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

2020-05-01 07:42:23 -0700

[diff] [blame]

88

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

Sai Cheemalapati

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

[diff] [blame]

89

<p class="firstline">Creates a new Cloud Spanner database and starts to prepare it for serving.</p>

90

91

<code><a href="#dropDatabase">dropDatabase(database, x__xgafv=None)</a></code></p>

92

<p class="firstline">Drops (aka deletes) a Cloud Spanner database.</p>

93

Thomas Coffee

2f24537

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

[diff] [blame]

94

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

Sai Cheemalapati

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

[diff] [blame]

95

<p class="firstline">Gets the state of a Cloud Spanner database.</p>

96

97

<code><a href="#getDdl">getDdl(database, x__xgafv=None)</a></code></p>

98

<p class="firstline">Returns the schema of a Cloud Spanner database as a list of formatted</p>

99

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

100

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

101

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

Sai Cheemalapati

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

[diff] [blame]

102

Bu Sun Kim

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

[diff] [blame]

103

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

Sai Cheemalapati

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

[diff] [blame]

104

<p class="firstline">Lists Cloud Spanner databases.</p>

105

106

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

107

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

108

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

109

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

110

<p class="firstline">Create a new database by restoring from a completed backup. The new</p>

Sai Cheemalapati

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

[diff] [blame]

111

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

112

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

113

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

Sai Cheemalapati

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

[diff] [blame]

114

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

115

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

116

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

117

118

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

Sai Cheemalapati

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

[diff] [blame]

119

<p class="firstline">Updates the schema of a Cloud Spanner database by</p>

120

<h3>Method Details</h3>

121

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

122

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

Sai Cheemalapati

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

[diff] [blame]

123

<pre>Creates a new Cloud Spanner database and starts to prepare it for serving.

124

The returned long-running operation will

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

125

have a name of the format `<database_name>/operations/<operation_id>` and

Sai Cheemalapati

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

[diff] [blame]

126

can be used to track preparation of the database. The

127

metadata field type is

128

CreateDatabaseMetadata. The

129

response field type is

130

Database, if successful.

131

132

Args:

133

parent: string, Required. The name of the instance that will serve the new database.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

134

Values are of the form `projects/<project>/instances/<instance>`. (required)

135

body: object, The request body.

Sai Cheemalapati

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

[diff] [blame]

136

The object takes the form of:

137

138

{ # The request for CreateDatabase.

Bu Sun Kim

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

[diff] [blame]

139

"extraStatements": [ # Optional. A list of DDL statements to run inside the newly created

Sai Cheemalapati

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

[diff] [blame]

140

# database. Statements can create tables, indexes, etc. These

141

# statements execute atomically with the creation of the database:

142

# if there is an error in any statement, the database is not created.

Bu Sun Kim

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

[diff] [blame]

143

"A String",

Sai Cheemalapati

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

[diff] [blame]

144

],

Bu Sun Kim

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

[diff] [blame]

145

"createStatement": "A String", # Required. A `CREATE DATABASE` statement, which specifies the ID of the

Sai Cheemalapati

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

[diff] [blame]

146

# new database. The database ID must conform to the regular expression

147

# `a-z*[a-z0-9]` and be between 2 and 30 characters in length.

Sai Cheemalapati

4ba8c23

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

[diff] [blame]

148

# If the database ID is a reserved word or if it contains a hyphen, the

149

# database ID must be enclosed in backticks (`` ` ``).

Sai Cheemalapati

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

[diff] [blame]

150

}

151

152

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

159

160

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

161

# network API call.

Bu Sun Kim

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

[diff] [blame]

162

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

163

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

164

# available.

Bu Sun Kim

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

[diff] [blame]

165

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

166

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

167

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

168

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

169

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

170

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

171

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

172

# `TakeSnapshotResponse`.

Bu Sun Kim

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

[diff] [blame]

173

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

174

},

Bu Sun Kim

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

