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

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

[diff] [blame]

162

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

163

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

164

#

165

# - Simple to use and understand for most users

166

# - Flexible enough to meet unexpected needs

#

# # Overview

#

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

171

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

172

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

173

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

174

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

175

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

176

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

177

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

178

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

#

# # Language mapping

#

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

183

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

184

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

185

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

186

# 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

191

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

192

# consistent developer experience across different environments.

193

#

194

# Example uses of this error model include:

195

#

196

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

197

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

198

# errors.

199

#

200

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

201

# have a `Status` message for error reporting purpose.

202

#

203

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

204

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

205

# each error sub-response.

206

#

207

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

208

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

209

# represented directly using the `Status` message.

210

#

211

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

212

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

213

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

214

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

215

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

216

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

217

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

218

# common set of message types for APIs to use.

219

{

220

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

221

},

222

],

223

},

Sai Cheemalapati

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

[diff] [blame]

224

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

225

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

226

# available.

227

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

228

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

229

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

230

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

231

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

232

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

233

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

234

# `TakeSnapshotResponse`.

235

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

236

},

237

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

238

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

239

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

Jon Wayne Parrott

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

[diff] [blame]

}</pre>

</div>

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

Jon Wayne Parrott

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

[diff] [blame]

245

<pre>Deletes a managed service. This method will change the service to the

Jon Wayne Parrott

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

[diff] [blame]

246

`Soft-Delete` state for 30 days. Within this period, service producers may

247

call UndeleteService to restore the service.

248

After 30 days, the service will be permanently deleted.

249

250

Operation<response: google.protobuf.Empty>

251

252

Args:

253

serviceName: string, The name of the service. See the [overview](/service-management/overview)

254

for naming requirements. For example: `example.googleapis.com`. (required)

255

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

262

263

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

264

# network API call.

265

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

266

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

267

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

268

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

269

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

270

},

Sai Cheemalapati

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

[diff] [blame]

271

"error": { # The `Status` type defines a logical error model that is suitable for different # The error result of the operation in case of failure or cancellation.

Jon Wayne Parrott

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

[diff] [blame]

272

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

273

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

274

#

275

# - Simple to use and understand for most users

276

# - Flexible enough to meet unexpected needs

#

# # Overview

#

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

281

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

282

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

283

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

284

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

285

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

286

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

287

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

288

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

#

# # Language mapping

#

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

293

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

294

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

295

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

296

# 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

301

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

302

# consistent developer experience across different environments.

303

#

304

# Example uses of this error model include:

305

#

306

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

307

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

308

# errors.

309

#

310

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

311

# have a `Status` message for error reporting purpose.

312

#

313

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

314

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

315

# each error sub-response.

316

#

317

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

318

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

319

# represented directly using the `Status` message.

320

#

321

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

322

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

323

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

324

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

325

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

326

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

327

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

328

# common set of message types for APIs to use.

329

{

330

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

331

},

332

],

333

},

Sai Cheemalapati

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

[diff] [blame]

334

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

335

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

336

# available.

337

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

338

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

339

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

340

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

341

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

342

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

343

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

344

# `TakeSnapshotResponse`.

345

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

346

},

347

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

348

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

349

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

Jon Wayne Parrott

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

[diff] [blame]

}</pre>

</div>

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

Sai Cheemalapati

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

[diff] [blame]

355

<pre>Disables a service for a project, so it can no longer be

356

be used for the project. It prevents accidental usage that may cause

357

unexpected billing charges or security leaks.

Jon Wayne Parrott

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

[diff] [blame]

358

359

Operation<response: DisableServiceResponse>

360

361

Args:

362

serviceName: string, Name of the service to disable. Specifying an unknown service name

363

will cause the request to fail. (required)

364

body: object, The request body. (required)

365

The object takes the form of:

366

367

{ # Request message for DisableService method.

368

"consumerId": "A String", # The identity of consumer resource which service disablement will be

369

# applied to.

370

#

371

# The Google Service Management implementation accepts the following

Jon Wayne Parrott

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

[diff] [blame]

372

# forms:

373

# - "project:<project_id>"

Jon Wayne Parrott

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

[diff] [blame]

374

#

375

# Note: this is made compatible with

376

# google.api.servicecontrol.v1.Operation.consumer_id.

377

}

378

379

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

386

387

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

388

# network API call.

389

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

390

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

391

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

392

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

393

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

394

},

Sai Cheemalapati

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

[diff] [blame]

395

"error": { # The `Status` type defines a logical error model that is suitable for different # The error result of the operation in case of failure or cancellation.

Jon Wayne Parrott

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

[diff] [blame]

396

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

397

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

398

#

399

# - Simple to use and understand for most users

400

# - Flexible enough to meet unexpected needs

#

# # Overview

#

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

405

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

406

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

407

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

408

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

409

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

410

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

411

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

412

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

#

# # Language mapping

#

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

417

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

418

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

419

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

420

# 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

425

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

426

# consistent developer experience across different environments.

427

#

428

# Example uses of this error model include:

429

#

430

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

431

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

432

# errors.

433

#

434

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

435

# have a `Status` message for error reporting purpose.

436

#

437

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

438

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

439

# each error sub-response.

440

#

441

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

442

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

443

# represented directly using the `Status` message.

444

#

445

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

446

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

447

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

448

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

449

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

450

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

451

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

452

# common set of message types for APIs to use.

453

{

454

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

455

},

456

],

457

},

Sai Cheemalapati

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

[diff] [blame]

458

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

459

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

460

# available.

461

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

462

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

463

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

464

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

465

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

466

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

467

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

468

# `TakeSnapshotResponse`.

469

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

470

},

471

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

472

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

473

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

Jon Wayne Parrott

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

[diff] [blame]

}</pre>

</div>

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

Sai Cheemalapati

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

[diff] [blame]

479

<pre>Enables a service for a project, so it can be used

480

for the project. See

481

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

482

more information.

Jon Wayne Parrott

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

[diff] [blame]

483

484

Operation<response: EnableServiceResponse>

485

486

Args:

487

serviceName: string, Name of the service to enable. Specifying an unknown service name will

488

cause the request to fail. (required)

489

body: object, The request body. (required)

490

The object takes the form of:

491

492

{ # Request message for EnableService method.

493

"consumerId": "A String", # The identity of consumer resource which service enablement will be

494

# applied to.

495

#

496

# The Google Service Management implementation accepts the following

Jon Wayne Parrott

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

[diff] [blame]

497

# forms:

498

# - "project:<project_id>"

Jon Wayne Parrott

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

[diff] [blame]

499

#

500

# Note: this is made compatible with

501

# google.api.servicecontrol.v1.Operation.consumer_id.

502

}

503

504

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

511

512

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

513

# network API call.

514

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

515

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

516

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

517

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

518

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

519

},

Sai Cheemalapati

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

[diff] [blame]

520

"error": { # The `Status` type defines a logical error model that is suitable for different # The error result of the operation in case of failure or cancellation.

Jon Wayne Parrott

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

[diff] [blame]

521

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

522

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

523

#

524

# - Simple to use and understand for most users

525

# - Flexible enough to meet unexpected needs

#

# # Overview

#

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

530

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

531

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

532

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

533

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

534

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

535

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

536

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

537

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

#

# # Language mapping

#

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

542

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

543

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

544

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

545

# 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

550

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

551

# consistent developer experience across different environments.

552

#

553

# Example uses of this error model include:

554

#

555

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

556

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

557

# errors.

558

#

559

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

560

# have a `Status` message for error reporting purpose.

561

#

562

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

563

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

564

# each error sub-response.

565

#

566

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

567

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

568

# represented directly using the `Status` message.

569

#

570

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

571

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

572

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

573

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

574

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

575

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

576

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

577

# common set of message types for APIs to use.

578

{

579

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

580

},

581

],

582

},

Sai Cheemalapati

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

[diff] [blame]

583

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

584

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

585

# available.

586

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

587

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

588

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

589

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

590

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

591

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

592

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

593

# `TakeSnapshotResponse`.

594

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

595

},

596

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

597

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

598

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

Jon Wayne Parrott

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

[diff] [blame]

}</pre>

</div>

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

604

<pre>Generates and returns a report (errors, warnings and changes from

605

existing configurations) associated with

606

GenerateConfigReportRequest.new_value

607

608

If GenerateConfigReportRequest.old_value is specified,

609

GenerateConfigReportRequest will contain a single ChangeReport based on the

610

comparison between GenerateConfigReportRequest.new_value and

611

GenerateConfigReportRequest.old_value.

612

If GenerateConfigReportRequest.old_value is not specified, this method

613

will compare GenerateConfigReportRequest.new_value with the last pushed

614

service configuration.

615

616

Args:

617

body: object, The request body. (required)

618

The object takes the form of:

619

620

