Blame - docs/dyn/spanner_v1.projects.instances.backups.html - platform/external/python/google-api-python-client

2020-07-22 17:02:09 -0700

[diff] [blame^]

95

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

96

<p class="firstline">Lists completed and pending backups.</p>

97

98

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

99

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

100

101

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

102

<p class="firstline">Updates a pending or completed Backup.</p>

103

104

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

105

<p class="firstline">Sets the access control policy on a database or backup resource.</p>

106

107

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

108

<p class="firstline">Returns permissions that the caller has on the specified database or backup</p>

109

<h3>Method Details</h3>

110

111

<code class="details" id="create">create(parent, body=None, backupId=None, x__xgafv=None)</code>

112

<pre>Starts creating a new Cloud Spanner Backup.

113

The returned backup long-running operation

114

will have a name of the format

115

`projects/<project>/instances/<instance>/backups/<backup>/operations/<operation_id>`

116

and can be used to track creation of the backup. The

117

metadata field type is

118

CreateBackupMetadata. The

119

response field type is

120

Backup, if successful. Cancelling the returned operation will stop the

121

creation and delete the backup.

122

There can be only one pending backup creation per database. Backup creation

123

of different databases can run concurrently.

124

125

Args:

126

parent: string, Required. The name of the instance in which the backup will be

127

created. This must be the same instance that contains the database the

128

backup will be created from. The backup will be stored in the

129

location(s) specified in the instance configuration of this

130

instance. Values are of the form

131

`projects/<project>/instances/<instance>`. (required)

132

body: object, The request body.

133

The object takes the form of:

134

135

{ # A backup of a Cloud Spanner database.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

136

"expireTime": "A String", # Required for the CreateBackup

137

# operation. The expiration time of the backup, with microseconds

138

# granularity that must be at least 6 hours and at most 366 days

139

# from the time the CreateBackup request is processed. Once the `expire_time`

140

# has passed, the backup is eligible to be automatically deleted by Cloud

141

# Spanner to free the resources used by the backup.

142

"createTime": "A String", # Output only. The backup will contain an externally consistent

143

# copy of the database at the timestamp specified by

144

# `create_time`. `create_time` is approximately the time the

145

# CreateBackup request is received.

146

"database": "A String", # Required for the CreateBackup operation.

147

# Name of the database from which this backup was

148

# created. This needs to be in the same instance as the backup.

149

# Values are of the form

150

# `projects/<project>/instances/<instance>/databases/<database>`.

151

"state": "A String", # Output only. The current state of the backup.

152

"name": "A String", # Output only for the CreateBackup operation.

153

# Required for the UpdateBackup operation.

154

#

155

# A globally unique identifier for the backup which cannot be

156

# changed. Values are of the form

157

# `projects/<project>/instances/<instance>/backups/a-z*[a-z0-9]`

158

# The final segment of the name must be between 2 and 60 characters

159

# in length.

160

#

161

# The backup is stored in the location(s) specified in the instance

162

# configuration of the instance containing the backup, identified

163

# by the prefix of the backup name of the form

164

# `projects/<project>/instances/<instance>`.

165

"sizeBytes": "A String", # Output only. Size of the backup in bytes.

166

"referencingDatabases": [ # Output only. The names of the restored databases that reference the backup.

167

# The database names are of

168

# the form `projects/<project>/instances/<instance>/databases/<database>`.

169

# Referencing databases may exist in different instances. The existence of

170

# any referencing database prevents the backup from being deleted. When a

171

# restored database from the backup enters the `READY` state, the reference

172

# to the backup is removed.

173

"A String",

174

],

175

}

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

176

177

backupId: string, Required. The id of the backup to be created. The `backup_id` appended to

178

`parent` forms the full backup name of the form

179

`projects/<project>/instances/<instance>/backups/<backup_id>`.

180

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

187

188

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

189

# network API call.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

190

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

191

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

192

# `name` should be a resource name ending with `operations/{unique_id}`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

193

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

194

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

195

# used by [gRPC](https://github.com/grpc). Each `Status` message contains

196

# three pieces of data: error code, error message, and error details.

197

#

198

# You can find out more about this error model and how to work with it in the

199

# [API Design Guide](https://cloud.google.com/apis/design/errors).

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

200

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

201

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

202

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

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

203

"details": [ # A list of messages that carry the error details. There is a common set of

204

# message types for APIs to use.

205

{

206

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

207

},

208

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

209

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

210

},

211

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

212

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

213

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

214

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

215

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

216

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

217

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

218

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

219

# available.

220

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

221

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

222

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

223

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

224

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

225

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

226

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

227

# `TakeSnapshotResponse`.

228

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

229

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

}</pre>

</div>

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

235

<pre>Deletes a pending or completed Backup.

Args:

Values are of the form

240

`projects/<project>/instances/<instance>/backups/<backup>`. (required)

241

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

248

249

{ # A generic empty message that you can re-use to avoid defining duplicated

250

# empty messages in your APIs. A typical example is to use it as the request

251

# or the response type of an API method. For instance:

252

#

253

# service Foo {

254

# rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

255

# }

256

#

257

# The JSON representation for `Empty` is empty JSON object `{}`.

}</pre>

</div>

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

263

<pre>Gets metadata on a pending or completed Backup.

Args:

Values are of the form

268

`projects/<project>/instances/<instance>/backups/<backup>`. (required)

269

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

276

277