[diff] [blame]

175

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

176

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

177

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

Bu Sun Kim

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

[diff] [blame]

178

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

179

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

180

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

181

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

182

#

183

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

184

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

185

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

186

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

187

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

188

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

189

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

190

# message types for APIs to use.

191

{

192

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

},

],

},

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

197

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

198

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

199

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

Bu Sun Kim

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

[diff] [blame]

200

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

201

},

Sai Cheemalapati

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

[diff] [blame]

}</pre>

</div>

<code class="details" id="dropDatabase">dropDatabase(database, x__xgafv=None)</code>

207

<pre>Drops (aka deletes) a Cloud Spanner database.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

208

Completed backups for the database will be retained according to their

209

`expire_time`.

Sai Cheemalapati

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

[diff] [blame]

210

211

Args:

212

database: string, Required. The database to be dropped. (required)

213

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

220

221

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

222

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

223

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

224

#

225

# service Foo {

226

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

227

# }

228

#

229

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

}</pre>

</div>

Thomas Coffee

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

[diff] [blame]

234

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

Sai Cheemalapati

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

[diff] [blame]

235

<pre>Gets the state of a Cloud Spanner database.

236

237

Args:

238

name: string, Required. The name of the requested database. Values are of the form

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

239

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

Sai Cheemalapati

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

[diff] [blame]

240

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

247

248

{ # A Cloud Spanner database.

Bu Sun Kim

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

[diff] [blame]

249

"name": "A String", # Required. The name of the database. Values are of the form

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

250

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

251

# where `<database>` is as specified in the `CREATE DATABASE`

Sai Cheemalapati

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

[diff] [blame]

252

# statement. This name can be passed to other API methods to

253

# identify the database.

Bu Sun Kim

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

[diff] [blame]

254

"restoreInfo": { # Information about the database restore. # Output only. Applicable only for restored databases. Contains information

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

255

# about the restore source.

Bu Sun Kim

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

[diff] [blame]

256

"sourceType": "A String", # The type of the restore source.

257

"backupInfo": { # Information about a backup. # Information about the backup used to restore the database. The backup

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

258

# may no longer exist.

Bu Sun Kim

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

[diff] [blame]

259

"sourceDatabase": "A String", # Name of the database the backup was created from.

260

"backup": "A String", # Name of the backup.

261

"createTime": "A String", # The backup contains an externally consistent copy of `source_database` at

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

262

# the timestamp specified by `create_time`.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

263

},

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

264

},

Bu Sun Kim

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

[diff] [blame]

265

"createTime": "A String", # Output only. If exists, the time at which the database creation started.

266

"state": "A String", # Output only. The current database state.

Sai Cheemalapati

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

[diff] [blame]

}</pre>

</div>

<code class="details" id="getDdl">getDdl(database, x__xgafv=None)</code>

272

<pre>Returns the schema of a Cloud Spanner database as a list of formatted

273

DDL statements. This method does not show pending schema updates, those may

274

be queried using the Operations API.

275

276

Args:

277

database: string, Required. The database whose schema we wish to get. (required)

278

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

285

286

{ # The response for GetDatabaseDdl.

Bu Sun Kim

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

[diff] [blame]

287

"statements": [ # A list of formatted DDL statements defining the schema of the database

Sai Cheemalapati

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

[diff] [blame]

288

# specified in the request.

Bu Sun Kim

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

[diff] [blame]

289

"A String",

Sai Cheemalapati

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

[diff] [blame]

],

}</pre>

</div>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

295

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

296

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

297

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

298

policy set.

Sai Cheemalapati

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

[diff] [blame]

299

300

Authorization requires `spanner.databases.getIamPolicy` permission on

301

resource.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

302

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

303

permission on resource.

Sai Cheemalapati

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

[diff] [blame]

304

305

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

306

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)

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

307

body: object, The request body.

Sai Cheemalapati

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

[diff] [blame]

308