{ # Request message for GenerateConfigReport method.

621

"newConfig": { # Service configuration for which we want to generate the report.

622

# For this version of API, the supported types are

623

# google.api.servicemanagement.v1.ConfigRef,

624

# google.api.servicemanagement.v1.ConfigSource,

625

# and google.api.Service

626

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

627

},

628

"oldConfig": { # Service configuration against which the comparison will be done.

629

# For this version of API, the supported types are

630

# google.api.servicemanagement.v1.ConfigRef,

631

# google.api.servicemanagement.v1.ConfigSource,

632

# and google.api.Service

633

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

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

644

645

{ # Response message for GenerateConfigReport method.

646

"serviceName": "A String", # Name of the service this report belongs to.

647

"changeReports": [ # list of ChangeReport, each corresponding to comparison between two

648

# service configurations.

649

{ # Change report associated with a particular service configuration.

650

#

651

# It contains a list of ConfigChanges based on the comparison between

652

# two service configurations.

653

"configChanges": [ # List of changes between two service configurations.

654

# The changes will be alphabetically sorted based on the identifier

655

# of each change.

656

# A ConfigChange identifier is a dot separated path to the configuration.

657

# Example: visibility.rules[selector='LibraryService.CreateBook'].restriction

658

{ # Output generated from semantically comparing two versions of a service

659

# configuration.

660

#

661

# Includes detailed information about a field that have changed with

662

# applicable advice about potential consequences for the change, such as

663

# backwards-incompatibility.

664

"advices": [ # Collection of advice provided for this change, useful for determining the

665

# possible impact of this change.

666

{ # Generated advice about this change, used for providing more

667

# information about how a change will affect the existing service.

668

"description": "A String", # Useful description for why this advice was applied and what actions should

669

# be taken to mitigate any implied risks.

670

},

671

],

672

"changeType": "A String", # The type for this change, either ADDED, REMOVED, or MODIFIED.

673

"newValue": "A String", # Value of the changed object in the new Service configuration,

674

# in JSON format. This field will not be populated if ChangeType == REMOVED.

675

"oldValue": "A String", # Value of the changed object in the old Service configuration,

676

# in JSON format. This field will not be populated if ChangeType == ADDED.

677

"element": "A String", # Object hierarchy path to the change, with levels separated by a '.'

678

# character. For repeated fields, an applicable unique identifier field is

679

# used for the index (usually selector, name, or id). For maps, the term

680

# 'key' is used. If the field has no unique identifier, the numeric index

681

# is used.

682

# Examples:

683

# - visibility.rules[selector=="google.LibraryService.CreateBook"].restriction

684

# - quota.metric_rules[selector=="google"].metric_costs[key=="reads"].value

685

# - logging.producer_destinations[0]

},

],

},

],

"id": "A String", # ID of the service configuration this report belongs to.

691

"diagnostics": [ # Errors / Linter warnings associated with the service definition this

692

# report

693

# belongs to.

694

{ # Represents a diagnostic message (error or warning)

Sai Cheemalapati

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

[diff] [blame^]

695

"kind": "A String", # The kind of diagnostic information provided.

Jon Wayne Parrott

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

[diff] [blame]

696

"message": "A String", # Message describing the error or warning.

697

"location": "A String", # File name and line number of the error or warning.

},

],

}</pre>

</div>

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

Jon Wayne Parrott

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

[diff] [blame]

705

<pre>Gets a managed service. Authentication is required unless the service is

706

public.

Jon Wayne Parrott

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

[diff] [blame]

707

708

Args:

709

serviceName: string, The name of the service. See the `ServiceManager` overview for naming

710

requirements. For example: `example.googleapis.com`. (required)

711

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

718

719

{ # The full representation of a Service that is managed by

720

# Google Service Management.

721

"serviceName": "A String", # The name of the service. See the [overview](/service-management/overview)

722

# for naming requirements.

723

"producerProjectId": "A String", # ID of the project that produces and owns this service.

}</pre>

</div>

Sai Cheemalapati

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

[diff] [blame]

728

<code class="details" id="getConfig">getConfig(serviceName=None, configId=None, x__xgafv=None, view=None)</code>

Jon Wayne Parrott

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

[diff] [blame]

729

<pre>Gets a service configuration (version) for a managed service.

730

731

Args:

732

serviceName: string, The name of the service. See the [overview](/service-management/overview)

733

for naming requirements. For example: `example.googleapis.com`. (required)

Jon Wayne Parrott

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

[diff] [blame]

734

configId: string, The id of the service configuration resource.

Jon Wayne Parrott

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

[diff] [blame]

735

x__xgafv: string, V1 error format.

736

Allowed values

737

1 - v1 error format

738

2 - v2 error format

Sai Cheemalapati

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

[diff] [blame]

739

view: string, Specifies which parts of the Service Config should be returned in the

740

response.

Jon Wayne Parrott

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

[diff] [blame]

741

742

Returns:

743

An object of the form:

744

Sai Cheemalapati

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

[diff] [blame]

745

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

746

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

747

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

748

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

749

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

Jon Wayne Parrott

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

[diff] [blame]

#

# Example:

#

# type: google.api.Service

Sai Cheemalapati

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

[diff] [blame]

754

# config_version: 3

Jon Wayne Parrott

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

[diff] [blame]

755

# name: calendar.googleapis.com

756

# title: Google Calendar API

757

# apis:

Sai Cheemalapati

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

[diff] [blame]

758

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

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

[diff] [blame]

759

# authentication:

760

# providers:

761

# - id: google_calendar_auth

762

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

763

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

Jon Wayne Parrott

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

[diff] [blame]

764

# rules:

Jon Wayne Parrott

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

[diff] [blame]

765

# - selector: "*"

766

# requirements:

767

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

768

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

769

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

770

# monitoring, etc.

771

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

772

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

773

},

774

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

775

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

776

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

777

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

778

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

779

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

780

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

781

#

782

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

783

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

784

# by the API.

Sai Cheemalapati

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

[diff] [blame^]

785

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

786

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

787

# without any article or other determiners. For example,

788

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

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

[diff] [blame]

789

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

790

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

791

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

792

{ # A description of a label.

793

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

794

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

795

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

796

},

797

],

Sai Cheemalapati

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

[diff] [blame^]

798

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

799

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

800

# The maximum length of this value is 256 characters.

Jon Wayne Parrott

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

[diff] [blame]

801

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

802

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

803

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

804

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

805

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

806

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

Sai Cheemalapati

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

[diff] [blame]

807

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

808

# be used in documentation.

Jon Wayne Parrott

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

[diff] [blame]

809

},

810

],

811

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

812

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

813

#

814

# - name: library.googleapis.com/activity_history

815

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

816

# display_name: Activity

817

# labels:

818

# - key: /customer_id

819

# description: Identifier of a library customer

820

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

821

# Runtime requests that contain labels not specified here are

822

# considered invalid.

823

{ # A description of a label.

824

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

825

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

826

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

827

},

828

],

829

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

830

# the user interface and should be concise.

Sai Cheemalapati

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

[diff] [blame^]

831

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

832

# the documentation and can contain details.

Jon Wayne Parrott

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

[diff] [blame]

833

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

834

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

835

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

836

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

837

},

838

],

Sai Cheemalapati

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

[diff] [blame]

839

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

840

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

841

# generate one instead.

Jon Wayne Parrott

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

[diff] [blame]

842

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

843

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

844

#

845

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

846

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

847

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

848

#

849

# Refer to selector for syntax details.

850

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

851

# default depends on the deployment context.

852

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

853

},

854

],

855

},

Sai Cheemalapati

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

[diff] [blame]

856

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

Jon Wayne Parrott

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

[diff] [blame]

857

#

858

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

859

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

860

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

861

# to both producer and consumer projects, whereas the

862

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

863

# consumer project.

864

#

865

# monitored_resources:

866

# - type: library.googleapis.com/branch

867

# labels:

868

# - key: /city

869

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

870

# - key: /name

871

# description: The name of the branch.

872

# metrics:

873

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

878

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

883

# monitoring:

884

# producer_destinations:

885

# - monitored_resource: library.googleapis.com/branch

886

# metrics:

887

# - library.googleapis.com/book/returned_count

888

# consumer_destinations:

889

# - monitored_resource: library.googleapis.com/branch

890

# metrics:

891

# - library.googleapis.com/book/returned_count

892

# - library.googleapis.com/book/overdue_count

893

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

894

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

895

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

896

# one producer destination.

897

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

898

# or the consumer project).

899

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

900

# Service.monitored_resources section.

901

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

902

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

"A String",

],

},

],

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

908

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

909

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

910

# one consumer destination.

911

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

912

# or the consumer project).

913

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

914

# Service.monitored_resources section.

915

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

916

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

"A String",

],

},

],

},

Sai Cheemalapati

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

[diff] [blame]

922

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

923

#

924

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

925

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

926

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

927

# change the names of the system parameters.

928

"rules": [ # Define system parameters.

929

#

930

# The parameters defined here will override the default parameters

931

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

932

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

933

# and names is implementation-dependent.

934

#

935

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

943

#

944

#

945

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

950

# parameters:

951

# - name: api_key

952

# http_header: Api-Key1

953

# - name: api_key

954

# http_header: Api-Key2

955

#

956

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

957

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

958

# methods.

959

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

960

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

961

# names are used the behavior is implementation-dependent.

962

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

963

# parameter-dependent.

964

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

965

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

966

# is implementation-dependent.

967

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

968

# sensitive.

969

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

970

# insensitive.

971

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

972

},

973

],

974

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

975

# methods in all APIs.

976

#

977

# Refer to selector for syntax details.

978

},

979

],

980

},

Jon Wayne Parrott

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

[diff] [blame]

981

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

982

#

983

# Example for an API targeted for external use:

984

#

985

# name: calendar.googleapis.com

986

# authentication:

Jon Wayne Parrott

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

[diff] [blame]

987

# providers:

988

# - id: google_calendar_auth

989

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

990

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

Jon Wayne Parrott

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

[diff] [blame]

991

# rules:

992

# - selector: "*"

Jon Wayne Parrott

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

[diff] [blame]

993

# requirements:

994

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

995

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

996

#

997

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

998

{ # Authentication rules for the service.

999

#

1000

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

1001

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

1002

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

1003

# request.

1004

#

1005

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

1006

# ignored.

1007

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

1008

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

1009

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

1010

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

1011

#

1012

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

1013

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

1014

#

1015

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

1016

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

1017

# the OAuth scope across all of those APIs.

1018

#

1019

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

1020

# management about how developers will use them in practice.

1021

#

1022

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

1023

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

1024

# due to the backend requiring additional scopes or permissions.

1025

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

1026

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

#

# Example:

#

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

1031

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

1032

},

Sai Cheemalapati

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

[diff] [blame]

1033

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

1034

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

1035

#

1036

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

1037

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

1038

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

1039

# project.

Jon Wayne Parrott

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

[diff] [blame]

1040

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

1041

{ # User-defined authentication requirements, including support for

1042

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

1043

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

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

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

[diff] [blame]

1048

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

1049

# implemented and accepted in all the runtime components.

1050

#

1051

# The list of JWT

Jon Wayne Parrott

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

[diff] [blame]

1052

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

1053

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

1054

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

1055

# "https://Service_name/API_name"

1056

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

1057

# LibraryService API will only accept JWTs with the following audience

1058

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1063

# bookstore_web.apps.googleusercontent.com

1064

},

1065

],

Jon Wayne Parrott

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