{ # A backup of a Cloud Spanner database.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

278

"expireTime": "A String", # Required for the CreateBackup

279

# operation. The expiration time of the backup, with microseconds

280

# granularity that must be at least 6 hours and at most 366 days

281

# from the time the CreateBackup request is processed. Once the `expire_time`

282

# has passed, the backup is eligible to be automatically deleted by Cloud

283

# Spanner to free the resources used by the backup.

284

"createTime": "A String", # Output only. The backup will contain an externally consistent

285

# copy of the database at the timestamp specified by

286

# `create_time`. `create_time` is approximately the time the

287

# CreateBackup request is received.

288

"database": "A String", # Required for the CreateBackup operation.

289

# Name of the database from which this backup was

290

# created. This needs to be in the same instance as the backup.

291

# Values are of the form

292

# `projects/<project>/instances/<instance>/databases/<database>`.

293

"state": "A String", # Output only. The current state of the backup.

294

"name": "A String", # Output only for the CreateBackup operation.

295

# Required for the UpdateBackup operation.

296

#

297

# A globally unique identifier for the backup which cannot be

298

# changed. Values are of the form

299

# `projects/<project>/instances/<instance>/backups/a-z*[a-z0-9]`

300

# The final segment of the name must be between 2 and 60 characters

301

# in length.

302

#

303

# The backup is stored in the location(s) specified in the instance

304

# configuration of the instance containing the backup, identified

305

# by the prefix of the backup name of the form

306

# `projects/<project>/instances/<instance>`.

307

"sizeBytes": "A String", # Output only. Size of the backup in bytes.

308

"referencingDatabases": [ # Output only. The names of the restored databases that reference the backup.

309

# The database names are of

310

# the form `projects/<project>/instances/<instance>/databases/<database>`.

311

# Referencing databases may exist in different instances. The existence of

312

# any referencing database prevents the backup from being deleted. When a

313

# restored database from the backup enters the `READY` state, the reference

314

# to the backup is removed.

315

"A String",

316

],

317

}</pre>

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

</div>

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

322

<pre>Gets the access control policy for a database or backup resource.

323

Returns an empty policy if a database or backup exists but does not have a

324

policy set.

325

326

Authorization requires `spanner.databases.getIamPolicy` permission on

327

resource.

328

For backups, authorization requires `spanner.backups.getIamPolicy`

329

permission on resource.

330

331

Args:

332

resource: string, REQUIRED: The Cloud Spanner resource for which the policy is being retrieved. The format is `projects/<project ID>/instances/<instance ID>` for instance resources and `projects/<project ID>/instances/<instance ID>/databases/<database ID>` for database resources. (required)

333

body: object, The request body.

334

The object takes the form of:

335

336