The object takes the form of:

309

310

{ # Request message for `GetIamPolicy` method.

Bu Sun Kim

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

[diff] [blame]

311

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

312

# `GetIamPolicy`.

313

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

314

#

315

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

316

# rejected.

317

#

318

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

319

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

320

# leave the field unset.

321

},

Sai Cheemalapati

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

[diff] [blame]

322

}

323

324

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

331

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

332

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

333

# controls for Google Cloud resources.

Sai Cheemalapati

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

[diff] [blame]

334

#

335

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

336

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

337

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

338

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

339

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

340

# custom role.

Sai Cheemalapati

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

[diff] [blame]

341

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

342

# Optionally, a `binding` can specify a `condition`, which is a logical

343

# expression that allows access to a resource only if the expression evaluates

344

# to `true`. A condition can add constraints based on attributes of the

345

# request, the resource, or both.

346

#

347

# **JSON example:**

Sai Cheemalapati

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

[diff] [blame]

348

#

349

# {

Bu Sun Kim

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

[diff] [blame]

350

# "bindings": [

Sai Cheemalapati

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

[diff] [blame]

351

# {

Bu Sun Kim

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

[diff] [blame]

352

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

353

# "members": [

354

# "user:mike@example.com",

355

# "group:admins@example.com",

356

# "domain:google.com",

357

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

Sai Cheemalapati

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

[diff] [blame]

358

# ]

359

# },

360

# {

Bu Sun Kim

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

[diff] [blame]

361

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

362

# "members": ["user:eve@example.com"],

363

# "condition": {

364

# "title": "expirable access",

365

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

366

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

367

# }

Sai Cheemalapati

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

[diff] [blame]

368

# }

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

369

# ],

Bu Sun Kim

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

[diff] [blame]

370

# "etag": "BwWWja0YfJA=",

371

# "version": 3

Sai Cheemalapati

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

[diff] [blame]

372

# }

373

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

374

# **YAML example:**

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

#

# bindings:

# - members:

# - user:mike@example.com

379

# - group:admins@example.com

380

# - domain:google.com

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

381

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

382

# role: roles/resourcemanager.organizationAdmin

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

383

# - members:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

384

# - user:eve@example.com

385

# role: roles/resourcemanager.organizationViewer

386

# condition:

387

# title: expirable access

388

# description: Does not grant access after Sep 2020

Bu Sun Kim

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

[diff] [blame]

389

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

390

# - etag: BwWWja0YfJA=

391

# - version: 3

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

392

#

Sai Cheemalapati

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

[diff] [blame]

393

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

394

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

Bu Sun Kim

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

[diff] [blame]

395

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

396

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

397

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

398

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

399

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

400

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

401

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

402

#

403

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

404

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

405

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

406

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

407

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

408

#

409

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

410

# are rejected.

411

#

412

# Any operation that affects conditional role bindings must specify version

413

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

414

#

415

# * Getting a policy that includes a conditional role binding

416

# * Adding a conditional role binding to a policy

417

# * Changing a conditional role binding in a policy

418

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

419

# that includes conditions

420

#

421

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

422

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

423

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

424

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

425

#

426

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

427

# specify any valid version or leave the field unset.

428

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

429

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

430

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

Sai Cheemalapati

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

[diff] [blame]

431

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

Bu Sun Kim

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

[diff] [blame]

432

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

433

# NOTE: An unsatisfied condition will not allow user access via current

434

# binding. Different bindings, including their conditions, are examined

435

# independently.

436

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

437

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

438

#

439

# Example (Comparison):

440

#

441

# title: "Summary size limit"

442

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

443

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

444

#

445

# Example (Equality):

446

#

447

# title: "Requestor is owner"

448

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

449

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

#

# Example (Logic):

#

# title: "Public documents"

454

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

455

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

456

#

457

# Example (Data Manipulation):

458

#

459

# title: "Notification string"

460

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

461

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

462