[diff] [blame]

1066

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

1067

#

1068

# Refer to selector for syntax details.

1069

},

1070

],

1071

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

1072

{ # Configuration for an anthentication provider, including support for

1073

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

Jon Wayne Parrott

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

[diff] [blame]

1074

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

1075

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

1076

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

1077

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

1078

# "https://Service_name/API_name"

1079

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

1080

# LibraryService API will only accept JWTs with the following audience

1081

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1086

# bookstore_web.apps.googleusercontent.com

Sai Cheemalapati

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

[diff] [blame]

1087

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

1088

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

1089

# Optional if the key set document:

1090

# - can be retrieved from

1091

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

1092

# of the issuer.

1093

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

1094

#

1095

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

Jon Wayne Parrott

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

[diff] [blame]

1096

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

1097

# `AuthRequirement.provider_id`.

1098

#

1099

# Example: "bookstore_auth".

1100

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

1101

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

1102

# Usually a URL or an email address.

1103

#

1104

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

1105

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

},

],

},

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

1110

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

1111

#

1112

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

1113

{ # Usage configuration rules for the service.

1114

#

1115

# NOTE: Under development.

1116

#

1117

#

1118

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

1119

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

1120

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

1121

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

1122

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

1123

# allow/disallow unregistered calls.

1124

#

1125

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

1131

#

1132

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

#

# usage:

# rules:

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

1137

# allow_unregistered_calls: true

Sai Cheemalapati

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

[diff] [blame^]

1138

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

Jon Wayne Parrott

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

[diff] [blame]

1139

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

1140

# methods in all APIs.

1141

#

1142

# Refer to selector for syntax details.

Jon Wayne Parrott

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

[diff] [blame]

1143

},

1144

],

Jon Wayne Parrott

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

[diff] [blame]

1145

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

1146

# service producer.

1147

#

1148

# Google Service Management currently only supports

1149

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

1150

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

1151

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

1152

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

Jon Wayne Parrott

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

[diff] [blame]

1153

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

1154

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

1155

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

"A String",

],

},

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

1160

# influence interpretation of the configuration, for example, to

1161

# determine defaults. This is documented together with applicable

1162

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

1163

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

1164

# Members of this project can manage the service configuration,

1165

# manage consumption of the service, etc.

1166

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

1167

# HttpRule, each specifying the mapping of an RPC method

1168

# to one or more HTTP REST API methods.

1169

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

1170

#

1171

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

1172

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

1173

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

1174

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

1175

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

1176

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

1177

# for details.

1178

#

1179

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

1180

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

1181

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

1182

# operation on a resource collection of messages:

1183

#

Jon Wayne Parrott

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

[diff] [blame]

1184

#

1185

# service Messaging {

1186

# rpc GetMessage(GetMessageRequest) returns (Message) {

1187

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

1188

# }

1189

# }

1190

# message GetMessageRequest {

1191

# message SubMessage {

1192

# string subfield = 1;

1193

# }

1194

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

1195

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

1196

# }

1197

# message Message {

1198

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

1199

# }

1200

#

1201

# The same http annotation can alternatively be expressed inside the

1202

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

1207

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

Jon Wayne Parrott

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

[diff] [blame]

1208

#

1209

# This definition enables an automatic, bidrectional mapping of HTTP

1210

# JSON to RPC. Example:

#

# HTTP | RPC

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

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

1215

#

1216

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

1217

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

1218

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

1219

#

1220

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

1221

# pattern automatically become (optional) HTTP query

1222

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

1223

#

Jon Wayne Parrott

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

[diff] [blame]

1224

#

1225

# message GetMessageRequest {

1226

# message SubMessage {

1227

# string subfield = 1;

1228

# }

1229

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

1230

# int64 revision = 2; // becomes a parameter

1231

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

1232

# }

1233

#

Jon Wayne Parrott

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

[diff] [blame]

1234

#

1235

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

1240

#

1241

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

1242

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

1243

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

1244

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

1245

#

1246

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

1247

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

1248

# message resource collection:

1249

#

Jon Wayne Parrott

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

[diff] [blame]

1250

#

1251

# service Messaging {

1252

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

1253

# option (google.api.http) = {

1254

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

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

1260

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

1261

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

1262

# }

1263

#

Jon Wayne Parrott

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

[diff] [blame]

1264

#

1265

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

1266

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

1267

# protos JSON encoding:

#

# HTTP | RPC

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

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

1272

#

1273

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

1274

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

1275

# request body. This enables the following alternative definition of

1276

# the update method:

1277

#

Jon Wayne Parrott

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

[diff] [blame]

1278

# service Messaging {

1279

# rpc UpdateMessage(Message) returns (Message) {

1280

# option (google.api.http) = {

1281

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

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

1288

# string text = 2;

1289

# }

1290

#

Jon Wayne Parrott

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

[diff] [blame]

1291

#

1292

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

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

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

1297

#

1298

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

1299

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

1300

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

1301

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

1302

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

1303

#

1304

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

1305

# the `additional_bindings` option. Example:

1306

#

Jon Wayne Parrott

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

[diff] [blame]

1307

# service Messaging {

1308

# rpc GetMessage(GetMessageRequest) returns (Message) {

1309

# option (google.api.http) = {

1310

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

1311

# additional_bindings {

1312

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

1313

# }

1314

# };

Jon Wayne Parrott

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

[diff] [blame]

1315

# }

Jon Wayne Parrott

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

[diff] [blame]

1316

# }

1317

# message GetMessageRequest {

1318

# string message_id = 1;

1319

# string user_id = 2;

1320

# }

1321

#

Jon Wayne Parrott

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

[diff] [blame]

1322

#

1323

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

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

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

1329

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

1330

#

1331

# # Rules for HTTP mapping

1332

#

1333

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

1334

# to the request message are as follows:

1335

#

1336

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

1337

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

1338

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

1339

# request) can be classified into three types:

1340

# (a) Matched in the URL template.

1341

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

1342

# else everything under the body field)

1343

# (c) All other fields.

1344

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

1345

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

1346

#

1347

# The syntax of the path template is as follows:

1348

#

1349

# Template = "/" Segments [ Verb ] ;

1350

# Segments = Segment { "/" Segment } ;

1351

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

1352

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

1353

# FieldPath = IDENT { "." IDENT } ;

1354

# Verb = ":" LITERAL ;

1355

#

1356

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

1357

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

1358

# Expansion.

1359

#

1360

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

1361

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

Jon Wayne Parrott

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

[diff] [blame]

1362

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

Jon Wayne Parrott

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

[diff] [blame]

1363

#

1364

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

1365

#

1366

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

1367

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

1368

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

1369

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

1370

#

1371

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

1372

# repeated fields or map fields.

1373

#

1374

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

1375

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

1376

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

1377

# content to Web (HTML) clients.

1378

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

1379

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

1380

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

Jon Wayne Parrott

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

[diff] [blame]

1381

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

Sai Cheemalapati

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

[diff] [blame^]

1382

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

1383

#

1384

# Refer to selector for syntax details.

Jon Wayne Parrott

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

[diff] [blame]

1385

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

Sai Cheemalapati

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

[diff] [blame]

1386

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

1387

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

1388

# API to your configuration.

1389

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

1390

# your configuration for Bytestream methods.

Jon Wayne Parrott

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

[diff] [blame]

1391

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

Sai Cheemalapati

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

[diff] [blame]

1392

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

1393

#

1394

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

Jon Wayne Parrott

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

[diff] [blame]

1395

},

1396

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

1397

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

1398

# the nesting may only be one level deep).

1399

# Object with schema name: HttpRule

1400

],

Sai Cheemalapati

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

[diff] [blame]

1401

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

1402

# Bytestream, add instead

Jon Wayne Parrott

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

[diff] [blame]

1403

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

Sai Cheemalapati

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

[diff] [blame]

1404

# configuration for Bytestream methods.

1405

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

1406

# your configuration for Bytestream methods.

Jon Wayne Parrott

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

[diff] [blame]

1407

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

Sai Cheemalapati

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

[diff] [blame]

1408

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

1409

#

1410

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

Jon Wayne Parrott

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

[diff] [blame]

1411

},

Sai Cheemalapati

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

[diff] [blame^]

1412

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

1413

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

1414

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

1415

},

Jon Wayne Parrott

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

[diff] [blame]

1416

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

1417

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

1418

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

1419

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

1420

# at the top-level of response message type.

1421

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

Jon Wayne Parrott

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

[diff] [blame]

1422

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

Sai Cheemalapati

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

[diff] [blame^]

1423

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

Jon Wayne Parrott

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

[diff] [blame]

1424

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

},

],

},

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

1429

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

1430

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

1431

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

1432

# which cannot be resolved against the associated IDL files.

1433

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

1434

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

1435

{ # Method represents a method of an api.

1436

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

1437

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

1438

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

1439

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

1440

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

1441

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

1442

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

1443

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

1444

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1445

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

1446

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

1447

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

1448

# `"google.api.http"`.

1449

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

1450

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

1451

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

1452

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1453

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

},

},

],

},

],

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

1460

# message.

1461

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

1462

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

1463

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

1464

},

1465

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

1466

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

1467

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

1468

# and options are inherited as follows:

1469

#

1470

# - If after comment and whitespace stripping, the documentation

1471

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

1472

# from the original method.

1473

#

1474

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

1475

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

1476

# inherited.

1477

#

1478

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

1479

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

1480

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

1481

#

1482

# Example of a simple mixin:

1483

#

1484

# package google.acl.v1;

1485

# service AccessControl {

1486

# // Get the underlying ACL object.

1487

# rpc GetAcl(GetAclRequest) returns (Acl) {

1488

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

# }

# }

#

# package google.storage.v2;

1493

# service Storage {

1494

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

1495

#

1496

# // Get a data record.

1497

# rpc GetData(GetDataRequest) returns (Data) {

1498

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

# }

# }

#

# Example of a mixin configuration:

1503

#

1504

# apis:

1505

# - name: google.storage.v2.Storage

1506

# mixins:

1507

# - name: google.acl.v1.AccessControl

1508

#

1509

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

1510

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

1511

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

1512

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

1513