{ # Request message for `GetIamPolicy` method.

337

"options": { # Encapsulates settings provided to GetIamPolicy. # OPTIONAL: A `GetPolicyOptions` object for specifying options to

338

# `GetIamPolicy`.

339

"requestedPolicyVersion": 42, # Optional. The policy format version to be returned.

340

#

341

# Valid values are 0, 1, and 3. Requests specifying an invalid value will be

342

# rejected.

343

#

344

# Requests for policies with any conditional bindings must specify version 3.

345

# Policies without any conditional bindings may specify any valid value or

346

# leave the field unset.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

347

#

348

# To learn which resources support conditions in their IAM policies, see the

349

# [IAM

350

# documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

361

362

{ # An Identity and Access Management (IAM) policy, which specifies access

363

# controls for Google Cloud resources.

364

#

365

#

366

# A `Policy` is a collection of `bindings`. A `binding` binds one or more

367

# `members` to a single `role`. Members can be user accounts, service accounts,

368

# Google groups, and domains (such as G Suite). A `role` is a named list of

369

# permissions; each `role` can be an IAM predefined role or a user-created

370

# custom role.

371

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

372

# For some types of Google Cloud resources, a `binding` can also specify a

373

# `condition`, which is a logical expression that allows access to a resource

374

# only if the expression evaluates to `true`. A condition can add constraints

375

# based on attributes of the request, the resource, or both. To learn which

376

# resources support conditions in their IAM policies, see the

377

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

#

# **JSON example:**

#

# {

# "bindings": [

# {

# "role": "roles/resourcemanager.organizationAdmin",

385

# "members": [

386

# "user:mike@example.com",

387

# "group:admins@example.com",

388

# "domain:google.com",

389

# "serviceAccount:my-project-id@appspot.gserviceaccount.com"

# ]

# },

# {

# "role": "roles/resourcemanager.organizationViewer",

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

394

# "members": [

395

# "user:eve@example.com"

396

# ],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

397

# "condition": {

398

# "title": "expirable access",

399

# "description": "Does not grant access after Sep 2020",

400

# "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",

# }

# }

# ],

# "etag": "BwWWja0YfJA=",

# "version": 3

# }

#

# **YAML example:**

#

# bindings:

# - members:

# - user:mike@example.com

413

# - group:admins@example.com

414

# - domain:google.com

415

# - serviceAccount:my-project-id@appspot.gserviceaccount.com

416

# role: roles/resourcemanager.organizationAdmin

417

# - members:

418

# - user:eve@example.com

419

# role: roles/resourcemanager.organizationViewer

420

# condition:

421

# title: expirable access

422

# description: Does not grant access after Sep 2020

423

# expression: request.time < timestamp('2020-10-01T00:00:00.000Z')

424

# - etag: BwWWja0YfJA=

425

# - version: 3

426

#

427

# For a description of IAM and its features, see the

428

# [IAM documentation](https://cloud.google.com/iam/docs/).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

429

"bindings": [ # Associates a list of `members` to a `role`. Optionally, may specify a

430

# `condition` that determines how and when the `bindings` are applied. Each

431

# of the `bindings` must contain at least one member.

432

{ # Associates `members` with a `role`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

433

"role": "A String", # Role that is assigned to `members`.

434

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

435

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

436

# `members` can have the following values:

437

#

438

# * `allUsers`: A special identifier that represents anyone who is

439

# on the internet; with or without a Google account.

440

#

441

# * `allAuthenticatedUsers`: A special identifier that represents anyone

442

# who is authenticated with a Google account or a service account.

443

#

444

# * `user:{emailid}`: An email address that represents a specific Google

445

# account. For example, `alice@example.com` .

446

#

447

#

448

# * `serviceAccount:{emailid}`: An email address that represents a service

449

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

450

#

451

# * `group:{emailid}`: An email address that represents a Google group.

452

# For example, `admins@example.com`.

453

#

454

# * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique

455

# identifier) representing a user that has been recently deleted. For

456

# example, `alice@example.com?uid=123456789012345678901`. If the user is

457

# recovered, this value reverts to `user:{emailid}` and the recovered user

458

# retains the role in the binding.

459

#

460

# * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus

461

# unique identifier) representing a service account that has been recently

462

# deleted. For example,

463

# `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.

464

# If the service account is undeleted, this value reverts to

465

# `serviceAccount:{emailid}` and the undeleted service account retains the

466

# role in the binding.

467

#

468

# * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique

469

# identifier) representing a Google group that has been recently

470

# deleted. For example, `admins@example.com?uid=123456789012345678901`. If

471

# the group is recovered, this value reverts to `group:{emailid}` and the

472

# recovered group retains the role in the binding.

473

#

474

#

475

# * `domain:{domain}`: The G Suite domain (primary) that represents all the

476

# users of that domain. For example, `google.com` or `example.com`.

477

#

478

"A String",

479

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

480

"condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.

481

#

482

# If the condition evaluates to `true`, then this binding applies to the

483

# current request.

484

#

485

# If the condition evaluates to `false`, then this binding does not apply to

486

# the current request. However, a different role binding might grant the same

487

# role to one or more of the members in this binding.

488

#

489

# To learn which resources support conditions in their IAM policies, see the

490

# [IAM

491

# documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

492

# syntax. CEL is a C-like expression language. The syntax and semantics of CEL

493

# are documented at https://github.com/google/cel-spec.

494

#

495

# Example (Comparison):

496

#

497

# title: "Summary size limit"

498

# description: "Determines if a summary is less than 100 chars"

499

# expression: "document.summary.size() < 100"

500

#

501

# Example (Equality):

502

#

503

# title: "Requestor is owner"

504

# description: "Determines if requestor is the document owner"

505

# expression: "document.owner == request.auth.claims.email"

#

# Example (Logic):

#

# title: "Public documents"

510

# description: "Determine whether the document should be publicly visible"

511

# expression: "document.type != 'private' && document.type != 'internal'"

512

#

513

# Example (Data Manipulation):

514

#

515

# title: "Notification string"

516

# description: "Create a notification string with a timestamp."

517

# expression: "'New message received at ' + string(document.create_time)"

518

#

519

# The exact variables and functions that may be referenced within an expression

520

# are determined by the service that evaluates it. See the service

521

# documentation for additional information.

522

"expression": "A String", # Textual representation of an expression in Common Expression Language

523

# syntax.

524

"description": "A String", # Optional. Description of the expression. This is a longer text which

525

# describes the expression, e.g. when hovered over it in a UI.

526

"location": "A String", # Optional. String indicating the location of the expression for error

527

# reporting, e.g. a file name and a position in the file.

528

"title": "A String", # Optional. Title for the expression, i.e. a short string describing

529

# its purpose. This can be used e.g. in UIs which allow to enter the

530

# expression.

531

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

532

},

533

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

534

"version": 42, # Specifies the format of the policy.

535

#

536

# Valid values are `0`, `1`, and `3`. Requests that specify an invalid value

537

# are rejected.

538

#

539

# Any operation that affects conditional role bindings must specify version

540

# `3`. This requirement applies to the following operations:

541

#

542

# * Getting a policy that includes a conditional role binding

543

# * Adding a conditional role binding to a policy

544

# * Changing a conditional role binding in a policy

545

# * Removing any role binding, with or without a condition, from a policy

546

# that includes conditions

547

#

548

# **Important:** If you use IAM Conditions, you must include the `etag` field

549

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

550

# you to overwrite a version `3` policy with a version `1` policy, and all of

551

# the conditions in the version `3` policy are lost.

552

#

553

# If a policy does not include any conditions, operations on that policy may

554

# specify any valid version or leave the field unset.

555

#

556

# To learn which resources support conditions in their IAM policies, see the

557

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

558

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

559

# prevent simultaneous updates of a policy from overwriting each other.

560

# It is strongly suggested that systems make use of the `etag` in the

561

# read-modify-write cycle to perform policy updates in order to avoid race

562

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

563

# systems are expected to put that etag in the request to `setIamPolicy` to

564

# ensure that their change will be applied to the same version of the policy.

565

#

566

# **Important:** If you use IAM Conditions, you must include the `etag` field

567

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

568

# you to overwrite a version `3` policy with a version `1` policy, and all of

569

# the conditions in the version `3` policy are lost.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

}</pre>

</div>

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

574

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

575

<pre>Lists completed and pending backups.

576

Backups returned are ordered by `create_time` in descending order,

577

starting from the most recent `create_time`.

578

579

Args:

580

parent: string, Required. The instance to list backups from. Values are of the

581

form `projects/<project>/instances/<instance>`. (required)

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

582

filter: string, An expression that filters the list of returned backups.

583

584

A filter expression consists of a field name, a comparison operator, and a

585

value for filtering.

586

The value must be a string, a number, or a boolean. The comparison operator

587

must be one of: `<`, `>`, `<=`, `>=`, `!=`, `=`, or `:`.

588

Colon `:` is the contains operator. Filter rules are not case sensitive.

589

590

The following fields in the Backup are eligible for filtering:

* `name`

* `database`

* `state`

* `create_time` (and values are of the format YYYY-MM-DDTHH:MM:SSZ)

596

* `expire_time` (and values are of the format YYYY-MM-DDTHH:MM:SSZ)

597

* `size_bytes`

598

599

You can combine multiple expressions by enclosing each expression in

600

parentheses. By default, expressions are combined with AND logic, but

601

you can specify AND, OR, and NOT logic explicitly.

602

603

Here are a few examples:

604

605

* `name:Howl` - The backup's name contains the string "howl".

606

* `database:prod`

607

- The database's name contains the string "prod".

608

* `state:CREATING` - The backup is pending creation.

609

* `state:READY` - The backup is fully created and ready for use.

610

* `(name:howl) AND (create_time < \"2018-03-28T14:50:00Z\")`

611

- The backup name contains the string "howl" and `create_time`

612

of the backup is before 2018-03-28T14:50:00Z.

613

* `expire_time < \"2018-03-28T14:50:00Z\"`

614

- The backup `expire_time` is before 2018-03-28T14:50:00Z.

615

* `size_bytes > 10000000000` - The backup's size is greater than 10GB

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

616

pageSize: integer, Number of backups to be returned in the response. If 0 or

617

less, defaults to the server's maximum allowed page size.

618

pageToken: string, If non-empty, `page_token` should contain a

619

next_page_token from a

620

previous ListBackupsResponse to the same `parent` and with the same

621

`filter`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

622

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

629

630

{ # The response for ListBackups.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

631

"nextPageToken": "A String", # `next_page_token` can be sent in a subsequent

632

# ListBackups call to fetch more

633

# of the matching backups.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

634

"backups": [ # The list of matching backups. Backups returned are ordered by `create_time`

635

# in descending order, starting from the most recent `create_time`.

636

{ # A backup of a Cloud Spanner database.

637

"expireTime": "A String", # Required for the CreateBackup

638

# operation. The expiration time of the backup, with microseconds

639

# granularity that must be at least 6 hours and at most 366 days

640

# from the time the CreateBackup request is processed. Once the `expire_time`

641

# has passed, the backup is eligible to be automatically deleted by Cloud

642

# Spanner to free the resources used by the backup.

643

"createTime": "A String", # Output only. The backup will contain an externally consistent

644

# copy of the database at the timestamp specified by

645

# `create_time`. `create_time` is approximately the time the

646

# CreateBackup request is received.

647

"database": "A String", # Required for the CreateBackup operation.

648

# Name of the database from which this backup was

649

# created. This needs to be in the same instance as the backup.

650

# Values are of the form

651

# `projects/<project>/instances/<instance>/databases/<database>`.

652

"state": "A String", # Output only. The current state of the backup.

653

"name": "A String", # Output only for the CreateBackup operation.

654

# Required for the UpdateBackup operation.

655

#

656

# A globally unique identifier for the backup which cannot be

657

# changed. Values are of the form

658

# `projects/<project>/instances/<instance>/backups/a-z*[a-z0-9]`

659

# The final segment of the name must be between 2 and 60 characters

660

# in length.

661

#

662

# The backup is stored in the location(s) specified in the instance

663

# configuration of the instance containing the backup, identified

664

# by the prefix of the backup name of the form

665

# `projects/<project>/instances/<instance>`.

666

"sizeBytes": "A String", # Output only. Size of the backup in bytes.

667

"referencingDatabases": [ # Output only. The names of the restored databases that reference the backup.

668

# The database names are of

669

# the form `projects/<project>/instances/<instance>/databases/<database>`.

670

# Referencing databases may exist in different instances. The existence of

671

# any referencing database prevents the backup from being deleted. When a

672

# restored database from the backup enters the `READY` state, the reference

673

# to the backup is removed.

"A String",

],

},

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

}</pre>

</div>

<code class="details" id="list_next">list_next(previous_request, previous_response)</code>

683

<pre>Retrieves the next page of results.

684

685

Args:

686

previous_request: The request for the previous page. (required)

687

previous_response: The response from the request for the previous page. (required)

688

689

Returns:

690

A request object that you can call 'execute()' on to request the next

691

page. Returns None if there are no more items in the collection.

</pre>

</div>

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

697

<pre>Updates a pending or completed Backup.

Args:

Required for the UpdateBackup operation.

702

703

A globally unique identifier for the backup which cannot be

704

changed. Values are of the form

705

`projects/<project>/instances/<instance>/backups/a-z*[a-z0-9]`

706

The final segment of the name must be between 2 and 60 characters

707

in length.

708

709

The backup is stored in the location(s) specified in the instance

710

configuration of the instance containing the backup, identified

711

by the prefix of the backup name of the form

712

`projects/<project>/instances/<instance>`. (required)

713

body: object, The request body.

714

The object takes the form of:

715

716

{ # A backup of a Cloud Spanner database.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

717

"expireTime": "A String", # Required for the CreateBackup

718

# operation. The expiration time of the backup, with microseconds

719

# granularity that must be at least 6 hours and at most 366 days

720

# from the time the CreateBackup request is processed. Once the `expire_time`

721

# has passed, the backup is eligible to be automatically deleted by Cloud

722

# Spanner to free the resources used by the backup.

723

"createTime": "A String", # Output only. The backup will contain an externally consistent

724

# copy of the database at the timestamp specified by

725

# `create_time`. `create_time` is approximately the time the

726

# CreateBackup request is received.

727

"database": "A String", # Required for the CreateBackup operation.

728

# Name of the database from which this backup was

729

# created. This needs to be in the same instance as the backup.

730

# Values are of the form

731

# `projects/<project>/instances/<instance>/databases/<database>`.

732

"state": "A String", # Output only. The current state of the backup.

733

"name": "A String", # Output only for the CreateBackup operation.

734

# Required for the UpdateBackup operation.

735

#

736

# A globally unique identifier for the backup which cannot be

737

# changed. Values are of the form

738

# `projects/<project>/instances/<instance>/backups/a-z*[a-z0-9]`

739

# The final segment of the name must be between 2 and 60 characters

740

# in length.

741

#

742

# The backup is stored in the location(s) specified in the instance

743

# configuration of the instance containing the backup, identified

744

# by the prefix of the backup name of the form

745

# `projects/<project>/instances/<instance>`.

746

"sizeBytes": "A String", # Output only. Size of the backup in bytes.

747

"referencingDatabases": [ # Output only. The names of the restored databases that reference the backup.

748

# The database names are of

749

# the form `projects/<project>/instances/<instance>/databases/<database>`.

750

# Referencing databases may exist in different instances. The existence of

751

# any referencing database prevents the backup from being deleted. When a

752

# restored database from the backup enters the `READY` state, the reference

753

# to the backup is removed.

754

"A String",

755

],

756

}

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

757

758

updateMask: string, Required. A mask specifying which fields (e.g. `expire_time`) in the

759

Backup resource should be updated. This mask is relative to the Backup

760

resource, not to the request message. The field mask must always be

761

specified; this prevents any future fields from being erased accidentally

762

by clients that do not know about them.

763

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

770

771

{ # A backup of a Cloud Spanner database.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

772

"expireTime": "A String", # Required for the CreateBackup

773

# operation. The expiration time of the backup, with microseconds

774

# granularity that must be at least 6 hours and at most 366 days

775

# from the time the CreateBackup request is processed. Once the `expire_time`

776

# has passed, the backup is eligible to be automatically deleted by Cloud

777

# Spanner to free the resources used by the backup.

778

"createTime": "A String", # Output only. The backup will contain an externally consistent

779

# copy of the database at the timestamp specified by

780

# `create_time`. `create_time` is approximately the time the

781

# CreateBackup request is received.

782

"database": "A String", # Required for the CreateBackup operation.

783

# Name of the database from which this backup was

784

# created. This needs to be in the same instance as the backup.

785

# Values are of the form

786

# `projects/<project>/instances/<instance>/databases/<database>`.

787

"state": "A String", # Output only. The current state of the backup.

788

"name": "A String", # Output only for the CreateBackup operation.

789

# Required for the UpdateBackup operation.

790

#

791

# A globally unique identifier for the backup which cannot be

792

# changed. Values are of the form

793

# `projects/<project>/instances/<instance>/backups/a-z*[a-z0-9]`

794

# The final segment of the name must be between 2 and 60 characters

795

# in length.

796

#

797

# The backup is stored in the location(s) specified in the instance

798

# configuration of the instance containing the backup, identified

799

# by the prefix of the backup name of the form

800

# `projects/<project>/instances/<instance>`.

801

"sizeBytes": "A String", # Output only. Size of the backup in bytes.

802

"referencingDatabases": [ # Output only. The names of the restored databases that reference the backup.

803

# The database names are of

804

# the form `projects/<project>/instances/<instance>/databases/<database>`.

805

# Referencing databases may exist in different instances. The existence of

806

# any referencing database prevents the backup from being deleted. When a

807

# restored database from the backup enters the `READY` state, the reference

808

# to the backup is removed.

809

"A String",

810

],

811

}</pre>

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

</div>

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

816

<pre>Sets the access control policy on a database or backup resource.

817

Replaces any existing policy.

818

819

Authorization requires `spanner.databases.setIamPolicy`

820

permission on resource.

821

For backups, authorization requires `spanner.backups.setIamPolicy`

822

permission on resource.

823

824

Args:

825

resource: string, REQUIRED: The Cloud Spanner resource for which the policy is being set. The format is `projects/<project ID>/instances/<instance ID>` for instance resources and `projects/<project ID>/instances/<instance ID>/databases/<database ID>` for databases resources. (required)

826

body: object, The request body.

827

The object takes the form of:

828

829

{ # Request message for `SetIamPolicy` method.

830

"policy": { # An Identity and Access Management (IAM) policy, which specifies access # REQUIRED: The complete policy to be applied to the `resource`. The size of

831

# the policy is limited to a few 10s of KB. An empty policy is a

832

# valid policy but certain Cloud Platform services (such as Projects)

833

# might reject them.

834

# controls for Google Cloud resources.

835

#

836

#

837

# A `Policy` is a collection of `bindings`. A `binding` binds one or more

838

# `members` to a single `role`. Members can be user accounts, service accounts,

839

# Google groups, and domains (such as G Suite). A `role` is a named list of

840

# permissions; each `role` can be an IAM predefined role or a user-created

841

# custom role.

842

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

843

# For some types of Google Cloud resources, a `binding` can also specify a

844

# `condition`, which is a logical expression that allows access to a resource

845

# only if the expression evaluates to `true`. A condition can add constraints

846

# based on attributes of the request, the resource, or both. To learn which

847

# resources support conditions in their IAM policies, see the

848

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

#

# **JSON example:**

#

# {

# "bindings": [

# {

# "role": "roles/resourcemanager.organizationAdmin",

856

# "members": [

857

# "user:mike@example.com",

858

# "group:admins@example.com",

859

# "domain:google.com",

860

# "serviceAccount:my-project-id@appspot.gserviceaccount.com"

# ]

# },

# {

# "role": "roles/resourcemanager.organizationViewer",

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

865

# "members": [

866

# "user:eve@example.com"

867

# ],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

868

# "condition": {

869

# "title": "expirable access",

870

# "description": "Does not grant access after Sep 2020",

871

# "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",

# }

# }

# ],

# "etag": "BwWWja0YfJA=",

# "version": 3

# }

#

# **YAML example:**

#

# bindings:

# - members:

# - user:mike@example.com

884

# - group:admins@example.com

885

# - domain:google.com

886

# - serviceAccount:my-project-id@appspot.gserviceaccount.com

887

# role: roles/resourcemanager.organizationAdmin

888

# - members:

889

# - user:eve@example.com

890

# role: roles/resourcemanager.organizationViewer

891

# condition:

892

# title: expirable access

893

# description: Does not grant access after Sep 2020

894

# expression: request.time < timestamp('2020-10-01T00:00:00.000Z')

895

# - etag: BwWWja0YfJA=

896

# - version: 3

897

#

898

# For a description of IAM and its features, see the

899

# [IAM documentation](https://cloud.google.com/iam/docs/).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

900

"bindings": [ # Associates a list of `members` to a `role`. Optionally, may specify a

901

# `condition` that determines how and when the `bindings` are applied. Each

902

# of the `bindings` must contain at least one member.

903

{ # Associates `members` with a `role`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

904

"role": "A String", # Role that is assigned to `members`.

905

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

906

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

907

# `members` can have the following values:

908

#

909

# * `allUsers`: A special identifier that represents anyone who is

910

# on the internet; with or without a Google account.

911

#

912

# * `allAuthenticatedUsers`: A special identifier that represents anyone

913

# who is authenticated with a Google account or a service account.

914

#

915

# * `user:{emailid}`: An email address that represents a specific Google

916

# account. For example, `alice@example.com` .

917

#

918

#

919

# * `serviceAccount:{emailid}`: An email address that represents a service

920

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

921

#

922

# * `group:{emailid}`: An email address that represents a Google group.

923

# For example, `admins@example.com`.

924

#

925

# * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique

926

# identifier) representing a user that has been recently deleted. For

927

# example, `alice@example.com?uid=123456789012345678901`. If the user is

928

# recovered, this value reverts to `user:{emailid}` and the recovered user

929

# retains the role in the binding.

930

#

931

# * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus

932

# unique identifier) representing a service account that has been recently

933

# deleted. For example,

934

# `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.

935

# If the service account is undeleted, this value reverts to

936

# `serviceAccount:{emailid}` and the undeleted service account retains the

937

# role in the binding.

938

#

939

# * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique

940

# identifier) representing a Google group that has been recently

941

# deleted. For example, `admins@example.com?uid=123456789012345678901`. If

942

# the group is recovered, this value reverts to `group:{emailid}` and the

943

# recovered group retains the role in the binding.

944

#

945

#

946

# * `domain:{domain}`: The G Suite domain (primary) that represents all the

947

# users of that domain. For example, `google.com` or `example.com`.

948

#

949

"A String",

950

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

951

"condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.

952

#

953

# If the condition evaluates to `true`, then this binding applies to the

954

# current request.

955

#

956

# If the condition evaluates to `false`, then this binding does not apply to

957

# the current request. However, a different role binding might grant the same

958

# role to one or more of the members in this binding.

959

#

960

# To learn which resources support conditions in their IAM policies, see the

961

# [IAM

962

# documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

963

# syntax. CEL is a C-like expression language. The syntax and semantics of CEL

964

# are documented at https://github.com/google/cel-spec.

965

#

966

# Example (Comparison):

967

#

968

# title: "Summary size limit"

969

# description: "Determines if a summary is less than 100 chars"

970

# expression: "document.summary.size() < 100"

971

#

972

# Example (Equality):

973

#

974

# title: "Requestor is owner"

975

# description: "Determines if requestor is the document owner"

976

# expression: "document.owner == request.auth.claims.email"

#

# Example (Logic):

#

# title: "Public documents"

981

# description: "Determine whether the document should be publicly visible"

982

# expression: "document.type != 'private' && document.type != 'internal'"

983

#

984

# Example (Data Manipulation):

985

#

986

# title: "Notification string"

987

# description: "Create a notification string with a timestamp."

988

# expression: "'New message received at ' + string(document.create_time)"

989

#

990

# The exact variables and functions that may be referenced within an expression

991

# are determined by the service that evaluates it. See the service

992

# documentation for additional information.

993

"expression": "A String", # Textual representation of an expression in Common Expression Language

994

# syntax.

995

"description": "A String", # Optional. Description of the expression. This is a longer text which

996

# describes the expression, e.g. when hovered over it in a UI.

997

"location": "A String", # Optional. String indicating the location of the expression for error

998

# reporting, e.g. a file name and a position in the file.

999

"title": "A String", # Optional. Title for the expression, i.e. a short string describing

1000

# its purpose. This can be used e.g. in UIs which allow to enter the

1001

# expression.

1002

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1003

},

1004

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

1005

"version": 42, # Specifies the format of the policy.

1006

#

1007

# Valid values are `0`, `1`, and `3`. Requests that specify an invalid value

1008

# are rejected.

1009

#

1010

# Any operation that affects conditional role bindings must specify version

1011

# `3`. This requirement applies to the following operations:

1012

#

1013

# * Getting a policy that includes a conditional role binding

1014

# * Adding a conditional role binding to a policy

1015

# * Changing a conditional role binding in a policy

1016

# * Removing any role binding, with or without a condition, from a policy

1017

# that includes conditions

1018

#

1019

# **Important:** If you use IAM Conditions, you must include the `etag` field

1020

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

1021

# you to overwrite a version `3` policy with a version `1` policy, and all of

1022

# the conditions in the version `3` policy are lost.

1023

#

1024

# If a policy does not include any conditions, operations on that policy may

1025

# specify any valid version or leave the field unset.

1026

#

1027

# To learn which resources support conditions in their IAM policies, see the

1028

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1029

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

1030

# prevent simultaneous updates of a policy from overwriting each other.

1031

# It is strongly suggested that systems make use of the `etag` in the

1032

# read-modify-write cycle to perform policy updates in order to avoid race

1033

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

1034

# systems are expected to put that etag in the request to `setIamPolicy` to

1035

# ensure that their change will be applied to the same version of the policy.

1036

#

1037

# **Important:** If you use IAM Conditions, you must include the `etag` field

1038

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

1039

# you to overwrite a version `3` policy with a version `1` policy, and all of

1040

# the conditions in the version `3` policy are lost.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1051

1052

{ # An Identity and Access Management (IAM) policy, which specifies access

1053

# controls for Google Cloud resources.

1054

#

1055

#

1056

# A `Policy` is a collection of `bindings`. A `binding` binds one or more

1057

# `members` to a single `role`. Members can be user accounts, service accounts,

1058

# Google groups, and domains (such as G Suite). A `role` is a named list of

1059

# permissions; each `role` can be an IAM predefined role or a user-created

1060

# custom role.

1061

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

1062

# For some types of Google Cloud resources, a `binding` can also specify a

1063

# `condition`, which is a logical expression that allows access to a resource

1064

# only if the expression evaluates to `true`. A condition can add constraints

1065

# based on attributes of the request, the resource, or both. To learn which

1066

# resources support conditions in their IAM policies, see the

1067

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

#

# **JSON example:**

#

# {

# "bindings": [

# {

# "role": "roles/resourcemanager.organizationAdmin",

1075

# "members": [

1076

# "user:mike@example.com",

1077

# "group:admins@example.com",

1078

# "domain:google.com",

1079

# "serviceAccount:my-project-id@appspot.gserviceaccount.com"

# ]

# },

# {

# "role": "roles/resourcemanager.organizationViewer",

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

1084

# "members": [

1085

# "user:eve@example.com"

1086

# ],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1087

# "condition": {

1088

# "title": "expirable access",

1089

# "description": "Does not grant access after Sep 2020",

1090

# "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",

# }

# }

# ],

# "etag": "BwWWja0YfJA=",

# "version": 3

# }

#

# **YAML example:**

#

# bindings:

# - members:

# - user:mike@example.com

1103

# - group:admins@example.com

1104

# - domain:google.com

1105

# - serviceAccount:my-project-id@appspot.gserviceaccount.com

1106

# role: roles/resourcemanager.organizationAdmin

1107

# - members:

1108

# - user:eve@example.com

1109

# role: roles/resourcemanager.organizationViewer

1110

# condition:

1111

# title: expirable access

1112

# description: Does not grant access after Sep 2020

1113

# expression: request.time < timestamp('2020-10-01T00:00:00.000Z')

1114

# - etag: BwWWja0YfJA=

1115

# - version: 3

1116

#

1117

# For a description of IAM and its features, see the

1118

# [IAM documentation](https://cloud.google.com/iam/docs/).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1119

"bindings": [ # Associates a list of `members` to a `role`. Optionally, may specify a

1120

# `condition` that determines how and when the `bindings` are applied. Each

1121

# of the `bindings` must contain at least one member.

1122

{ # Associates `members` with a `role`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

1123

"role": "A String", # Role that is assigned to `members`.

1124

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1125

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

1126

# `members` can have the following values:

1127

#

1128

# * `allUsers`: A special identifier that represents anyone who is

1129

# on the internet; with or without a Google account.

1130

#

1131

# * `allAuthenticatedUsers`: A special identifier that represents anyone

1132

# who is authenticated with a Google account or a service account.

1133

#

1134

# * `user:{emailid}`: An email address that represents a specific Google

1135

# account. For example, `alice@example.com` .

1136

#

1137

#

1138

# * `serviceAccount:{emailid}`: An email address that represents a service

1139

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

1140

#

1141

# * `group:{emailid}`: An email address that represents a Google group.

1142

# For example, `admins@example.com`.

1143

#

1144

# * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique

1145

# identifier) representing a user that has been recently deleted. For

1146

# example, `alice@example.com?uid=123456789012345678901`. If the user is

1147

# recovered, this value reverts to `user:{emailid}` and the recovered user

1148

# retains the role in the binding.

1149

#

1150

# * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus

1151

# unique identifier) representing a service account that has been recently

1152

# deleted. For example,

1153

# `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.

1154

# If the service account is undeleted, this value reverts to

1155

# `serviceAccount:{emailid}` and the undeleted service account retains the

1156

# role in the binding.

1157

#

1158

# * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique

1159

# identifier) representing a Google group that has been recently

1160

# deleted. For example, `admins@example.com?uid=123456789012345678901`. If

1161

# the group is recovered, this value reverts to `group:{emailid}` and the

1162

# recovered group retains the role in the binding.

1163

#

1164

#

1165

# * `domain:{domain}`: The G Suite domain (primary) that represents all the

1166

# users of that domain. For example, `google.com` or `example.com`.

1167

#

1168

"A String",

1169

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1170

"condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.

1171

#

1172

# If the condition evaluates to `true`, then this binding applies to the

1173

# current request.

1174

#

1175

# If the condition evaluates to `false`, then this binding does not apply to

1176

# the current request. However, a different role binding might grant the same

1177

# role to one or more of the members in this binding.

1178

#

1179

# To learn which resources support conditions in their IAM policies, see the

1180

# [IAM

1181

# documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

1182

# syntax. CEL is a C-like expression language. The syntax and semantics of CEL

1183

# are documented at https://github.com/google/cel-spec.

1184

#

1185

# Example (Comparison):

1186

#

1187

# title: "Summary size limit"

1188

# description: "Determines if a summary is less than 100 chars"

1189

# expression: "document.summary.size() < 100"

1190

#

1191

# Example (Equality):

1192

#

1193

# title: "Requestor is owner"

1194

# description: "Determines if requestor is the document owner"

1195

# expression: "document.owner == request.auth.claims.email"

#

# Example (Logic):

#

# title: "Public documents"

1200

# description: "Determine whether the document should be publicly visible"

1201

# expression: "document.type != 'private' && document.type != 'internal'"

1202

#

1203

# Example (Data Manipulation):

1204

#

1205

# title: "Notification string"

1206

# description: "Create a notification string with a timestamp."

1207

# expression: "'New message received at ' + string(document.create_time)"

1208

#

1209

# The exact variables and functions that may be referenced within an expression

1210

# are determined by the service that evaluates it. See the service

1211

# documentation for additional information.

1212

"expression": "A String", # Textual representation of an expression in Common Expression Language

1213

# syntax.

1214

"description": "A String", # Optional. Description of the expression. This is a longer text which

1215

# describes the expression, e.g. when hovered over it in a UI.

1216

"location": "A String", # Optional. String indicating the location of the expression for error

1217

# reporting, e.g. a file name and a position in the file.

1218

"title": "A String", # Optional. Title for the expression, i.e. a short string describing

1219

# its purpose. This can be used e.g. in UIs which allow to enter the

1220

# expression.

1221

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1222

},

1223

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

1224

"version": 42, # Specifies the format of the policy.

1225

#

1226

# Valid values are `0`, `1`, and `3`. Requests that specify an invalid value

1227

# are rejected.

1228

#

1229

# Any operation that affects conditional role bindings must specify version

1230

# `3`. This requirement applies to the following operations:

1231

#

1232

# * Getting a policy that includes a conditional role binding

1233

# * Adding a conditional role binding to a policy

1234

# * Changing a conditional role binding in a policy

1235

# * Removing any role binding, with or without a condition, from a policy

1236

# that includes conditions

1237

#

1238

# **Important:** If you use IAM Conditions, you must include the `etag` field

1239

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

1240

# you to overwrite a version `3` policy with a version `1` policy, and all of

1241

# the conditions in the version `3` policy are lost.

1242

#

1243

# If a policy does not include any conditions, operations on that policy may

1244

# specify any valid version or leave the field unset.

1245

#

1246

# To learn which resources support conditions in their IAM policies, see the

1247

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1248

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

1249

# prevent simultaneous updates of a policy from overwriting each other.

1250

# It is strongly suggested that systems make use of the `etag` in the

1251

# read-modify-write cycle to perform policy updates in order to avoid race

1252

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

1253

# systems are expected to put that etag in the request to `setIamPolicy` to

1254

# ensure that their change will be applied to the same version of the policy.

1255

#

1256

# **Important:** If you use IAM Conditions, you must include the `etag` field

1257

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

1258

# you to overwrite a version `3` policy with a version `1` policy, and all of

1259

# the conditions in the version `3` policy are lost.

Bu Sun Kim