#

463

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

464

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

465

# documentation for additional information.

466

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

467

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

468

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

469

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

470

# expression.

471

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

472

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

473

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

474

# syntax.

475

},

476

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

Sai Cheemalapati

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

[diff] [blame]

477

# `members` can have the following values:

478

#

479

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

480

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

481

#

482

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

483

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

484

#

485

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

486

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

Sai Cheemalapati

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

[diff] [blame]

487

#

488

#

489

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

490

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

491

#

492

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

493

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

494

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

495

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

496

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

497

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

498

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

499

# retains the role in the binding.

500

#

501

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

502

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

503

# deleted. For example,

504

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

505

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

506

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

507

# role in the binding.

508

#

509

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

510

# identifier) representing a Google group that has been recently

511

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

512

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

513

# recovered group retains the role in the binding.

514

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

515

#

516

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

Sai Cheemalapati

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

[diff] [blame]

517

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

518

#

Bu Sun Kim

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

[diff] [blame]

519

"A String",

Sai Cheemalapati

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

[diff] [blame]

520

],

Bu Sun Kim

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

[diff] [blame]

521

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

522

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

Sai Cheemalapati

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

[diff] [blame]

523

},

524

],

Sai Cheemalapati

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

[diff] [blame]

}</pre>

</div>

Bu Sun Kim

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

[diff] [blame]

529

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

Sai Cheemalapati

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

[diff] [blame]

530

<pre>Lists Cloud Spanner databases.

531

532

Args:

533

parent: string, Required. The instance whose databases should be listed.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

534

Values are of the form `projects/<project>/instances/<instance>`. (required)

Sai Cheemalapati

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

[diff] [blame]

535

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

536

next_page_token from a

537

previous ListDatabasesResponse.

Bu Sun Kim

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

[diff] [blame]

538

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

539

defaults to the server's maximum allowed page size.

Sai Cheemalapati

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

[diff] [blame]

540

x__xgafv: string, V1 error format.

541

Allowed values

542

1 - v1 error format

543

2 - v2 error format

Sai Cheemalapati

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

[diff] [blame]

544

545

Returns:

546

An object of the form:

547

548

{ # The response for ListDatabases.

Bu Sun Kim

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

[diff] [blame]

549

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

Sai Cheemalapati

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

[diff] [blame]

550

# ListDatabases call to fetch more

551

# of the matching databases.

Bu Sun Kim

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

[diff] [blame]

552

"databases": [ # Databases that matched the request.

Sai Cheemalapati

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

[diff] [blame]

553

{ # A Cloud Spanner database.

Bu Sun Kim

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

[diff] [blame]

554

"name": "A String", # Required. The name of the database. Values are of the form

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

555

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

556

# where `<database>` is as specified in the `CREATE DATABASE`

Sai Cheemalapati

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

[diff] [blame]

557

# statement. This name can be passed to other API methods to

558

# identify the database.

Bu Sun Kim

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

[diff] [blame]

559

"restoreInfo": { # Information about the database restore. # Output only. Applicable only for restored databases. Contains information

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

560

# about the restore source.

Bu Sun Kim

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

[diff] [blame]

561

"sourceType": "A String", # The type of the restore source.

562

"backupInfo": { # Information about a backup. # Information about the backup used to restore the database. The backup

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

563

# may no longer exist.

Bu Sun Kim

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

[diff] [blame]

564

"sourceDatabase": "A String", # Name of the database the backup was created from.

565

"backup": "A String", # Name of the backup.

566

"createTime": "A String", # The backup contains an externally consistent copy of `source_database` at

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

567

# the timestamp specified by `create_time`.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

568

},

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

569

},

Bu Sun Kim

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

[diff] [blame]

570

"createTime": "A String", # Output only. If exists, the time at which the database creation started.

571

"state": "A String", # Output only. The current database state.

Sai Cheemalapati

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

[diff] [blame]

},

],

}</pre>