# documentation and annotations as follows:

1514

#

1515

# service Storage {

1516

# // Get the underlying ACL object.

1517

# rpc GetAcl(GetAclRequest) returns (Acl) {

1518

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

# }

# ...

# }

#

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

1524

#

1525

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

1526

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

1527

#

1528

# apis:

1529

# - name: google.storage.v2.Storage

1530

# mixins:

1531

# - name: google.acl.v1.AccessControl

1532

# root: acls

1533

#

1534

# This implies the following inherited HTTP annotation:

1535

#

1536

# service Storage {

1537

# // Get the underlying ACL object.

1538

# rpc GetAcl(GetAclRequest) returns (Acl) {

1539

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

# }

# ...

# }

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

1544

# are rooted.

1545

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

1546

},

1547

],

1548

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

1549

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

1550

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

1551

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

1552

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

1553

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

1554

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

1555

# provided here.

1556

#

1557

# The versioning schema uses [semantic

1558

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

1559

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

1560

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

1561

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

1562

# chosen based on the product plan.

1563

#

1564

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

1565

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

1566

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

1567

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

1568

# experimental, none-GA apis.

1569

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

1570

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

1571

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1572

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

1573

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

1574

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

1575

# `"google.api.http"`.

1576

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

1577

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

1578

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

1579

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1580

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

},

},

],

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

1585

# followed by the api's simple name.

1586

},

1587

],

1588

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

1589

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

1597

# - google.foo.v1.AnotherError

1598

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

1599

#

1600

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

1601

{ # A custom error rule.

1602

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

1603

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

1604

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

1605

#

1606

# Refer to selector for syntax details.

1607

},

1608

],

1609

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

"A String",

],

},

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

1614

# elements. Restrictions are specified using visibility labels

1615

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

1616

#

1617

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

1618

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

1619

# elements, plus any unrestricted elements.

1620

#

1621

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

1622

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

1629

# restriction: TRUSTED_TESTER

1630

# - selector: google.calendar.Calendar.Delegate

1631

# restriction: GOOGLE_INTERNAL

1632

#

1633

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

1634

# EnhancedSearch and Delegate.

1635

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

1636

#

1637

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

1638

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

1639

# element.

Sai Cheemalapati

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

[diff] [blame]

1640

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

1641

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

Jon Wayne Parrott

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

[diff] [blame]

1642

#

1643

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

1644

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

1651

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

1652

#

1653

# Removing GOOGLE_INTERNAL from this restriction will break clients that

1654

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

1655

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

1656

#

1657

# Refer to selector for syntax details.

},

],

},

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

Jon Wayne Parrott

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

[diff] [blame]

1662

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

1663

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

1664

# existing data unusable.

Jon Wayne Parrott

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

[diff] [blame]

1665

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

1666

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

Sai Cheemalapati

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

[diff] [blame]

1667

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

1668

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

1669

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

1670

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

1671

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

1672

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

1673

#

1674

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

Jon Wayne Parrott

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

[diff] [blame]

1675

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

Sai Cheemalapati

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

[diff] [blame]

1676

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

Jon Wayne Parrott

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

[diff] [blame]

1677

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

Sai Cheemalapati

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

[diff] [blame]

1678

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

Jon Wayne Parrott

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

[diff] [blame]

1679

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

1680

# instance of this metric type. For example, the

1681

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

1682

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

1683

# you can look at latencies for successful responses or just

1684

# for responses that failed.

Jon Wayne Parrott

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

[diff] [blame]

1685

{ # A description of a label.

1686

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

1687

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

1688

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

1689

},

1690

],

Jon Wayne Parrott

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

[diff] [blame]

1691

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

Sai Cheemalapati

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

[diff] [blame]

1692

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

Jon Wayne Parrott

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

[diff] [blame]

1693

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

1694

# grouping. For example:

Jon Wayne Parrott

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

[diff] [blame]

1695

#

Jon Wayne Parrott

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

[diff] [blame]

1696

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

1697

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

Jon Wayne Parrott

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

[diff] [blame]

1698

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

1699

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

1700

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

1701

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

1702

#

1703

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

1718

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

1719

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

1720

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

1721

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

1722

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

1723

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

1724

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

1725

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

1726

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

1727

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

1728

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

1729

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

1730

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

1731

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

1732

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

1733

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

#

# **Grammar**

#

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

1738

#

1739

# The grammar also includes these connectors:

1740

#

1741

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

1742

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

1743

#

1744

# The grammar for a unit is as follows:

1745

#

1746

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

1747

#

1748

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

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

1758

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

1759

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

1760

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

1761

# containing '{' or '}'.

Sai Cheemalapati

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

[diff] [blame]

1762

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

Jon Wayne Parrott

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

[diff] [blame]

1763

},

1764

],

1765

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

1766

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

1767

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

1768

# should be listed here by name. Example:

1769

#

1770

# enums:

1771

# - name: google.someapi.v1.SomeEnum

1772

{ # Enum type definition.

1773

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

1774

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

1775

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

1776

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

1777

},

Sai Cheemalapati

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

[diff] [blame^]

1778

"enumvalue": [ # Enum value definitions.

1779

{ # Enum value definition.

1780

"number": 42, # Enum value number.

1781

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

1782

"options": [ # Protocol buffer options.

1783

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

1784

# enumeration, etc.

1785

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

1786

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

1787

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

1788

# `"google.api.http"`.

1789

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

1790

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

1791

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

1792

# value using the google.protobuf.Int32Value type.

1793

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

},

},

],

},

],

Jon Wayne Parrott

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

[diff] [blame]

1799

"options": [ # Protocol buffer options.

1800

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

1801

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1802

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

1803

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

1804

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

1805

# `"google.api.http"`.

1806

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

1807

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

1808

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

1809

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1810

"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^]

1815

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1816

},

1817

],

1818