</div>

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

579

<pre>Retrieves the next page of results.

580

581

Args:

582

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

583

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

584

585

Returns:

Bu Sun Kim

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

[diff] [blame]

586

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

Sai Cheemalapati

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

[diff] [blame]

587

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

</pre>

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

592

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

593

<pre>Create a new database by restoring from a completed backup. The new

594

database must be in the same project and in an instance with the same

595

instance configuration as the instance containing

596

the backup. The returned database long-running

597

operation has a name of the format

598

`projects/<project>/instances/<instance>/databases/<database>/operations/<operation_id>`,

599

and can be used to track the progress of the operation, and to cancel it.

600

The metadata field type is

601

RestoreDatabaseMetadata.

602

The response type

603

is Database, if

604

successful. Cancelling the returned operation will stop the restore and

605

delete the database.

606

There can be only one database being restored into an instance at a time.

607

Once the restore operation completes, a new restore operation can be

608

initiated, without waiting for the optimize operation associated with the

609

first restore to complete.

Sai Cheemalapati

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

[diff] [blame]

610

611

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

612

parent: string, Required. The name of the instance in which to create the

613

restored database. This instance must be in the same project and

614

have the same instance configuration as the instance containing

615

the source backup. Values are of the form

616

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

617

body: object, The request body.

Sai Cheemalapati

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

[diff] [blame]

618

The object takes the form of:

619

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

620

{ # The request for

621

# RestoreDatabase.

Bu Sun Kim

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

[diff] [blame]

622

"databaseId": "A String", # Required. The id of the database to create and restore to. This

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

623

# database must not already exist. The `database_id` appended to

624

# `parent` forms the full database name of the form

625

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

Bu Sun Kim

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

[diff] [blame]

626

"backup": "A String", # Name of the backup from which to restore. Values are of the form

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

627

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

Sai Cheemalapati

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

[diff] [blame]

628

}

629

630

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

637

638

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

639

# network API call.

Bu Sun Kim

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

[diff] [blame]

640

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

641

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

642

# available.

Bu Sun Kim

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

[diff] [blame]

643

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

644

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

645

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

646

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

647

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

648

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

649

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

650

# `TakeSnapshotResponse`.

Bu Sun Kim

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

[diff] [blame]

651

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

652

},

Bu Sun Kim

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

[diff] [blame]

653

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

654

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

655

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

Bu Sun Kim

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

[diff] [blame]

656

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

657

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

658

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

659

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

660

#

661

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

662

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

663

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

664

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

665

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

666

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

667

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

668

# message types for APIs to use.

669

{

670

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

},

],

},

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

675

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

676

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

677

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

Bu Sun Kim

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

[diff] [blame]

678

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

},

}</pre>

</div>

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

685

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

686

Replaces any existing policy.

687

688

Authorization requires `spanner.databases.setIamPolicy`

689

permission on resource.

690

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

691

permission on resource.

692

693

Args:

694

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)

695

body: object, The request body.

696

The object takes the form of:

697

698