"types": [ # A list of all proto message types included in this API service.

1819

# Types referenced directly or indirectly by the `apis` are

1820

# automatically included. Messages which are not referenced but

1821

# shall be included, such as types used by the `google.protobuf.Any` type,

1822

# should be listed here by name. Example:

1823

#

1824

# types:

1825

# - name: google.protobuf.Int32

1826

{ # A protocol buffer message type.

1827

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

1828

"A String",

1829

],

1830

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1831

"fields": [ # The list of fields.

1832

{ # A single field of a message type.

1833

"kind": "A String", # The field type.

1834

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

1835

# types. The first type has index 1; zero means the type is not in the list.

1836

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

1837

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

1838

"name": "A String", # The field name.

1839

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

1840

"jsonName": "A String", # The field JSON name.

1841

"number": 42, # The field number.

1842

"cardinality": "A String", # The field cardinality.

1843

"options": [ # The protocol buffer options.

1844

{ # A protocol buffer option, which can be attached to a message, field,

1845

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1846

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1847

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1848

# For custom options, it should be the fully-qualified name. For example,

1849

# `"google.api.http"`.

1850

"value": { # The option's value packed in an Any message. If the value is a primitive,

1851

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1852

# should be used. If the value is an enum, it should be stored as an int32

1853

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1854

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

1859

},

1860

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1861

"syntax": "A String", # The source syntax.

1862

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

1863

# protobuf element, like the file in which it is defined.

1864

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

1865

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

1866

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1867

"options": [ # The protocol buffer options.

1868

{ # A protocol buffer option, which can be attached to a message, field,

1869

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1870

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1871

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1872

# For custom options, it should be the fully-qualified name. For example,

1873

# `"google.api.http"`.

1874

"value": { # The option's value packed in an Any message. If the value is a primitive,

1875

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1876

# should be used. If the value is an enum, it should be stored as an int32

1877

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1878

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1884

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1885

#

1886

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1887

# producer and consumer projects. In the example, the `activity_history`

1888

# log is sent to both the producer and consumer projects, whereas the

1889

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1890

#

1891

# monitored_resources:

1892

# - type: library.googleapis.com/branch

1893

# labels:

1894

# - key: /city

1895

# description: The city where the library branch is located in.

1896

# - key: /name

1897

# description: The name of the branch.

1898

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1899

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1900

# labels:

1901

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1902

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1903

# logging:

1904

# producer_destinations:

1905

# - monitored_resource: library.googleapis.com/branch

1906

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1907

# - activity_history

1908

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1909

# consumer_destinations:

1910

# - monitored_resource: library.googleapis.com/branch

1911

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1912

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1913

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

1914

# There can be multiple producer destinations, each one must have a

1915

# different monitored resource type. A log can be used in at most

1916

# one producer destination.

1917

{ # Configuration of a specific logging destination (the producer project

1918

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1919

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1920

# Service.monitored_resources section.

1921

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1922

# be defined in the Service.logs section. If the log name is

1923

# not a domain scoped name, it will be automatically prefixed with

1924

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

1930

# There can be multiple consumer destinations, each one must have a

1931

# different monitored resource type. A log can be used in at most

1932

# one consumer destination.

1933

{ # Configuration of a specific logging destination (the producer project

1934

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1935

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1936

# Service.monitored_resources section.

1937

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1938

# be defined in the Service.logs section. If the log name is

1939

# not a domain scoped name, it will be automatically prefixed with

1940

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

1947

# e.g. `calendar.googleapis.com`.

1948

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

1949

#

1950

# Example:

1951

# <pre><code>documentation:

1952

# summary: >

1953

# The Google Calendar API gives access

1954

# to most calendar features.

1955

# pages:

1956

# - name: Overview

1957

# content: (== include google/foo/overview.md ==)

1958

# - name: Tutorial

1959

# content: (== include google/foo/tutorial.md ==)

1960

# subpages;

1961

# - name: Java

1962

# content: (== include google/foo/tutorial_java.md ==)

1963

# rules:

1964

# - selector: google.calendar.Calendar.Get

1965

# description: >

1966

# ...

1967

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1972

# standard markdown features, definition lists, tables and fenced

1973

# code blocks are supported. Section headers can be provided and are

1974

# interpreted relative to the section nesting of the context where

1975

# a documentation fragment is embedded.

1976

#

1977

# Documentation from the IDL is merged with documentation defined

1978

# via the config at normalization time, where documentation provided

1979

# by config rules overrides IDL provided.

1980

#

1981

# A number of constructs specific to the API platform are supported

1982

# in documentation text.

1983

#

1984

# In order to reference a proto element, the following

1985

# notation can be used:

1986

# <pre><code>[fully.qualified.proto.name][]</code></pre>

1987

# To override the display text used for the link, this can be used:

1988

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

1989

# Text can be excluded from doc using the following notation:

1990

# <pre><code>(-- internal comment --)</code></pre>

1991

# Comments can be made conditional using a visibility label. The below

1992

# text will be only rendered if the `BETA` label is available:

1993

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

1994

# A few directives are available in documentation. Note that

1995

# directives must appear on a single line to be properly

1996

# identified. The `include` directive includes a markdown file from

1997

# an external source:

1998

# <pre><code>(== include path/to/file ==)</code></pre>

1999

# The `resource_for` directive marks a message to be the resource of

2000

# a collection in REST view. If it is not specified, tools attempt

2001

# to infer the resource from the operations in a collection:

2002

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

2003

# The directive `suppress_warning` does not directly affect documentation

2004

# and is documented together with service config validation.

2005

"rules": [ # A list of documentation rules that apply to individual API elements.

2006

#

2007

# **NOTE:** All service configuration rules follow "last one wins" order.

2008

{ # A documentation rule provides information about individual API elements.

2009

"description": "A String", # Description of the selected API(s).

2010

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

2011

# element is marked as `deprecated`.

2012

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

2013

# qualified name of the element which may end in "*", indicating a wildcard.

2014

# Wildcards are only allowed at the end and for a whole component of the

2015

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

2016

# specify a default for all applicable elements, the whole pattern "*"

2017

# is used.

2018

},

2019

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2020

"documentationRootUrl": "A String", # The URL to the root of documentation.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame^]

2021

"overview": "A String", # Declares a single overview page. For example:

2022

# <pre><code>documentation:

2023

# summary: ...

2024

# overview: (== include overview.md ==)

2025

# </code></pre>

2026

# This is a shortcut for the following declaration (using pages style):

2027

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

2032

# </code></pre>

2033

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2034

"pages": [ # The top level pages for the documentation set.

2035

{ # Represents a documentation page. A page can contain subpages to represent

2036

# nested documentation set structure.

2037

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

2038

# to include content from a Markdown file.

2039

"subpages": [ # Subpages of this page. The order of subpages specified here will be

2040

# honored in the generated docset.

2041

# Object with schema name: Page

2042

],

2043

"name": "A String", # The name of the page. It will be used as an identity of the page to

2044

# generate URI of the page, text of the link to this page in navigation,

2045

# etc. The full page name (start from the root page name to this page

2046

# concatenated with `.`) can be used as reference to the page in your

2047

# documentation. For example:

2048

# <pre><code>pages:

2049

# - name: Tutorial

2050

# content: (== include tutorial.md ==)

2051

# subpages:

2052

# - name: Java

2053

# content: (== include tutorial_java.md ==)

2054

# </code></pre>

2055

# You can reference `Java` page using Markdown reference link syntax:

2056

# `Java`.

2057

},

2058

],

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame^]

2059

"summary": "A String", # A short summary of what the service does. Can only be provided by

2060

# plain text.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2061

},

2062

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

2063

"sourceFiles": [ # All files used during config generation.

2064

{

2065

"a_key": "", # Properties of the object. Contains field @type with type URL.

2066

},

2067

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2068

},

2069

"systemTypes": [ # A list of all proto message types included in this API service.

2070

# It serves similar purpose as [google.api.Service.types], except that

2071

# these types are not needed by user-defined APIs. Therefore, they will not

2072

# show up in the generated discovery doc. This field should only be used

2073

# to define system APIs in ESF.

2074

{ # A protocol buffer message type.

2075

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2076

"A String",

2077

],

2078

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2079

"fields": [ # The list of fields.

2080

{ # A single field of a message type.

2081

"kind": "A String", # The field type.

2082

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2083

# types. The first type has index 1; zero means the type is not in the list.

2084

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2085

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2086

"name": "A String", # The field name.

2087

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2088

"jsonName": "A String", # The field JSON name.

2089

"number": 42, # The field number.

2090

"cardinality": "A String", # The field cardinality.

2091

"options": [ # The protocol buffer options.

2092

{ # A protocol buffer option, which can be attached to a message, field,

2093

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2094

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2095

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2096

# For custom options, it should be the fully-qualified name. For example,

2097

# `"google.api.http"`.

2098

"value": { # The option's value packed in an Any message. If the value is a primitive,

2099

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2100

# should be used. If the value is an enum, it should be stored as an int32

2101

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2102

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2107

},

2108

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2109

"syntax": "A String", # The source syntax.

2110

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2111

# protobuf element, like the file in which it is defined.

2112

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2113

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2114

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2115

"options": [ # The protocol buffer options.

2116

{ # A protocol buffer option, which can be attached to a message, field,

2117

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2118

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2119

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2120

# For custom options, it should be the fully-qualified name. For example,

2121

# `"google.api.http"`.

2122

"value": { # The option's value packed in an Any message. If the value is a primitive,

2123

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2124

# should be used. If the value is an enum, it should be stored as an int32

2125

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2126

"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

2141

# - google.rpc.context.OriginContext

2142

#

2143

# The above specifies that all methods in the API request

2144

# `google.rpc.context.ProjectContext` and

2145

# `google.rpc.context.OriginContext`.

2146

#

2147

# Available context types are defined in package

2148

# `google.rpc.context`.

2149

"rules": [ # A list of RPC context rules that apply to individual API methods.

2150

#

2151

# **NOTE:** All service configuration rules follow "last one wins" order.

2152

{ # A context rule provides information about the context for an individual API

2153

# element.

2154

"provided": [ # A list of full type names of provided contexts.

2155

"A String",

2156

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2157

"selector": "A String", # Selects the methods to which this rule applies.

2158

#

2159

# Refer to selector for syntax details.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame^]

2160

"requested": [ # A list of full type names of requested contexts.

2161

"A String",

2162

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2163

},

2164

],

2165

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2166

"title": "A String", # The product title associated with this service.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2167

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

2168

# with the same name as the service is automatically generated to service all

2169

# defined APIs.

2170

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

2171

# A service may expose any number of endpoints, and all endpoints share the

2172

# same service configuration, such as quota configuration and monitoring

2173

# configuration.

2174

#

2175

# Example service configuration:

2176

#

2177

# name: library-example.googleapis.com

2178

# endpoints:

2179

# # Below entry makes 'google.example.library.v1.Library'

2180

# # API be served from endpoint address library-example.googleapis.com.

2181

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

2182

# # it to decide whether the subsequent cross-origin request is

2183

# # allowed to proceed.

2184

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2185

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2186

"allowCors": True or False, # Allowing

2187

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

2188

# cross-domain traffic, would allow the backends served from this endpoint to

2189

# receive and respond to HTTP OPTIONS requests. The response will be used by

2190

# the browser to determine whether the subsequent cross-origin request is

2191

# allowed to proceed.

2192

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

2193

# please specify multiple google.api.Endpoint for each of the intented

2194

# alias.

2195

#

2196

# Additional names that this endpoint will be hosted on.

2197

"A String",

2198

],

2199

"features": [ # The list of features enabled on this endpoint.

2200

"A String",

2201

],

2202

"name": "A String", # The canonical name of this endpoint.

2203

"apis": [ # The list of APIs served by this endpoint.

"A String",

],

},

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2208

"experimental": { # Experimental service configuration. These configuration options can # Experimental configuration.

2209

# only be used by whitelisted users.

2210

"authorization": { # Configuration of authorization. # Authorization configuration.

2211

#

2212

# This section determines the authorization provider, if unspecified, then no

2213

# authorization check will be done.

#

# Example:

#

# experimental:

# authorization:

# provider: firebaserules.googleapis.com

2220

"provider": "A String", # The name of the authorization provider, such as

2221

# firebaserules.googleapis.com.

2222

},

2223

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

}</pre>

</div>

<code class="details" id="getIamPolicy">getIamPolicy(resource=None, body, x__xgafv=None)</code>

2229

<pre>Gets the access control policy for a resource.

2230

Returns an empty policy if the resource exists and does not have a policy

set.

Args:

resource: string, REQUIRED: The resource for which the policy is being requested.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2235

See the operation documentation for the appropriate value for this field. (required)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2236

body: object, The request body. (required)

2237

The object takes the form of:

2238

2239

{ # Request message for `GetIamPolicy` method.

2240

}

2241

2242

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2249

2250

{ # Defines an Identity and Access Management (IAM) policy. It is used to

2251

# specify access control policies for Cloud Platform resources.

2252

#

2253

#

2254

# A `Policy` consists of a list of `bindings`. A `Binding` binds a list of

2255

# `members` to a `role`, where the members can be user accounts, Google groups,

2256

# Google domains, and service accounts. A `role` is a named list of permissions

# defined by IAM.

#

# **Example**

#

# {

# "bindings": [

# {

# "role": "roles/owner",

2265

# "members": [

2266

# "user:mike@example.com",

2267

# "group:admins@example.com",

2268

# "domain:google.com",

2269

# "serviceAccount:my-other-app@appspot.gserviceaccount.com",

# ]

# },

# {

# "role": "roles/viewer",

2274

# "members": ["user:sean@example.com"]

# }

# ]

# }

#

# For a description of IAM and its features, see the

2280

# [IAM developer's guide](https://cloud.google.com/iam).

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2281

"auditConfigs": [ # Specifies cloud audit logging configuration for this policy.

2282

{ # Specifies the audit configuration for a service.

2283

# The configuration determines which permission types are logged, and what

2284

# identities, if any, are exempted from logging.

2285

# An AuditConifg must have one or more AuditLogConfigs.

2286

#

2287

# If there are AuditConfigs for both `allServices` and a specific service,

2288

# the union of the two AuditConfigs is used for that service: the log_types

2289

# specified in each AuditConfig are enabled, and the exempted_members in each

2290

# AuditConfig are exempted.

2291

# Example Policy with multiple AuditConfigs:

# {

# "audit_configs": [

# {

# "service": "allServices"

2296

# "audit_log_configs": [

2297

# {

2298

# "log_type": "DATA_READ",

2299

# "exempted_members": [

2300

# "user:foo@gmail.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

2305

# },

2306

# {

2307

# "log_type": "ADMIN_READ",

# }

# ]

# },

# {

# "service": "fooservice@googleapis.com"

2313

# "audit_log_configs": [

2314

# {

2315

# "log_type": "DATA_READ",

2316

# },

2317

# {

2318

# "log_type": "DATA_WRITE",

2319

# "exempted_members": [

2320

# "user:bar@gmail.com"

# ]

# }

# ]

# }

# ]

# }

# For fooservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ

2328

# logging. It also exempts foo@gmail.com from DATA_READ logging, and

2329

# bar@gmail.com from DATA_WRITE logging.

2330

"exemptedMembers": [

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2331

"A String",

2332

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2333

"auditLogConfigs": [ # The configuration for logging of each type of permission.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2334

# Next ID: 4

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2335

{ # Provides the configuration for logging a type of permissions.

# Example:

#

# {

# "audit_log_configs": [

2340

# {

2341

# "log_type": "DATA_READ",

2342

# "exempted_members": [

2343

# "user:foo@gmail.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

# }

# ]

# }

#

# This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting

2353

# foo@gmail.com from DATA_READ logging.

2354

"exemptedMembers": [ # Specifies the identities that do not cause logging for this type of

2355

# permission.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2356

# Follows the same format of Binding.members.

2357

"A String",

2358

],

2359

"logType": "A String", # The log type that this config enables.

2360

},

2361

],

2362

"service": "A String", # Specifies a service that will be enabled for audit logging.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame^]

2363

# For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2364

# `allServices` is a special value that covers all services.

2365

},

2366

],

2367

"rules": [ # If more than one rule is specified, the rules are applied in the following

2368

# manner:

2369

# - All matching LOG rules are always applied.

2370

# - If any DENY/DENY_WITH_LOG rule matches, permission is denied.

2371

# Logging will be applied if one or more matching rule requires logging.

2372

# - Otherwise, if any ALLOW/ALLOW_WITH_LOG rule matches, permission is

2373

# granted.

2374

# Logging will be applied if one or more matching rule requires logging.

2375

# - Otherwise, if no rule applies, permission is denied.

2376

{ # A rule to be applied in a Policy.

2377

"notIn": [ # If one or more 'not_in' clauses are specified, the rule matches

2378

# if the PRINCIPAL/AUTHORITY_SELECTOR is in none of the entries.

2379

# The format for in and not_in entries is the same as for members in a

2380

# Binding (see google/iam/v1/policy.proto).

2381

"A String",

2382

],

2383

"description": "A String", # Human-readable description of the rule.

2384

"in": [ # If one or more 'in' clauses are specified, the rule matches if

2385

# the PRINCIPAL/AUTHORITY_SELECTOR is in at least one of these entries.

2386

"A String",

2387

],

2388

"action": "A String", # Required

2389

"conditions": [ # Additional restrictions that must be met

2390

{ # A condition to be met.

2391

"iam": "A String", # Trusted attributes supplied by the IAM system.

2392

"svc": "A String", # Trusted attributes discharged by the service.

2393

"value": "A String", # DEPRECATED. Use 'values' instead.

2394

"sys": "A String", # Trusted attributes supplied by any service that owns resources and uses

2395

# the IAM system for access control.

2396

"values": [ # The objects of the condition. This is mutually exclusive with 'value'.

2397

"A String",

2398

],

2399

"op": "A String", # An operator to apply the subject with.

2400

},

2401

],

2402

"logConfig": [ # The config returned to callers of tech.iam.IAM.CheckPolicy for any entries

2403

# that match the LOG action.

2404

{ # Specifies what kind of log the caller must write

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2405

"counter": { # Options for counters # Counter options.

2406

"field": "A String", # The field value to attribute.

2407

"metric": "A String", # The metric to update.

2408

},

2409

"dataAccess": { # Write a Data Access (Gin) log # Data access options.

2410

},

2411

"cloudAudit": { # Write a Cloud Audit log # Cloud audit options.

},

},

],

"permissions": [ # A permission is a string of form '<service>.<resource type>.<verb>'

2416

# (e.g., 'storage.buckets.list'). A value of '*' matches all permissions,

2417

# and a verb part of '*' (e.g., 'storage.buckets.*') matches all verbs.

"A String",

],

},

],

"version": 42, # Version of the `Policy`. The default version is 0.

2423

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

2424

# prevent simultaneous updates of a policy from overwriting each other.

2425

# It is strongly suggested that systems make use of the `etag` in the

2426

# read-modify-write cycle to perform policy updates in order to avoid race

2427

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

2428

# systems are expected to put that etag in the request to `setIamPolicy` to

2429

# ensure that their change will be applied to the same version of the policy.

2430

#

2431

# If no `etag` is provided in the call to `setIamPolicy`, then the existing

2432

# policy is overwritten blindly.

2433

"bindings": [ # Associates a list of `members` to a `role`.

2434

# Multiple `bindings` must not be specified for the same `role`.

2435

# `bindings` with no members will result in an error.

2436

{ # Associates `members` with a `role`.

2437

"role": "A String", # Role that is assigned to `members`.

2438

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

2439

# Required

2440

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

2441

# `members` can have the following values:

2442

#

2443

# * `allUsers`: A special identifier that represents anyone who is

2444

# on the internet; with or without a Google account.

2445

#

2446

# * `allAuthenticatedUsers`: A special identifier that represents anyone

2447

# who is authenticated with a Google account or a service account.

2448

#

2449

# * `user:{emailid}`: An email address that represents a specific Google

2450

# account. For example, `alice@gmail.com` or `joe@example.com`.

2451

#

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2452

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2453

# * `serviceAccount:{emailid}`: An email address that represents a service

2454

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

2455

#

2456

# * `group:{emailid}`: An email address that represents a Google group.

2457

# For example, `admins@example.com`.

2458

#

2459

# * `domain:{domain}`: A Google Apps domain name that represents all the

2460

# users of that domain. For example, `google.com` or `example.com`.

#

"A String",

],

},

],

"iamOwned": True or False,

}</pre>

</div>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2471

<code class="details" id="list">list(producerProjectId=None, pageSize=None, pageToken=None, consumerId=None, x__xgafv=None)</code>

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2472

<pre>Lists managed services.

2473

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2474

Returns all public services. For authenticated users, also returns all

2475

services the calling user has "servicemanagement.services.get" permission

2476

for.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2477

2478

**BETA:** If the caller specifies the `consumer_id`, it returns only the

2479

services enabled on the consumer. The `consumer_id` must have the format

2480

of "project:{PROJECT-ID}".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2481

2482

Args:

2483

producerProjectId: string, Include services produced by the specified project.

2484

pageSize: integer, Requested size of the next page of data.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2485

pageToken: string, Token identifying which result to start with; returned by a previous list

2486

call.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2487

consumerId: string, Include services consumed by the specified consumer.

2488

2489

The Google Service Management implementation accepts the following

2490

forms:

2491

- project:<project_id>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2492

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2499

2500

{ # Response message for `ListServices` method.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2501

"services": [ # The returned services will only have the name field set.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2502

{ # The full representation of a Service that is managed by

2503

# Google Service Management.

2504

"serviceName": "A String", # The name of the service. See the [overview](/service-management/overview)

2505

# for naming requirements.

2506

"producerProjectId": "A String", # ID of the project that produces and owns this service.

2507

},

2508

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2509

"nextPageToken": "A String", # Token that can be passed to `ListServices` to resume a paginated query.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

}</pre>

</div>

<code class="details" id="list_next">list_next(previous_request, previous_response)</code>

2515

<pre>Retrieves the next page of results.

2516

2517

Args:

2518

previous_request: The request for the previous page. (required)

2519

previous_response: The response from the request for the previous page. (required)

2520

2521

Returns:

2522

A request object that you can call 'execute()' on to request the next

2523

page. Returns None if there are no more items in the collection.

</pre>

</div>

<code class="details" id="setIamPolicy">setIamPolicy(resource=None, body, x__xgafv=None)</code>

2529

<pre>Sets the access control policy on the specified resource. Replaces any

existing policy.

Args:

resource: string, REQUIRED: The resource for which the policy is being specified.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2534

See the operation documentation for the appropriate value for this field. (required)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2535

body: object, The request body. (required)

2536

The object takes the form of:

2537

2538

{ # Request message for `SetIamPolicy` method.

2539

"policy": { # Defines an Identity and Access Management (IAM) policy. It is used to # REQUIRED: The complete policy to be applied to the `resource`. The size of

2540

# the policy is limited to a few 10s of KB. An empty policy is a

2541

# valid policy but certain Cloud Platform services (such as Projects)

2542

# might reject them.

2543

# specify access control policies for Cloud Platform resources.

2544

#

2545

#

2546

# A `Policy` consists of a list of `bindings`. A `Binding` binds a list of

2547

# `members` to a `role`, where the members can be user accounts, Google groups,

2548

# Google domains, and service accounts. A `role` is a named list of permissions

# defined by IAM.

#

# **Example**

#

# {

# "bindings": [

# {

# "role": "roles/owner",

2557

# "members": [

2558

# "user:mike@example.com",

2559

# "group:admins@example.com",

2560

# "domain:google.com",

2561

# "serviceAccount:my-other-app@appspot.gserviceaccount.com",

# ]

# },

# {

# "role": "roles/viewer",

2566

# "members": ["user:sean@example.com"]

# }

# ]

# }

#

# For a description of IAM and its features, see the

2572

# [IAM developer's guide](https://cloud.google.com/iam).

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2573

"auditConfigs": [ # Specifies cloud audit logging configuration for this policy.

2574

{ # Specifies the audit configuration for a service.

2575

# The configuration determines which permission types are logged, and what

2576

# identities, if any, are exempted from logging.

2577

# An AuditConifg must have one or more AuditLogConfigs.

2578

#

2579

# If there are AuditConfigs for both `allServices` and a specific service,

2580

# the union of the two AuditConfigs is used for that service: the log_types

2581

# specified in each AuditConfig are enabled, and the exempted_members in each

2582

# AuditConfig are exempted.

2583

# Example Policy with multiple AuditConfigs:

# {

# "audit_configs": [

# {

# "service": "allServices"

2588

# "audit_log_configs": [

2589

# {

2590

# "log_type": "DATA_READ",

2591

# "exempted_members": [

2592

# "user:foo@gmail.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

2597

# },

2598

# {

2599

# "log_type": "ADMIN_READ",

# }

# ]

# },

# {

# "service": "fooservice@googleapis.com"

2605

# "audit_log_configs": [

2606

# {

2607

# "log_type": "DATA_READ",

2608

# },

2609

# {

2610

# "log_type": "DATA_WRITE",

2611

# "exempted_members": [

2612

# "user:bar@gmail.com"

# ]

# }

# ]

# }

# ]

# }

# For fooservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ

2620

# logging. It also exempts foo@gmail.com from DATA_READ logging, and

2621

# bar@gmail.com from DATA_WRITE logging.

2622

"exemptedMembers": [

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2623

"A String",

2624

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2625

"auditLogConfigs": [ # The configuration for logging of each type of permission.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2626

# Next ID: 4

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2627

{ # Provides the configuration for logging a type of permissions.

# Example:

#

# {

# "audit_log_configs": [

2632

# {

2633

# "log_type": "DATA_READ",

2634

# "exempted_members": [

2635

# "user:foo@gmail.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

# }

# ]

# }

#

# This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting

2645

# foo@gmail.com from DATA_READ logging.

2646

"exemptedMembers": [ # Specifies the identities that do not cause logging for this type of

2647

# permission.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2648

# Follows the same format of Binding.members.

2649

"A String",

2650

],

2651

"logType": "A String", # The log type that this config enables.

2652

},

2653

],

2654

"service": "A String", # Specifies a service that will be enabled for audit logging.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame^]

2655

# For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2656

# `allServices` is a special value that covers all services.

2657

},

2658

],

2659

"rules": [ # If more than one rule is specified, the rules are applied in the following

2660

# manner:

2661

# - All matching LOG rules are always applied.

2662

# - If any DENY/DENY_WITH_LOG rule matches, permission is denied.

2663

# Logging will be applied if one or more matching rule requires logging.

2664

# - Otherwise, if any ALLOW/ALLOW_WITH_LOG rule matches, permission is

2665

# granted.

2666

# Logging will be applied if one or more matching rule requires logging.

2667

# - Otherwise, if no rule applies, permission is denied.

2668

{ # A rule to be applied in a Policy.

2669

"notIn": [ # If one or more 'not_in' clauses are specified, the rule matches

2670

# if the PRINCIPAL/AUTHORITY_SELECTOR is in none of the entries.

2671

# The format for in and not_in entries is the same as for members in a

2672

# Binding (see google/iam/v1/policy.proto).

2673

"A String",

2674

],

2675

"description": "A String", # Human-readable description of the rule.

2676

"in": [ # If one or more 'in' clauses are specified, the rule matches if

2677

# the PRINCIPAL/AUTHORITY_SELECTOR is in at least one of these entries.

2678

"A String",

2679

],

2680

"action": "A String", # Required

2681

"conditions": [ # Additional restrictions that must be met

2682

{ # A condition to be met.

2683

"iam": "A String", # Trusted attributes supplied by the IAM system.

2684

"svc": "A String", # Trusted attributes discharged by the service.

2685

"value": "A String", # DEPRECATED. Use 'values' instead.

2686

"sys": "A String", # Trusted attributes supplied by any service that owns resources and uses

2687

# the IAM system for access control.

2688

"values": [ # The objects of the condition. This is mutually exclusive with 'value'.

2689

"A String",

2690

],

2691

"op": "A String", # An operator to apply the subject with.

2692

},

2693

],

2694

"logConfig": [ # The config returned to callers of tech.iam.IAM.CheckPolicy for any entries

2695

# that match the LOG action.

2696

{ # Specifies what kind of log the caller must write

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2697

"counter": { # Options for counters # Counter options.

2698

"field": "A String", # The field value to attribute.

2699

"metric": "A String", # The metric to update.

2700

},

2701

"dataAccess": { # Write a Data Access (Gin) log # Data access options.

2702

},

2703

"cloudAudit": { # Write a Cloud Audit log # Cloud audit options.

},

},

],

"permissions": [ # A permission is a string of form '<service>.<resource type>.<verb>'

2708

# (e.g., 'storage.buckets.list'). A value of '*' matches all permissions,

2709

# and a verb part of '*' (e.g., 'storage.buckets.*') matches all verbs.

"A String",

],

},

],

"version": 42, # Version of the `Policy`. The default version is 0.

2715

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

2716

# prevent simultaneous updates of a policy from overwriting each other.

2717

# It is strongly suggested that systems make use of the `etag` in the

2718

# read-modify-write cycle to perform policy updates in order to avoid race

2719

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

2720

# systems are expected to put that etag in the request to `setIamPolicy` to

2721

# ensure that their change will be applied to the same version of the policy.

2722

#

2723

# If no `etag` is provided in the call to `setIamPolicy`, then the existing

2724

# policy is overwritten blindly.

2725

"bindings": [ # Associates a list of `members` to a `role`.

2726

# Multiple `bindings` must not be specified for the same `role`.

2727

# `bindings` with no members will result in an error.

2728

{ # Associates `members` with a `role`.

2729

"role": "A String", # Role that is assigned to `members`.

2730

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

2731

# Required

2732

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

2733

# `members` can have the following values:

2734

#

2735

# * `allUsers`: A special identifier that represents anyone who is

2736

# on the internet; with or without a Google account.

2737

#

2738

# * `allAuthenticatedUsers`: A special identifier that represents anyone

2739

# who is authenticated with a Google account or a service account.

2740

#

2741

# * `user:{emailid}`: An email address that represents a specific Google

2742

# account. For example, `alice@gmail.com` or `joe@example.com`.

2743

#

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2744

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2745

# * `serviceAccount:{emailid}`: An email address that represents a service

2746

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

2747

#

2748

# * `group:{emailid}`: An email address that represents a Google group.

2749

# For example, `admins@example.com`.

2750

#

2751

# * `domain:{domain}`: A Google Apps domain name that represents all the

2752

# users of that domain. For example, `google.com` or `example.com`.

#

"A String",

],

},

],

"iamOwned": True or False,

2759

},

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2760

"updateMask": "A String", # OPTIONAL: A FieldMask specifying which fields of the policy to modify. Only

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2761

# the fields in the mask will be modified. If no mask is provided, the

2762

# following default mask is used:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2763

# paths: "bindings, etag"

2764

# This field is only used by Cloud IAM.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2765

}

2766

2767

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2774

2775

{ # Defines an Identity and Access Management (IAM) policy. It is used to

2776

# specify access control policies for Cloud Platform resources.

2777

#

2778

#

2779

# A `Policy` consists of a list of `bindings`. A `Binding` binds a list of

2780

# `members` to a `role`, where the members can be user accounts, Google groups,

2781

# Google domains, and service accounts. A `role` is a named list of permissions

# defined by IAM.

#

# **Example**

#

# {

# "bindings": [

# {

# "role": "roles/owner",

2790

# "members": [

2791

# "user:mike@example.com",

2792

# "group:admins@example.com",

2793

# "domain:google.com",

2794

# "serviceAccount:my-other-app@appspot.gserviceaccount.com",

# ]

# },

# {

# "role": "roles/viewer",

2799

# "members": ["user:sean@example.com"]

# }

# ]

# }

#

# For a description of IAM and its features, see the

2805

# [IAM developer's guide](https://cloud.google.com/iam).

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2806

"auditConfigs": [ # Specifies cloud audit logging configuration for this policy.

2807

{ # Specifies the audit configuration for a service.

2808

# The configuration determines which permission types are logged, and what

2809

# identities, if any, are exempted from logging.

2810

# An AuditConifg must have one or more AuditLogConfigs.

2811

#

2812

# If there are AuditConfigs for both `allServices` and a specific service,

2813

# the union of the two AuditConfigs is used for that service: the log_types

2814

# specified in each AuditConfig are enabled, and the exempted_members in each

2815

# AuditConfig are exempted.

2816

# Example Policy with multiple AuditConfigs:

# {

# "audit_configs": [

# {

# "service": "allServices"

2821

# "audit_log_configs": [

2822

# {

2823

# "log_type": "DATA_READ",

2824

# "exempted_members": [

2825

# "user:foo@gmail.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

2830

# },

2831

# {

2832

# "log_type": "ADMIN_READ",

# }

# ]

# },

# {

# "service": "fooservice@googleapis.com"

2838

# "audit_log_configs": [

2839

# {

2840

# "log_type": "DATA_READ",

2841

# },

2842

# {

2843

# "log_type": "DATA_WRITE",

2844

# "exempted_members": [

2845

# "user:bar@gmail.com"

# ]

# }

# ]

# }

# ]

# }

# For fooservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ

2853

# logging. It also exempts foo@gmail.com from DATA_READ logging, and

2854

# bar@gmail.com from DATA_WRITE logging.

2855

"exemptedMembers": [

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2856

"A String",

2857

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2858

"auditLogConfigs": [ # The configuration for logging of each type of permission.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2859

# Next ID: 4

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2860

{ # Provides the configuration for logging a type of permissions.

# Example:

#

# {

# "audit_log_configs": [

2865

# {

2866

# "log_type": "DATA_READ",

2867

# "exempted_members": [

2868

# "user:foo@gmail.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

# }

# ]

# }

#

# This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting

2878

# foo@gmail.com from DATA_READ logging.

2879

"exemptedMembers": [ # Specifies the identities that do not cause logging for this type of

2880

# permission.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2881

# Follows the same format of Binding.members.

2882

"A String",

2883

],

2884

"logType": "A String", # The log type that this config enables.

2885

},

2886

],

2887

"service": "A String", # Specifies a service that will be enabled for audit logging.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame^]

2888

# For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2889

# `allServices` is a special value that covers all services.

2890

},

2891

],

2892

"rules": [ # If more than one rule is specified, the rules are applied in the following

2893

# manner:

2894

# - All matching LOG rules are always applied.

2895

# - If any DENY/DENY_WITH_LOG rule matches, permission is denied.

2896

# Logging will be applied if one or more matching rule requires logging.

2897

# - Otherwise, if any ALLOW/ALLOW_WITH_LOG rule matches, permission is

2898

# granted.

2899

# Logging will be applied if one or more matching rule requires logging.

2900

# - Otherwise, if no rule applies, permission is denied.

2901

{ # A rule to be applied in a Policy.

2902

"notIn": [ # If one or more 'not_in' clauses are specified, the rule matches

2903

# if the PRINCIPAL/AUTHORITY_SELECTOR is in none of the entries.

2904

# The format for in and not_in entries is the same as for members in a

2905

# Binding (see google/iam/v1/policy.proto).

2906

"A String",

2907

],

2908

"description": "A String", # Human-readable description of the rule.

2909

"in": [ # If one or more 'in' clauses are specified, the rule matches if

2910

# the PRINCIPAL/AUTHORITY_SELECTOR is in at least one of these entries.

2911

"A String",

2912

],

2913

"action": "A String", # Required

2914

"conditions": [ # Additional restrictions that must be met

2915

{ # A condition to be met.

2916

"iam": "A String", # Trusted attributes supplied by the IAM system.

2917

"svc": "A String", # Trusted attributes discharged by the service.

2918

"value": "A String", # DEPRECATED. Use 'values' instead.

2919

"sys": "A String", # Trusted attributes supplied by any service that owns resources and uses

2920

# the IAM system for access control.

2921

"values": [ # The objects of the condition. This is mutually exclusive with 'value'.

2922

"A String",

2923

],

2924

"op": "A String", # An operator to apply the subject with.

2925

},

2926

],

2927

"logConfig": [ # The config returned to callers of tech.iam.IAM.CheckPolicy for any entries

2928

# that match the LOG action.

2929

{ # Specifies what kind of log the caller must write

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2930

"counter": { # Options for counters # Counter options.

2931

"field": "A String", # The field value to attribute.

2932

"metric": "A String", # The metric to update.

2933

},

2934

"dataAccess": { # Write a Data Access (Gin) log # Data access options.

2935

},

2936

"cloudAudit": { # Write a Cloud Audit log # Cloud audit options.

},

},

],

"permissions": [ # A permission is a string of form '<service>.<resource type>.<verb>'

2941

# (e.g., 'storage.buckets.list'). A value of '*' matches all permissions,

2942

# and a verb part of '*' (e.g., 'storage.buckets.*') matches all verbs.

"A String",

],

},

],

"version": 42, # Version of the `Policy`. The default version is 0.

2948

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

2949

# prevent simultaneous updates of a policy from overwriting each other.

2950

# It is strongly suggested that systems make use of the `etag` in the

2951

# read-modify-write cycle to perform policy updates in order to avoid race

2952

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

2953

# systems are expected to put that etag in the request to `setIamPolicy` to

2954

# ensure that their change will be applied to the same version of the policy.

2955

#

2956

# If no `etag` is provided in the call to `setIamPolicy`, then the existing

2957

# policy is overwritten blindly.

2958

"bindings": [ # Associates a list of `members` to a `role`.

2959

# Multiple `bindings` must not be specified for the same `role`.

2960

# `bindings` with no members will result in an error.

2961

{ # Associates `members` with a `role`.

2962

"role": "A String", # Role that is assigned to `members`.

2963

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

2964

# Required

2965

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

2966

# `members` can have the following values:

2967

#

2968

# * `allUsers`: A special identifier that represents anyone who is

2969

# on the internet; with or without a Google account.

2970

#

2971

# * `allAuthenticatedUsers`: A special identifier that represents anyone

2972

# who is authenticated with a Google account or a service account.

2973

#

2974

# * `user:{emailid}`: An email address that represents a specific Google

2975

# account. For example, `alice@gmail.com` or `joe@example.com`.

2976

#

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2977

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2978

# * `serviceAccount:{emailid}`: An email address that represents a service

2979

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

2980

#

2981

# * `group:{emailid}`: An email address that represents a Google group.

2982

# For example, `admins@example.com`.

2983

#

2984

# * `domain:{domain}`: A Google Apps domain name that represents all the

2985

# users of that domain. For example, `google.com` or `example.com`.

#

"A String",

],

},

],

"iamOwned": True or False,

}</pre>

</div>

<code class="details" id="testIamPermissions">testIamPermissions(resource=None, body, x__xgafv=None)</code>

2997

<pre>Returns permissions that a caller has on the specified resource.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2998

If the resource does not exist, this will return an empty set of

2999

permissions, not a NOT_FOUND error.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3000

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3001

Note: This operation is designed to be used for building permission-aware

3002

UIs and command-line tools, not for authorization checking. This operation

3003

may "fail open" without warning.

3004

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3005

Args:

3006

resource: string, REQUIRED: The resource for which the policy detail is being requested.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3007

See the operation documentation for the appropriate value for this field. (required)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3008

body: object, The request body. (required)

3009

The object takes the form of:

3010

3011

{ # Request message for `TestIamPermissions` method.

3012

"permissions": [ # The set of permissions to check for the `resource`. Permissions with

3013

# wildcards (such as '*' or 'storage.*') are not allowed. For more

3014

# information see

3015

# [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).

"A String",

],

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

3027

3028

{ # Response message for `TestIamPermissions` method.

3029

"permissions": [ # A subset of `TestPermissionsRequest.permissions` that the caller is

# allowed.

"A String",

],

}</pre>

</div>

<code class="details" id="undelete">undelete(serviceName=None, x__xgafv=None)</code>

3038

<pre>Revives a previously deleted managed service. The method restores the

3039

service using the configuration at the time the service was deleted.

3040

The target service must exist and must have been deleted within the

3041

last 30 days.

3042

3043

Operation<response: UndeleteServiceResponse>

3044

3045

Args:

3046

serviceName: string, The name of the service. See the [overview](/service-management/overview)

3047

for naming requirements. For example: `example.googleapis.com`. (required)

3048

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

3055

3056

{ # This resource represents a long-running operation that is the result of a

3057

# network API call.

3058

"metadata": { # Service-specific metadata associated with the operation. It typically

3059

# contains progress information and common metadata such as create time.

3060

# Some services might not provide such metadata. Any method that returns a

3061

# long-running operation should document the metadata type, if any.

3062

"a_key": "", # Properties of the object. Contains field @type with type URL.

3063

},

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3064

"error": { # The `Status` type defines a logical error model that is suitable for different # The error result of the operation in case of failure or cancellation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3065

# programming environments, including REST APIs and RPC APIs. It is used by

3066

# [gRPC](https://github.com/grpc). The error model is designed to be:

3067

#

3068

# - Simple to use and understand for most users

3069

# - Flexible enough to meet unexpected needs

#

# # Overview

#

# The `Status` message contains three pieces of data: error code, error message,

3074

# and error details. The error code should be an enum value of

3075

# google.rpc.Code, but it may accept additional error codes if needed. The

3076

# error message should be a developer-facing English message that helps

3077

# developers *understand* and *resolve* the error. If a localized user-facing

3078

# error message is needed, put the localized message in the error details or

3079

# localize it in the client. The optional error details may contain arbitrary

3080

# information about the error. There is a predefined set of error detail types

3081

# in the package `google.rpc` which can be used for common error conditions.

#

# # Language mapping

#

# The `Status` message is the logical representation of the error model, but it

3086

# is not necessarily the actual wire format. When the `Status` message is

3087

# exposed in different client libraries and different wire protocols, it can be

3088

# mapped differently. For example, it will likely be mapped to some exceptions

3089

# 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

3094

# environments, either with or without APIs, to provide a

3095

# consistent developer experience across different environments.

3096

#

3097

# Example uses of this error model include:

3098

#

3099

# - Partial errors. If a service needs to return partial errors to the client,

3100

# it may embed the `Status` in the normal response to indicate the partial

3101

# errors.

3102

#

3103

# - Workflow errors. A typical workflow has multiple steps. Each step may

3104

# have a `Status` message for error reporting purpose.

3105

#

3106

# - Batch operations. If a client uses batch request and batch response, the

3107

# `Status` message should be used directly inside batch response, one for

3108

# each error sub-response.

3109

#

3110

# - Asynchronous operations. If an API call embeds asynchronous operation

3111

# results in its response, the status of those operations should be

3112

# represented directly using the `Status` message.

3113

#

3114

# - Logging. If some API errors are stored in logs, the message `Status` could

3115

# be used directly after any stripping needed for security/privacy reasons.

3116

"message": "A String", # A developer-facing error message, which should be in English. Any

3117

# user-facing error message should be localized and sent in the

3118

# google.rpc.Status.details field, or localized by the client.

3119

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

3120

"details": [ # A list of messages that carry the error details. There will be a

3121

# common set of message types for APIs to use.

3122

{

3123

"a_key": "", # Properties of the object. Contains field @type with type URL.

3124

},

3125

],

3126

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3127

"done": True or False, # If the value is `false`, it means the operation is still in progress.

3128

# If true, the operation is completed, and either `error` or `response` is

3129

# available.

3130

"response": { # The normal response of the operation in case of success. If the original

3131

# method returns no data on success, such as `Delete`, the response is

3132

# `google.protobuf.Empty`. If the original method is standard

3133

# `Get`/`Create`/`Update`, the response should be the resource. For other

3134

# methods, the response should have the type `XxxResponse`, where `Xxx`

3135

# is the original method name. For example, if the original method name

3136

# is `TakeSnapshot()`, the inferred response type is

3137

# `TakeSnapshotResponse`.

3138

"a_key": "", # Properties of the object. Contains field @type with type URL.

3139

},

3140

"name": "A String", # The server-assigned name, which is only unique within the same service that

3141

# originally returns it. If you use the default HTTP mapping, the

3142

# `name` should have the format of `operations/some/unique/name`.

Jon Wayne Parrott