{ # Request message for `SetIamPolicy` method.

Bu Sun Kim

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

[diff] [blame]

699

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

700

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

701

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

702

# might reject them.

703

# controls for Google Cloud resources.

704

#

705

#

706

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

707

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

708

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

709

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

710

# custom role.

711

#

712

# Optionally, a `binding` can specify a `condition`, which is a logical

713

# expression that allows access to a resource only if the expression evaluates

714

# to `true`. A condition can add constraints based on attributes of the

715

# request, the resource, or both.

#

# **JSON example:**

#

# {

Bu Sun Kim

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

[diff] [blame]

720

# "bindings": [

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

721

# {

Bu Sun Kim

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

[diff] [blame]

722

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

723

# "members": [

724

# "user:mike@example.com",

725

# "group:admins@example.com",

726

# "domain:google.com",

727

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

728

# ]

729

# },

730

# {

Bu Sun Kim

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

[diff] [blame]

731

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

732

# "members": ["user:eve@example.com"],

733

# "condition": {

734

# "title": "expirable access",

735

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

736

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

737

# }

738

# }

739

# ],

Bu Sun Kim

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

[diff] [blame]

740

# "etag": "BwWWja0YfJA=",

741

# "version": 3

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

# }

#

# **YAML example:**

#

# bindings:

# - members:

# - user:mike@example.com

749

# - group:admins@example.com

750

# - domain:google.com

751

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

752

# role: roles/resourcemanager.organizationAdmin

753

# - members:

754

# - user:eve@example.com

755

# role: roles/resourcemanager.organizationViewer

756

# condition:

757

# title: expirable access

758

# description: Does not grant access after Sep 2020

Bu Sun Kim

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

[diff] [blame]

759

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

760

# - etag: BwWWja0YfJA=

761

# - version: 3

762

#

763

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

764

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

Bu Sun Kim

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

[diff] [blame]

765

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

766

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

767

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

768

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

769

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

770

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

771

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

772

#

773

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

774

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

775

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

776

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

777

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

778

#

779

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

780

# are rejected.

781

#

782

# Any operation that affects conditional role bindings must specify version

783

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

784

#

785

# * Getting a policy that includes a conditional role binding

786

# * Adding a conditional role binding to a policy

787

# * Changing a conditional role binding in a policy

788

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

789

# that includes conditions

790

#

791

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

792

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

793

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

794

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

795

#

796

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

797

# specify any valid version or leave the field unset.

798

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

799

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

800

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

801

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

Bu Sun Kim

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

[diff] [blame]

802

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

803

# NOTE: An unsatisfied condition will not allow user access via current

804

# binding. Different bindings, including their conditions, are examined

805

# independently.

806

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

807

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

808

#

809

# Example (Comparison):

810

#

811

# title: "Summary size limit"

812

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

813

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

814

#

815

# Example (Equality):

816

#

817

# title: "Requestor is owner"

818

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

819

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

#

# Example (Logic):

#

# title: "Public documents"

824

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

825

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

826

#

827

# Example (Data Manipulation):

828

#

829

# title: "Notification string"

830

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

831

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

832

#

833

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

834

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

835

# documentation for additional information.

836

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

837

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

838

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

839

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

840

# expression.

841

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

842

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

843

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

844

# syntax.

845

},

846

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

847

# `members` can have the following values:

848

#

849

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

850

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

851

#

852

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

853

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

854

#

855

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

856

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

857

#

858

#

859

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

860

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

861

#

862

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

863

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

864

#

865

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

866

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

867

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

868

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

869

# retains the role in the binding.

870

#

871

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

872

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

873

# deleted. For example,

874

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

875

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

876

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

877

# role in the binding.

878

#

879

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

880

# identifier) representing a Google group that has been recently

881

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

882

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

883

# recovered group retains the role in the binding.

884

#

885

#

886

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

887

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

888

#

Bu Sun Kim

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

[diff] [blame]

889

"A String",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

890

],

Bu Sun Kim

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

[diff] [blame]

891

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

892

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

893

},

894

],

Dan O'Meara

2020-05-01 07:42:23 -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:

905

906

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

907

# controls for Google Cloud resources.

908

#

909

#

910

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

911

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

912

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

913

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

914

# custom role.

915

#

916

# Optionally, a `binding` can specify a `condition`, which is a logical

917

# expression that allows access to a resource only if the expression evaluates

918

# to `true`. A condition can add constraints based on attributes of the

919

# request, the resource, or both.

#

# **JSON example:**

#

# {

Bu Sun Kim

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

[diff] [blame]

924

# "bindings": [

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

925

# {

Bu Sun Kim

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

[diff] [blame]

926

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

927

# "members": [

928

# "user:mike@example.com",

929

# "group:admins@example.com",

930

# "domain:google.com",

931

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

932

# ]

933

# },

934

# {

Bu Sun Kim

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

[diff] [blame]

935

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

936

# "members": ["user:eve@example.com"],

937

# "condition": {

938

# "title": "expirable access",

939

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

940

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

941

# }

942

# }

943

# ],

Bu Sun Kim

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

[diff] [blame]

944

# "etag": "BwWWja0YfJA=",

945

# "version": 3

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

# }

#

# **YAML example:**

#

# bindings:

# - members:

# - user:mike@example.com

953

# - group:admins@example.com

954

# - domain:google.com

955

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

956

# role: roles/resourcemanager.organizationAdmin

957

# - members:

958

# - user:eve@example.com

959

# role: roles/resourcemanager.organizationViewer

960

# condition:

961

# title: expirable access

962

# description: Does not grant access after Sep 2020

Bu Sun Kim

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

[diff] [blame]

963

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

964

# - etag: BwWWja0YfJA=

965

# - version: 3

966

#

967

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

968

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

Bu Sun Kim

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

[diff] [blame]

969

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

970

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

971

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

972

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

973

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

974

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

975

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

976

#

977

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

978

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

979

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

980

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

981

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

982

#

983

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

984

# are rejected.

985

#

986

# Any operation that affects conditional role bindings must specify version

987

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

988

#

989

# * Getting a policy that includes a conditional role binding

990

# * Adding a conditional role binding to a policy

991

# * Changing a conditional role binding in a policy

992

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

993

# that includes conditions

994

#

995

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

996

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

997

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

998

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

999

#

1000

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

1001

# specify any valid version or leave the field unset.

1002

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1003

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

1004

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

1005

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

Bu Sun Kim

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

[diff] [blame]

1006

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

1007

# NOTE: An unsatisfied condition will not allow user access via current

1008

# binding. Different bindings, including their conditions, are examined

1009

# independently.

1010

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

1011

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

1012

#

1013

# Example (Comparison):

1014

#

1015

# title: "Summary size limit"

1016

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

1017

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

1018

#

1019

# Example (Equality):

1020

#

1021

# title: "Requestor is owner"

1022

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

1023

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

#

# Example (Logic):

#

# title: "Public documents"

1028

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

1029

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

1030

#

1031

# Example (Data Manipulation):

1032

#

1033

# title: "Notification string"

1034

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

1035

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

1036

#

1037

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

1038

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

1039

# documentation for additional information.

1040

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

1041

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

1042

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

1043

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

1044

# expression.

1045

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

1046

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

1047

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

1048

# syntax.

1049

},

1050

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1051

# `members` can have the following values:

1052

#

1053

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

1054

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

1055

#

1056

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

1057

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

1058

#

1059

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

1060

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

1061

#

1062

#

1063

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

1064

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

1065

#

1066

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

1067

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

1068

#

1069

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

1070

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

1071

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

1072

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

1073

# retains the role in the binding.

1074

#

1075

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

1076

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

1077

# deleted. For example,

1078

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

1079

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

1080

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

1081

# role in the binding.

1082

#

1083

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

1084

# identifier) representing a Google group that has been recently

1085

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

1086

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

1087

# recovered group retains the role in the binding.

1088

#

1089

#

1090

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

1091

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

1092

#

Bu Sun Kim

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

[diff] [blame]

1093

"A String",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1094

],

Bu Sun Kim

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

[diff] [blame]

1095

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

1096

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1097

},

1098

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

}</pre>

</div>

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

1104

<pre>Returns permissions that the caller has on the specified database or backup

1105

resource.

1106

1107

Attempting this RPC on a non-existent Cloud Spanner database will

1108

result in a NOT_FOUND error if the user has

1109

`spanner.databases.list` permission on the containing Cloud

1110

Spanner instance. Otherwise returns an empty set of permissions.

1111

Calling this method on a backup that does not exist will

1112

result in a NOT_FOUND error if the user has

1113

`spanner.backups.list` permission on the containing instance.

1114

1115

Args:

1116

resource: string, REQUIRED: The Cloud Spanner resource for which permissions are being tested. 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)

1117

body: object, The request body.

1118

The object takes the form of:

1119

1120

{ # Request message for `TestIamPermissions` method.

Bu Sun Kim

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

[diff] [blame]

1121

"permissions": [ # REQUIRED: The set of permissions to check for 'resource'.

1122

# Permissions with wildcards (such as '*', 'spanner.*', 'spanner.instances.*') are not allowed.

1123

"A String",

Dan O'Meara

2020-05-01 07:42:23 -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:

1134

1135

{ # Response message for `TestIamPermissions` method.

Bu Sun Kim

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

[diff] [blame]

1136

"permissions": [ # A subset of `TestPermissionsRequest.permissions` that the caller is

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1137

# allowed.

Bu Sun Kim

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

[diff] [blame]

1138

"A String",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

],

}</pre>

</div>

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

1145

<pre>Updates the schema of a Cloud Spanner database by

1146

creating/altering/dropping tables, columns, indexes, etc. The returned

1147

long-running operation will have a name of

1148

the format `<database_name>/operations/<operation_id>` and can be used to

1149

track execution of the schema change(s). The

1150

metadata field type is

1151

UpdateDatabaseDdlMetadata. The operation has no response.

1152

1153

Args:

1154

database: string, Required. The database to update. (required)

1155

body: object, The request body.

1156

The object takes the form of:

1157

1158

{ # Enqueues the given DDL statements to be applied, in order but not

1159

# necessarily all at once, to the database schema at some point (or

1160

# points) in the future. The server checks that the statements

1161

# are executable (syntactically valid, name tables that exist, etc.)

1162

# before enqueueing them, but they may still fail upon

1163

# later execution (e.g., if a statement from another batch of

1164

# statements is applied first and it conflicts in some way, or if

1165

# there is some data-related problem like a `NULL` value in a column to

1166

# which `NOT NULL` would be added). If a statement fails, all

1167

# subsequent statements in the batch are automatically cancelled.

1168

#

1169

# Each batch of statements is assigned a name which can be used with

1170

# the Operations API to monitor

1171

# progress. See the

1172

# operation_id field for more

1173

# details.

Bu Sun Kim

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

[diff] [blame]

1174

"statements": [ # Required. DDL statements to be applied to the database.

1175

"A String",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1176

],

Bu Sun Kim

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

[diff] [blame]

1177

"operationId": "A String", # If empty, the new update request is assigned an

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1178

# automatically-generated operation ID. Otherwise, `operation_id`

1179

# is used to construct the name of the resulting

1180

# Operation.

1181

#

1182

# Specifying an explicit operation ID simplifies determining

1183

# whether the statements were executed in the event that the

1184

# UpdateDatabaseDdl call is replayed,

1185

# or the return value is otherwise lost: the database and

1186

# `operation_id` fields can be combined to form the

1187

# name of the resulting

1188

# longrunning.Operation: `<database>/operations/<operation_id>`.

1189

#

1190

# `operation_id` should be unique within the database, and must be

1191

# a valid identifier: `a-z*`. Note that

1192

# automatically-generated operation IDs always begin with an

1193

# underscore. If the named operation already exists,

1194

# UpdateDatabaseDdl returns

# `ALREADY_EXISTS`.

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1205

1206

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

1207

# network API call.

Bu Sun Kim

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

[diff] [blame]

1208

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1209

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

1210

# available.

Bu Sun Kim

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

[diff] [blame]

1211

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1212

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

1213

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

1214

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

1215

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

1216

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

1217

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

1218

# `TakeSnapshotResponse`.

Bu Sun Kim

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

[diff] [blame]

1219

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1220

},

Bu Sun Kim

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

[diff] [blame]

1221

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1222

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

1223

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

Bu Sun Kim