Blame - docs/dyn/ml_v1.projects.models.html - platform/external/python/google-api-python-client

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

[diff] [blame]

76

<h2>Instance Methods</h2>

77

78

<code><a href="ml_v1.projects.models.versions.html">versions()</a></code>

79

</p>

80

<p class="firstline">Returns the versions Resource.</p>

81

82

Dan O'Meara

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

[diff] [blame]

83

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

84

<p class="firstline">Creates a model which will later contain one or more versions.</p>

85

Thomas Coffee

2f24537

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

[diff] [blame]

86

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

Sai Cheemalapati

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

[diff] [blame]

87

<p class="firstline">Deletes a model.</p>

88

Thomas Coffee

2f24537

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

[diff] [blame]

89

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

Sai Cheemalapati

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

[diff] [blame]

90

<p class="firstline">Gets information about a model, including its name, the description (if</p>

91

Dan O'Meara

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

[diff] [blame]

92

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

Bu Sun Kim

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

[diff] [blame]

93

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

94

Bu Sun Kim

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

[diff] [blame]

95

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

Sai Cheemalapati

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

[diff] [blame]

96

<p class="firstline">Lists the models in a project.</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>

Bu Sun Kim

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

[diff] [blame]

100

Dan O'Meara

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

[diff] [blame]

101

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

Bu Sun Kim

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

[diff] [blame]

102

<p class="firstline">Updates a specific model resource.</p>

103

Dan O'Meara

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

[diff] [blame]

104

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

Bu Sun Kim

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

[diff] [blame]

105

<p class="firstline">Sets the access control policy on the specified resource. Replaces any</p>

106

Dan O'Meara

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

[diff] [blame]

107

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

Bu Sun Kim

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

[diff] [blame]

108

<p class="firstline">Returns permissions that a caller has on the specified resource.</p>

Sai Cheemalapati

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

[diff] [blame]

109

<h3>Method Details</h3>

110

Dan O'Meara

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

[diff] [blame]

111

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

Sai Cheemalapati

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

[diff] [blame]

112

<pre>Creates a model which will later contain one or more versions.

113

114

You must add at least one version before you can request predictions from

115

the model. Add versions by calling

Dan O'Meara

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

[diff] [blame]

116

projects.models.versions.create.

Sai Cheemalapati

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

[diff] [blame]

117

118

Args:

Bu Sun Kim

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

[diff] [blame]

119

parent: string, Required. The project name. (required)

Dan O'Meara

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

[diff] [blame]

120

body: object, The request body.

Sai Cheemalapati

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

[diff] [blame]

121

The object takes the form of:

122

123

{ # Represents a machine learning solution.

Bu Sun Kim

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

[diff] [blame^]

124

#

125

# A model can have multiple versions, each of which is a deployed, trained

126

# model ready to receive prediction requests. The model itself is just a

127

# container.

128

"defaultVersion": { # Represents a version of the model. # Output only. The default version of the model. This version will be used to

129

# handle prediction requests that do not specify a version.

Dan O'Meara

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

[diff] [blame]

130

#

Bu Sun Kim

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

[diff] [blame^]

131

# You can change the default version by calling

132

# projects.models.versions.setDefault.

133

#

134

# Each version is a trained model deployed in the cloud, ready to handle

135

# prediction requests. A model can have multiple versions. You can get

136

# information about all of the versions of a given model by calling

137

# projects.models.versions.list.

138

"acceleratorConfig": { # Represents a hardware accelerator request config. # Optional. Accelerator config for using GPUs for online prediction (beta).

139

# Only specify this field if you have specified a Compute Engine (N1) machine

140

# type in the `machineType` field. Learn more about [using GPUs for online

141

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

142

# Note that the AcceleratorConfig can be used in both Jobs and Versions.

143

# Learn more about [accelerators for training](/ml-engine/docs/using-gpus) and

144

# [accelerators for online

145

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

146

"count": "A String", # The number of accelerators to attach to each machine running the job.

147

"type": "A String", # The type of accelerator to use.

148

},

149

"isDefault": True or False, # Output only. If true, this version will be used to handle prediction

150

# requests that do not specify a version.

151

#

152

# You can change the default version by calling

153

# projects.methods.versions.setDefault.

154

"manualScaling": { # Options for manually scaling a model. # Manually select the number of nodes to use for serving the

155

# model. You should generally use `auto_scaling` with an appropriate

156

# `min_nodes` instead, but this option is available if you want more

157

# predictable billing. Beware that latency and error rates will increase

158

# if the traffic exceeds that capability of the system to serve it based

159

# on the selected number of nodes.

160

"nodes": 42, # The number of nodes to allocate for this model. These nodes are always up,

161

# starting from the time the model is deployed, so the cost of operating

162

# this model will be proportional to `nodes` * number of hours since

163

# last billing cycle plus the cost for each prediction performed.

164

},

165

"state": "A String", # Output only. The state of a version.

166

"name": "A String", # Required. The name specified for the version when it was created.

167

#

168

# The version name must be unique within the model it is created in.

169

"serviceAccount": "A String", # Optional. Specifies the service account for resource access control.

170

"pythonVersion": "A String", # Required. The version of Python used in prediction.

171

#

172

# The following Python versions are available:

173

#

174

# * Python '3.7' is available when `runtime_version` is set to '1.15' or

175

# later.

176

# * Python '3.5' is available when `runtime_version` is set to a version

177

# from '1.4' to '1.14'.

178

# * Python '2.7' is available when `runtime_version` is set to '1.15' or

179

# earlier.

180

#

181

# Read more about the Python versions available for [each runtime

182

# version](/ml-engine/docs/runtime-version-list).

183

"lastUseTime": "A String", # Output only. The time the version was last used for prediction.

184

"predictionClass": "A String", # Optional. The fully qualified name

185

# (<var>module_name</var>.<var>class_name</var>) of a class that implements

186

# the Predictor interface described in this reference field. The module

187

# containing this class should be included in a package provided to the

188

# [`packageUris` field](#Version.FIELDS.package_uris).

189

#

190

# Specify this field if and only if you are deploying a [custom prediction

191

# routine (beta)](/ml-engine/docs/tensorflow/custom-prediction-routines).

192

# If you specify this field, you must set

193

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater and

194

# you must set `machineType` to a [legacy (MLS1)

195

# machine type](/ml-engine/docs/machine-types-online-prediction).

196

#

197

# The following code sample provides the Predictor interface:

198

#

199

# <pre style="max-width: 626px;">

200

# class Predictor(object):

201

# """Interface for constructing custom predictors."""

202

#

203

# def predict(self, instances, **kwargs):

204

# """Performs custom prediction.

205

#

206

# Instances are the decoded values from the request. They have already

207

# been deserialized from JSON.

208

#

209

# Args:

210

# instances: A list of prediction input instances.

211

# **kwargs: A dictionary of keyword args provided as additional

212

# fields on the predict request body.

213

#

214

# Returns:

215

# A list of outputs containing the prediction results. This list must

216

# be JSON serializable.

217

# """

218

# raise NotImplementedError()

219

#

220

# @classmethod

221

# def from_path(cls, model_dir):

222

# """Creates an instance of Predictor using the given path.

223

#

224

# Loading of the predictor should be done in this method.

225

#

226

# Args:

227

# model_dir: The local directory that contains the exported model

228

# file along with any additional files uploaded when creating the

# version resource.

#

# Returns:

# An instance implementing this Predictor class.

233

# """

234

# raise NotImplementedError()

235

# </pre>

236

#

237

# Learn more about [the Predictor interface and custom prediction

238

# routines](/ml-engine/docs/tensorflow/custom-prediction-routines).

239

"deploymentUri": "A String", # Required. The Cloud Storage location of the trained model used to

240

# create the version. See the

241

# [guide to model

242

# deployment](/ml-engine/docs/tensorflow/deploying-models) for more

243

# information.

244

#

245

# When passing Version to

246

# projects.models.versions.create

247

# the model service uses the specified location as the source of the model.

248

# Once deployed, the model version is hosted by the prediction service, so

249

# this location is useful only as a historical record.

250

# The total number of model files can't exceed 1000.

251

"packageUris": [ # Optional. Cloud Storage paths (`gs://…`) of packages for [custom

252

# prediction routines](/ml-engine/docs/tensorflow/custom-prediction-routines)

253

# or [scikit-learn pipelines with custom

254

# code](/ml-engine/docs/scikit/exporting-for-prediction#custom-pipeline-code).

255

#

256

# For a custom prediction routine, one of these packages must contain your

257

# Predictor class (see

258

# [`predictionClass`](#Version.FIELDS.prediction_class)). Additionally,

259

# include any dependencies used by your Predictor or scikit-learn pipeline

260

# uses that are not already included in your selected [runtime

261

# version](/ml-engine/docs/tensorflow/runtime-version-list).

262

#

263

# If you specify this field, you must also set

264

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater.

265

"A String",

266

],

267

"explanationConfig": { # Message holding configuration options for explaining model predictions. # Optional. Configures explainability features on the model's version.

268

# Some explanation features require additional metadata to be loaded

269

# as part of the model payload.

270

# There are two feature attribution methods supported for TensorFlow models:

271

# integrated gradients and sampled Shapley.

272

# [Learn more about feature

273

# attributions.](/ai-platform/prediction/docs/ai-explanations/overview)

274

"integratedGradientsAttribution": { # Attributes credit by computing the Aumann-Shapley value taking advantage # Attributes credit by computing the Aumann-Shapley value taking advantage

275

# of the model's fully differentiable structure. Refer to this paper for

276

# more details: http://proceedings.mlr.press/v70/sundararajan17a.html

277

# of the model's fully differentiable structure. Refer to this paper for

278

# more details: https://arxiv.org/abs/1703.01365

279

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

280

# A good value to start is 50 and gradually increase until the

281

# sum to diff property is met within the desired error range.

282

},

283

"sampledShapleyAttribution": { # An attribution method that approximates Shapley values for features that # An attribution method that approximates Shapley values for features that

284

# contribute to the label being predicted. A sampling strategy is used to

285

# approximate the value rather than considering all subsets of features.

286

# contribute to the label being predicted. A sampling strategy is used to

287

# approximate the value rather than considering all subsets of features.

288

"numPaths": 42, # The number of feature permutations to consider when approximating the

289

# Shapley values.

290

},

291

"xraiAttribution": { # Attributes credit by computing the XRAI taking advantage # Attributes credit by computing the XRAI taking advantage

292

# of the model's fully differentiable structure. Refer to this paper for

293

# more details: https://arxiv.org/abs/1906.02825

294

# Currently only implemented for models with natural image inputs.

295

# of the model's fully differentiable structure. Refer to this paper for

296

# more details: https://arxiv.org/abs/1906.02825

297

# Currently only implemented for models with natural image inputs.

298

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

299

# A good value to start is 50 and gradually increase until the

300

# sum to diff property is met within the desired error range.

301

},

302

},

303

"autoScaling": { # Options for automatically scaling a model. # Automatically scale the number of nodes used to serve the model in

304

# response to increases and decreases in traffic. Care should be

305

# taken to ramp up traffic according to the model's ability to scale

306

# or you will start seeing increases in latency and 429 response codes.

307

#

308

# Note that you cannot use AutoScaling if your version uses

309

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use specify

310

# `manual_scaling`.

311

"minNodes": 42, # Optional. The minimum number of nodes to allocate for this model. These

312

# nodes are always up, starting from the time the model is deployed.

313

# Therefore, the cost of operating this model will be at least

314

# `rate` * `min_nodes` * number of hours since last billing cycle,

315

# where `rate` is the cost per node-hour as documented in the

316

# [pricing guide](/ml-engine/docs/pricing),

317

# even if no predictions are performed. There is additional cost for each

318

# prediction performed.

319

#

320

# Unlike manual scaling, if the load gets too heavy for the nodes

321

# that are up, the service will automatically add nodes to handle the

322

# increased load as well as scale back as traffic drops, always maintaining

323

# at least `min_nodes`. You will be charged for the time in which additional

324

# nodes are used.

325

#

326

# If `min_nodes` is not specified and AutoScaling is used with a [legacy

327

# (MLS1) machine type](/ml-engine/docs/machine-types-online-prediction),

328

# `min_nodes` defaults to 0, in which case, when traffic to a model stops

329

# (and after a cool-down period), nodes will be shut down and no charges will

330

# be incurred until traffic to the model resumes.

331

#

332

# If `min_nodes` is not specified and AutoScaling is used with a [Compute

333

# Engine (N1) machine type](/ml-engine/docs/machine-types-online-prediction),

334

# `min_nodes` defaults to 1. `min_nodes` must be at least 1 for use with a

335

# Compute Engine machine type.

336

#

337

# Note that you cannot use AutoScaling if your version uses

338

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use

339

# ManualScaling.

340

#

341

# You can set `min_nodes` when creating the model version, and you can also

342

# update `min_nodes` for an existing version:

# <pre>

# update_body.json:

# {

# 'autoScaling': {

# 'minNodes': 5

# }

# }

# </pre>

# HTTP request:

# <pre style="max-width: 626px;">

353

# PATCH

354

# https://ml.googleapis.com/v1/{name=projects/*/models/*/versions/*}?update_mask=autoScaling.minNodes

355

# -d @./update_body.json

356

# </pre>

357

},

358

"createTime": "A String", # Output only. The time the version was created.

359

"labels": { # Optional. One or more labels that you can add, to organize your model

360

# versions. Each label is a key-value pair, where both the key and the value

361

# are arbitrary strings that you supply.

Bu Sun Kim

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

[diff] [blame]

362

# For more information, see the documentation on

Bu Sun Kim

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

[diff] [blame]

363

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

364

"a_key": "A String",

Bu Sun Kim

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

[diff] [blame]

365

},

Bu Sun Kim

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

[diff] [blame^]

366

"requestLoggingConfig": { # Configuration for logging request-response pairs to a BigQuery table. # Optional. *Only* specify this field in a

367

# projects.models.versions.patch

368

# request. Specifying it in a

369

# projects.models.versions.create

370

# request has no effect.

371

#

372

# Configures the request-response pair logging on predictions from this

373

# Version.

374

# Online prediction requests to a model version and the responses to these

375

# requests are converted to raw strings and saved to the specified BigQuery

376

# table. Logging is constrained by [BigQuery quotas and

377

# limits](/bigquery/quotas). If your project exceeds BigQuery quotas or limits,

378

# AI Platform Prediction does not log request-response pairs, but it continues

379

# to serve predictions.

380

#

381

# If you are using [continuous

382

# evaluation](/ml-engine/docs/continuous-evaluation/), you do not need to

383

# specify this configuration manually. Setting up continuous evaluation

384

# automatically enables logging of request-response pairs.

385

"bigqueryTableName": "A String", # Required. Fully qualified BigQuery table name in the following format:

386

# "<var>project_id</var>.<var>dataset_name</var>.<var>table_name</var>"

387

#

388

# The specified table must already exist, and the "Cloud ML Service Agent"

389

# for your project must have permission to write to it. The table must have

390

# the following [schema](/bigquery/docs/schemas):

391

#

392

# <table>

393

# <tr><th>Field name</th><th style="display: table-cell">Type</th>

394

# <th style="display: table-cell">Mode</th></tr>

395

# <tr><td>model</td><td>STRING</td><td>REQUIRED</td></tr>

396

# <tr><td>model_version</td><td>STRING</td><td>REQUIRED</td></tr>

397

# <tr><td>time</td><td>TIMESTAMP</td><td>REQUIRED</td></tr>

398

# <tr><td>raw_data</td><td>STRING</td><td>REQUIRED</td></tr>

399

# <tr><td>raw_prediction</td><td>STRING</td><td>NULLABLE</td></tr>

400

# <tr><td>groundtruth</td><td>STRING</td><td>NULLABLE</td></tr>

401

# </table>

402

"samplingPercentage": 3.14, # Percentage of requests to be logged, expressed as a fraction from 0 to 1.

403

# For example, if you want to log 10% of requests, enter `0.1`. The sampling

404

# window is the lifetime of the model version. Defaults to 0.

405

},

406

"errorMessage": "A String", # Output only. The details of a failure or a cancellation.

407

"machineType": "A String", # Optional. The type of machine on which to serve the model. Currently only

408

# applies to online prediction service. If this field is not specified, it

409

# defaults to `mls1-c1-m2`.

410

#

411

# Online prediction supports the following machine types:

#

# * `mls1-c1-m2`

# * `mls1-c4-m2`

# * `n1-standard-2`

# * `n1-standard-4`

# * `n1-standard-8`

# * `n1-standard-16`

# * `n1-standard-32`

# * `n1-highmem-2`

# * `n1-highmem-4`

# * `n1-highmem-8`

# * `n1-highmem-16`

# * `n1-highmem-32`

# * `n1-highcpu-2`

# * `n1-highcpu-4`

# * `n1-highcpu-8`

# * `n1-highcpu-16`

# * `n1-highcpu-32`

#

# `mls1-c1-m2` is generally available. All other machine types are available

432

# in beta. Learn more about the [differences between machine

433

# types](/ml-engine/docs/machine-types-online-prediction).

434

"runtimeVersion": "A String", # Required. The AI Platform runtime version to use for this deployment.

435

#

436

# For more information, see the

437

# [runtime version list](/ml-engine/docs/runtime-version-list) and

438

# [how to manage runtime versions](/ml-engine/docs/versioning).

439

"description": "A String", # Optional. The description specified for the version when it was created.

440

"framework": "A String", # Optional. The machine learning framework AI Platform uses to train

441

# this version of the model. Valid values are `TENSORFLOW`, `SCIKIT_LEARN`,

442

# `XGBOOST`. If you do not specify a framework, AI Platform

443

# will analyze files in the deployment_uri to determine a framework. If you

444

# choose `SCIKIT_LEARN` or `XGBOOST`, you must also set the runtime version

445

# of the model to 1.4 or greater.

446

#

447

# Do **not** specify a framework if you're deploying a [custom

448

# prediction routine](/ml-engine/docs/tensorflow/custom-prediction-routines).

449

#

450

# If you specify a [Compute Engine (N1) machine

451

# type](/ml-engine/docs/machine-types-online-prediction) in the

452

# `machineType` field, you must specify `TENSORFLOW`

453

# for the framework.

454

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

455

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

456

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

457

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

458

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

459

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

460

# ensure that their change will be applied to the model as intended.

461

},

462

"onlinePredictionConsoleLogging": True or False, # Optional. If true, online prediction nodes send `stderr` and `stdout`

463

# streams to Stackdriver Logging. These can be more verbose than the standard

464

# access logs (see `onlinePredictionLogging`) and can incur higher cost.

465

# However, they are helpful for debugging. Note that

466

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

467

# your project receives prediction requests at a high QPS. Estimate your

468

# costs before enabling this option.

469

#

470

# Default is false.

471

"regions": [ # Optional. The list of regions where the model is going to be deployed.

472

# Only one region per model is supported.

473

# Defaults to 'us-central1' if nothing is set.

474

# See the <a href="/ml-engine/docs/tensorflow/regions">available regions</a>

475

# for AI Platform services.

476

# Note:

477

# * No matter where a model is deployed, it can always be accessed by

478

# users from anywhere, both for online and batch prediction.

479

# * The region for a batch prediction job is set by the region field when

480

# submitting the batch prediction job and does not take its value from

# this field.

"A String",

],

"description": "A String", # Optional. The description specified for the model when it was created.

485

"onlinePredictionLogging": True or False, # Optional. If true, online prediction access logs are sent to StackDriver

486

# Logging. These logs are like standard server access logs, containing

487

# information like timestamp and latency for each request. Note that

488

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

489

# your project receives prediction requests at a high queries per second rate

490

# (QPS). Estimate your costs before enabling this option.

491

#

492

# Default is false.

493

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

494

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

495

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

496

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

497

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

498

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

499

# ensure that their change will be applied to the model as intended.

500

"labels": { # Optional. One or more labels that you can add, to organize your models.

501

# Each label is a key-value pair, where both the key and the value are

502

# arbitrary strings that you supply.

503

# For more information, see the documentation on

504

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

505

"a_key": "A String",

506

},

507

"name": "A String", # Required. The name specified for the model when it was created.

508

#

509

# The model name must be unique within the project it is created in.

510

}

511

512

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

519

520

{ # Represents a machine learning solution.

521

#

522

# A model can have multiple versions, each of which is a deployed, trained

523

# model ready to receive prediction requests. The model itself is just a

524

# container.

Bu Sun Kim

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

[diff] [blame]

525

"defaultVersion": { # Represents a version of the model. # Output only. The default version of the model. This version will be used to

Sai Cheemalapati

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

[diff] [blame]

526

# handle prediction requests that do not specify a version.

Bu Sun Kim

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

[diff] [blame^]

527

#

Sai Cheemalapati

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

[diff] [blame]

528

# You can change the default version by calling

Dan O'Meara

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

[diff] [blame]

529

# projects.models.versions.setDefault.

Sai Cheemalapati

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

[diff] [blame]

530

#

531

# Each version is a trained model deployed in the cloud, ready to handle

532

# prediction requests. A model can have multiple versions. You can get

533

# information about all of the versions of a given model by calling

Dan O'Meara

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

[diff] [blame]

534

# projects.models.versions.list.

Bu Sun Kim

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

[diff] [blame^]

535

"acceleratorConfig": { # Represents a hardware accelerator request config. # Optional. Accelerator config for using GPUs for online prediction (beta).

536

# Only specify this field if you have specified a Compute Engine (N1) machine

537

# type in the `machineType` field. Learn more about [using GPUs for online

538

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

539

# Note that the AcceleratorConfig can be used in both Jobs and Versions.

540

# Learn more about [accelerators for training](/ml-engine/docs/using-gpus) and

541

# [accelerators for online

542

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

543

"count": "A String", # The number of accelerators to attach to each machine running the job.

544

"type": "A String", # The type of accelerator to use.

545

},

546

"isDefault": True or False, # Output only. If true, this version will be used to handle prediction

547

# requests that do not specify a version.

548

#

549

# You can change the default version by calling

550

# projects.methods.versions.setDefault.

Bu Sun Kim

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

[diff] [blame]

551

"manualScaling": { # Options for manually scaling a model. # Manually select the number of nodes to use for serving the

552

# model. You should generally use `auto_scaling` with an appropriate

553

# `min_nodes` instead, but this option is available if you want more

554

# predictable billing. Beware that latency and error rates will increase

555

# if the traffic exceeds that capability of the system to serve it based

556

# on the selected number of nodes.

557

"nodes": 42, # The number of nodes to allocate for this model. These nodes are always up,

558

# starting from the time the model is deployed, so the cost of operating

559

# this model will be proportional to `nodes` * number of hours since

560

# last billing cycle plus the cost for each prediction performed.

Dan O'Meara

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

[diff] [blame]

561

},

Bu Sun Kim

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

[diff] [blame^]

562

"state": "A String", # Output only. The state of a version.

Bu Sun Kim

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

[diff] [blame]

563

"name": "A String", # Required. The name specified for the version when it was created.

564

#

565

# The version name must be unique within the model it is created in.

566

"serviceAccount": "A String", # Optional. Specifies the service account for resource access control.

567

"pythonVersion": "A String", # Required. The version of Python used in prediction.

568

#

569

# The following Python versions are available:

570

#

571

# * Python '3.7' is available when `runtime_version` is set to '1.15' or

572

# later.

573

# * Python '3.5' is available when `runtime_version` is set to a version

574

# from '1.4' to '1.14'.

575

# * Python '2.7' is available when `runtime_version` is set to '1.15' or

576

# earlier.

577

#

578

# Read more about the Python versions available for [each runtime

579

# version](/ml-engine/docs/runtime-version-list).

580

"lastUseTime": "A String", # Output only. The time the version was last used for prediction.

581

"predictionClass": "A String", # Optional. The fully qualified name

Dan O'Meara

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

[diff] [blame]

582

# (<var>module_name</var>.<var>class_name</var>) of a class that implements

Bu Sun Kim

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

[diff] [blame]

583

# the Predictor interface described in this reference field. The module

584

# containing this class should be included in a package provided to the

585

# [`packageUris` field](#Version.FIELDS.package_uris).

Sai Cheemalapati

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

[diff] [blame]

586

#

Bu Sun Kim

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

[diff] [blame]

587

# Specify this field if and only if you are deploying a [custom prediction

588

# routine (beta)](/ml-engine/docs/tensorflow/custom-prediction-routines).

589

# If you specify this field, you must set

Dan O'Meara

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

[diff] [blame]

590

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater and

591

# you must set `machineType` to a [legacy (MLS1)

592

# machine type](/ml-engine/docs/machine-types-online-prediction).

Bu Sun Kim

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

[diff] [blame]

593

#

594

# The following code sample provides the Predictor interface:

595

#

Bu Sun Kim

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

[diff] [blame]

596

# <pre style="max-width: 626px;">

Bu Sun Kim

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

[diff] [blame]

597

# class Predictor(object):

Bu Sun Kim

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

[diff] [blame]

598

# """Interface for constructing custom predictors."""

Bu Sun Kim

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

[diff] [blame]

599

#

600

# def predict(self, instances, **kwargs):

Bu Sun Kim

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

[diff] [blame]

601

# """Performs custom prediction.

Bu Sun Kim

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

[diff] [blame]

602

#

603

# Instances are the decoded values from the request. They have already

604

# been deserialized from JSON.

605

#

606

# Args:

607

# instances: A list of prediction input instances.

608

# **kwargs: A dictionary of keyword args provided as additional

609

# fields on the predict request body.

610

#

611

# Returns:

612

# A list of outputs containing the prediction results. This list must

613

# be JSON serializable.

Bu Sun Kim

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

[diff] [blame]

614

# """

Bu Sun Kim

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

[diff] [blame]

615

# raise NotImplementedError()

616

#

617

# @classmethod

618

# def from_path(cls, model_dir):

Bu Sun Kim

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

[diff] [blame]

619

# """Creates an instance of Predictor using the given path.

Bu Sun Kim

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

[diff] [blame]

620

#

621

# Loading of the predictor should be done in this method.

622

#

623

# Args:

624

# model_dir: The local directory that contains the exported model

625

# file along with any additional files uploaded when creating the

# version resource.

#

# Returns:

# An instance implementing this Predictor class.

Bu Sun Kim

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

[diff] [blame]

630

# """

Bu Sun Kim

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

[diff] [blame]

631

# raise NotImplementedError()

Dan O'Meara

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

[diff] [blame]

632

# </pre>

Bu Sun Kim

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

[diff] [blame]

633

#

634

# Learn more about [the Predictor interface and custom prediction

635

# routines](/ml-engine/docs/tensorflow/custom-prediction-routines).

Bu Sun Kim

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

[diff] [blame^]

636

"deploymentUri": "A String", # Required. The Cloud Storage location of the trained model used to

637

# create the version. See the

638

# [guide to model

639

# deployment](/ml-engine/docs/tensorflow/deploying-models) for more

640

# information.

641

#

642

# When passing Version to

643

# projects.models.versions.create

644

# the model service uses the specified location as the source of the model.

645

# Once deployed, the model version is hosted by the prediction service, so

646

# this location is useful only as a historical record.

647

# The total number of model files can't exceed 1000.

Bu Sun Kim

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

[diff] [blame]

648

"packageUris": [ # Optional. Cloud Storage paths (`gs://…`) of packages for [custom

Bu Sun Kim

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

[diff] [blame]

649

# prediction routines](/ml-engine/docs/tensorflow/custom-prediction-routines)

650

# or [scikit-learn pipelines with custom

651

# code](/ml-engine/docs/scikit/exporting-for-prediction#custom-pipeline-code).

652

#

653

# For a custom prediction routine, one of these packages must contain your

654

# Predictor class (see

655

# [`predictionClass`](#Version.FIELDS.prediction_class)). Additionally,

656

# include any dependencies used by your Predictor or scikit-learn pipeline

657

# uses that are not already included in your selected [runtime

658

# version](/ml-engine/docs/tensorflow/runtime-version-list).

659

#

660

# If you specify this field, you must also set

661

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater.

Bu Sun Kim

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

[diff] [blame]

662

"A String",

Bu Sun Kim

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

[diff] [blame]

663

],

Bu Sun Kim

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

[diff] [blame]

664

"explanationConfig": { # Message holding configuration options for explaining model predictions. # Optional. Configures explainability features on the model's version.

665

# Some explanation features require additional metadata to be loaded

666

# as part of the model payload.

667

# There are two feature attribution methods supported for TensorFlow models:

668

# integrated gradients and sampled Shapley.

669

# [Learn more about feature

670

# attributions.](/ai-platform/prediction/docs/ai-explanations/overview)

671

"integratedGradientsAttribution": { # Attributes credit by computing the Aumann-Shapley value taking advantage # Attributes credit by computing the Aumann-Shapley value taking advantage

672

# of the model's fully differentiable structure. Refer to this paper for

673

# more details: http://proceedings.mlr.press/v70/sundararajan17a.html

674

# of the model's fully differentiable structure. Refer to this paper for

675

# more details: https://arxiv.org/abs/1703.01365

676

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

677

# A good value to start is 50 and gradually increase until the

678

# sum to diff property is met within the desired error range.

679

},

680

"sampledShapleyAttribution": { # An attribution method that approximates Shapley values for features that # An attribution method that approximates Shapley values for features that

681

# contribute to the label being predicted. A sampling strategy is used to

682

# approximate the value rather than considering all subsets of features.

683

# contribute to the label being predicted. A sampling strategy is used to

684

# approximate the value rather than considering all subsets of features.

685

"numPaths": 42, # The number of feature permutations to consider when approximating the

686

# Shapley values.

687

},

688

"xraiAttribution": { # Attributes credit by computing the XRAI taking advantage # Attributes credit by computing the XRAI taking advantage

689

# of the model's fully differentiable structure. Refer to this paper for

690

# more details: https://arxiv.org/abs/1906.02825

691

# Currently only implemented for models with natural image inputs.

692

# of the model's fully differentiable structure. Refer to this paper for

693

# more details: https://arxiv.org/abs/1906.02825

694

# Currently only implemented for models with natural image inputs.

695

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

696

# A good value to start is 50 and gradually increase until the

697

# sum to diff property is met within the desired error range.

698

},

699

},

Bu Sun Kim

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

[diff] [blame]

700

"autoScaling": { # Options for automatically scaling a model. # Automatically scale the number of nodes used to serve the model in

Dan O'Meara

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

[diff] [blame]

701

# response to increases and decreases in traffic. Care should be

Bu Sun Kim

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

[diff] [blame]

702

# taken to ramp up traffic according to the model's ability to scale

Dan O'Meara

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

[diff] [blame]

703

# or you will start seeing increases in latency and 429 response codes.

704

#

705

# Note that you cannot use AutoScaling if your version uses

706

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use specify

707

# `manual_scaling`.

Bu Sun Kim

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

[diff] [blame]

708

"minNodes": 42, # Optional. The minimum number of nodes to allocate for this model. These

Dan O'Meara

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

[diff] [blame]

709

# nodes are always up, starting from the time the model is deployed.

710

# Therefore, the cost of operating this model will be at least

711

# `rate` * `min_nodes` * number of hours since last billing cycle,

712

# where `rate` is the cost per node-hour as documented in the

713

# [pricing guide](/ml-engine/docs/pricing),

714

# even if no predictions are performed. There is additional cost for each

715

# prediction performed.

716

#

717

# Unlike manual scaling, if the load gets too heavy for the nodes

718

# that are up, the service will automatically add nodes to handle the

719

# increased load as well as scale back as traffic drops, always maintaining

720

# at least `min_nodes`. You will be charged for the time in which additional

721

# nodes are used.

722

#

723

# If `min_nodes` is not specified and AutoScaling is used with a [legacy

724

# (MLS1) machine type](/ml-engine/docs/machine-types-online-prediction),

725

# `min_nodes` defaults to 0, in which case, when traffic to a model stops

726

# (and after a cool-down period), nodes will be shut down and no charges will

727

# be incurred until traffic to the model resumes.

728

#

729

# If `min_nodes` is not specified and AutoScaling is used with a [Compute

730

# Engine (N1) machine type](/ml-engine/docs/machine-types-online-prediction),

731

# `min_nodes` defaults to 1. `min_nodes` must be at least 1 for use with a

732

# Compute Engine machine type.

733

#

734

# Note that you cannot use AutoScaling if your version uses

735

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use

736

# ManualScaling.

737

#

738

# You can set `min_nodes` when creating the model version, and you can also

739

# update `min_nodes` for an existing version:

740

# <pre>

741

# update_body.json:

742

# {

Bu Sun Kim

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

[diff] [blame]

743

# 'autoScaling': {

744

# 'minNodes': 5

Dan O'Meara

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

[diff] [blame]

# }

# }

# </pre>

# HTTP request:

Bu Sun Kim

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

[diff] [blame]

749

# <pre style="max-width: 626px;">

Dan O'Meara

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

[diff] [blame]

750

# PATCH

751

# https://ml.googleapis.com/v1/{name=projects/*/models/*/versions/*}?update_mask=autoScaling.minNodes

752

# -d @./update_body.json

753

# </pre>

754

},

Bu Sun Kim

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

[diff] [blame^]

755

"createTime": "A String", # Output only. The time the version was created.

Bu Sun Kim

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

[diff] [blame]

756

"labels": { # Optional. One or more labels that you can add, to organize your model

757

# versions. Each label is a key-value pair, where both the key and the value

758

# are arbitrary strings that you supply.

759

# For more information, see the documentation on

760

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

761

"a_key": "A String",

762

},

Bu Sun Kim

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

[diff] [blame]

763

"requestLoggingConfig": { # Configuration for logging request-response pairs to a BigQuery table. # Optional. *Only* specify this field in a

Dan O'Meara

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

[diff] [blame]

764

# projects.models.versions.patch

765

# request. Specifying it in a

766

# projects.models.versions.create

767

# request has no effect.

768

#

769

# Configures the request-response pair logging on predictions from this

770

# Version.

771

# Online prediction requests to a model version and the responses to these

772

# requests are converted to raw strings and saved to the specified BigQuery

773

# table. Logging is constrained by [BigQuery quotas and

774

# limits](/bigquery/quotas). If your project exceeds BigQuery quotas or limits,

775

# AI Platform Prediction does not log request-response pairs, but it continues

776

# to serve predictions.

777

#

778

# If you are using [continuous

779

# evaluation](/ml-engine/docs/continuous-evaluation/), you do not need to

780

# specify this configuration manually. Setting up continuous evaluation

781

# automatically enables logging of request-response pairs.

Bu Sun Kim

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

[diff] [blame]

782

"bigqueryTableName": "A String", # Required. Fully qualified BigQuery table name in the following format:

783

# "<var>project_id</var>.<var>dataset_name</var>.<var>table_name</var>"

Dan O'Meara

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

[diff] [blame]

784

#

Bu Sun Kim

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

[diff] [blame]

785

# The specified table must already exist, and the "Cloud ML Service Agent"

Dan O'Meara

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

[diff] [blame]

786

# for your project must have permission to write to it. The table must have

787

# the following [schema](/bigquery/docs/schemas):

788

#

789

# <table>

Bu Sun Kim

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

[diff] [blame]

790

# <tr><th>Field name</th><th style="display: table-cell">Type</th>

791

# <th style="display: table-cell">Mode</th></tr>

Dan O'Meara

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

[diff] [blame]

792

# <tr><td>model</td><td>STRING</td><td>REQUIRED</td></tr>

793

# <tr><td>model_version</td><td>STRING</td><td>REQUIRED</td></tr>

794

# <tr><td>time</td><td>TIMESTAMP</td><td>REQUIRED</td></tr>

795

# <tr><td>raw_data</td><td>STRING</td><td>REQUIRED</td></tr>

796

# <tr><td>raw_prediction</td><td>STRING</td><td>NULLABLE</td></tr>

797

# <tr><td>groundtruth</td><td>STRING</td><td>NULLABLE</td></tr>

798

# </table>

Bu Sun Kim

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

[diff] [blame]

799

"samplingPercentage": 3.14, # Percentage of requests to be logged, expressed as a fraction from 0 to 1.

800

# For example, if you want to log 10% of requests, enter `0.1`. The sampling

801

# window is the lifetime of the model version. Defaults to 0.

802

},

803

"errorMessage": "A String", # Output only. The details of a failure or a cancellation.

804

"machineType": "A String", # Optional. The type of machine on which to serve the model. Currently only

805

# applies to online prediction service. If this field is not specified, it

806

# defaults to `mls1-c1-m2`.

807

#

808

# Online prediction supports the following machine types:

#

# * `mls1-c1-m2`

# * `mls1-c4-m2`

# * `n1-standard-2`

# * `n1-standard-4`

# * `n1-standard-8`

# * `n1-standard-16`

# * `n1-standard-32`

# * `n1-highmem-2`

# * `n1-highmem-4`

# * `n1-highmem-8`

# * `n1-highmem-16`

# * `n1-highmem-32`

# * `n1-highcpu-2`

# * `n1-highcpu-4`

# * `n1-highcpu-8`

# * `n1-highcpu-16`

# * `n1-highcpu-32`

#

# `mls1-c1-m2` is generally available. All other machine types are available

829

# in beta. Learn more about the [differences between machine

830

# types](/ml-engine/docs/machine-types-online-prediction).

831

"runtimeVersion": "A String", # Required. The AI Platform runtime version to use for this deployment.

832

#

833

# For more information, see the

834

# [runtime version list](/ml-engine/docs/runtime-version-list) and

835

# [how to manage runtime versions](/ml-engine/docs/versioning).

836

"description": "A String", # Optional. The description specified for the version when it was created.

837

"framework": "A String", # Optional. The machine learning framework AI Platform uses to train

838

# this version of the model. Valid values are `TENSORFLOW`, `SCIKIT_LEARN`,

839

# `XGBOOST`. If you do not specify a framework, AI Platform

840

# will analyze files in the deployment_uri to determine a framework. If you

841

# choose `SCIKIT_LEARN` or `XGBOOST`, you must also set the runtime version

842

# of the model to 1.4 or greater.

843

#

844

# Do **not** specify a framework if you're deploying a [custom

845

# prediction routine](/ml-engine/docs/tensorflow/custom-prediction-routines).

846

#

847

# If you specify a [Compute Engine (N1) machine

848

# type](/ml-engine/docs/machine-types-online-prediction) in the

849

# `machineType` field, you must specify `TENSORFLOW`

850

# for the framework.

851

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

852

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

853

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

854

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

855

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

856

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

857

# ensure that their change will be applied to the model as intended.

Sai Cheemalapati

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

[diff] [blame]

858

},

Bu Sun Kim

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

[diff] [blame]

859

"onlinePredictionConsoleLogging": True or False, # Optional. If true, online prediction nodes send `stderr` and `stdout`

860

# streams to Stackdriver Logging. These can be more verbose than the standard

861

# access logs (see `onlinePredictionLogging`) and can incur higher cost.

862

# However, they are helpful for debugging. Note that

863

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

864

# your project receives prediction requests at a high QPS. Estimate your

865

# costs before enabling this option.

Bu Sun Kim

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

[diff] [blame^]

866

#

Bu Sun Kim

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

[diff] [blame]

867

# Default is false.

868

"regions": [ # Optional. The list of regions where the model is going to be deployed.

869

# Only one region per model is supported.

870

# Defaults to 'us-central1' if nothing is set.

871

# See the <a href="/ml-engine/docs/tensorflow/regions">available regions</a>

872

# for AI Platform services.

873

# Note:

874

# * No matter where a model is deployed, it can always be accessed by

875

# users from anywhere, both for online and batch prediction.

876

# * The region for a batch prediction job is set by the region field when

877

# submitting the batch prediction job and does not take its value from

# this field.

"A String",

],

"description": "A String", # Optional. The description specified for the model when it was created.

882

"onlinePredictionLogging": True or False, # Optional. If true, online prediction access logs are sent to StackDriver

Bu Sun Kim

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

[diff] [blame]

883

# Logging. These logs are like standard server access logs, containing

884

# information like timestamp and latency for each request. Note that

885

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

886

# your project receives prediction requests at a high queries per second rate

887

# (QPS). Estimate your costs before enabling this option.

Bu Sun Kim

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

[diff] [blame^]

888

#

Bu Sun Kim

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

[diff] [blame]

889

# Default is false.

Bu Sun Kim

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

[diff] [blame]

890

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

891

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

892

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

893

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

894

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

895

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

896

# ensure that their change will be applied to the model as intended.

Bu Sun Kim

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

[diff] [blame^]

897

"labels": { # Optional. One or more labels that you can add, to organize your models.

898

# Each label is a key-value pair, where both the key and the value are

899

# arbitrary strings that you supply.

900

# For more information, see the documentation on

901

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

902

"a_key": "A String",

903

},

904

"name": "A String", # Required. The name specified for the model when it was created.

Bu Sun Kim

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

[diff] [blame]

905

#

Bu Sun Kim

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

[diff] [blame^]

906

# The model name must be unique within the project it is created in.

907

}</pre>

Sai Cheemalapati

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

[diff] [blame]

</div>

Thomas Coffee

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

[diff] [blame]

911

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

Sai Cheemalapati

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

[diff] [blame]

912

<pre>Deletes a model.

913

914

You can only delete a model if there are no versions in it. You can delete

915

versions by calling

Dan O'Meara

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

[diff] [blame]

916

projects.models.versions.delete.

Sai Cheemalapati

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

[diff] [blame]

917

918

Args:

Bu Sun Kim

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

[diff] [blame]

919

Sai Cheemalapati

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

[diff] [blame]

920

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

927

928

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

929

# network API call.

Bu Sun Kim

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

[diff] [blame]

930

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

Sai Cheemalapati

4ba8c23

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

[diff] [blame]

931

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

Bu Sun Kim

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

[diff] [blame]

932

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

Bu Sun Kim

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

[diff] [blame]

933

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

934

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

935

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

936

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

937

#

938

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

939

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

Bu Sun Kim

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

[diff] [blame^]

940

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

941

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

942

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

943

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

Bu Sun Kim

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

[diff] [blame]

944

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

945

# message types for APIs to use.

946

{

947

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

948

},

949

],

Bu Sun Kim

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

[diff] [blame]

950

},

951

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

952

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

953

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

954

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

955

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

956

},

957

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

958

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

959

# available.

Bu Sun Kim

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

[diff] [blame^]

960

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

961

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

962

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

963

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

964

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

965

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

966

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

967

# `TakeSnapshotResponse`.

968

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

969

},

Sai Cheemalapati

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

[diff] [blame]

}</pre>

</div>

Thomas Coffee

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

[diff] [blame]

974

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

Sai Cheemalapati

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

[diff] [blame]

975

<pre>Gets information about a model, including its name, the description (if

976

set), and the default version (if at least one version of the model has

977

been deployed).

978

979

Args:

Bu Sun Kim

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

[diff] [blame]

980

Sai Cheemalapati

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

[diff] [blame]

981

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

988

989

{ # Represents a machine learning solution.

Bu Sun Kim

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

[diff] [blame^]

990

#

991

# A model can have multiple versions, each of which is a deployed, trained

992

# model ready to receive prediction requests. The model itself is just a

993

# container.

994

"defaultVersion": { # Represents a version of the model. # Output only. The default version of the model. This version will be used to

995

# handle prediction requests that do not specify a version.

Dan O'Meara

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

[diff] [blame]

996

#

Bu Sun Kim

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

[diff] [blame^]

997

# You can change the default version by calling

998

# projects.models.versions.setDefault.

999

#

1000

# Each version is a trained model deployed in the cloud, ready to handle

1001

# prediction requests. A model can have multiple versions. You can get

1002

# information about all of the versions of a given model by calling

1003

# projects.models.versions.list.

1004

"acceleratorConfig": { # Represents a hardware accelerator request config. # Optional. Accelerator config for using GPUs for online prediction (beta).

1005

# Only specify this field if you have specified a Compute Engine (N1) machine

1006

# type in the `machineType` field. Learn more about [using GPUs for online

1007

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

1008

# Note that the AcceleratorConfig can be used in both Jobs and Versions.

1009

# Learn more about [accelerators for training](/ml-engine/docs/using-gpus) and

1010

# [accelerators for online

1011

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

1012

"count": "A String", # The number of accelerators to attach to each machine running the job.

1013

"type": "A String", # The type of accelerator to use.

1014

},

1015

"isDefault": True or False, # Output only. If true, this version will be used to handle prediction

1016

# requests that do not specify a version.

1017

#

1018

# You can change the default version by calling

1019

# projects.methods.versions.setDefault.

1020

"manualScaling": { # Options for manually scaling a model. # Manually select the number of nodes to use for serving the

1021

# model. You should generally use `auto_scaling` with an appropriate

1022

# `min_nodes` instead, but this option is available if you want more

1023

# predictable billing. Beware that latency and error rates will increase

1024

# if the traffic exceeds that capability of the system to serve it based

1025

# on the selected number of nodes.

1026

"nodes": 42, # The number of nodes to allocate for this model. These nodes are always up,

1027

# starting from the time the model is deployed, so the cost of operating

1028

# this model will be proportional to `nodes` * number of hours since

1029

# last billing cycle plus the cost for each prediction performed.

1030

},

1031

"state": "A String", # Output only. The state of a version.

1032

"name": "A String", # Required. The name specified for the version when it was created.

1033

#

1034

# The version name must be unique within the model it is created in.

1035

"serviceAccount": "A String", # Optional. Specifies the service account for resource access control.

1036

"pythonVersion": "A String", # Required. The version of Python used in prediction.

1037

#

1038

# The following Python versions are available:

1039

#

1040

# * Python '3.7' is available when `runtime_version` is set to '1.15' or

1041

# later.

1042

# * Python '3.5' is available when `runtime_version` is set to a version

1043

# from '1.4' to '1.14'.

1044

# * Python '2.7' is available when `runtime_version` is set to '1.15' or

1045

# earlier.

1046

#

1047

# Read more about the Python versions available for [each runtime

1048

# version](/ml-engine/docs/runtime-version-list).

1049

"lastUseTime": "A String", # Output only. The time the version was last used for prediction.

1050

"predictionClass": "A String", # Optional. The fully qualified name

1051

# (<var>module_name</var>.<var>class_name</var>) of a class that implements

1052

# the Predictor interface described in this reference field. The module

1053

# containing this class should be included in a package provided to the

1054

# [`packageUris` field](#Version.FIELDS.package_uris).

1055

#

1056

# Specify this field if and only if you are deploying a [custom prediction

1057

# routine (beta)](/ml-engine/docs/tensorflow/custom-prediction-routines).

1058

# If you specify this field, you must set

1059

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater and

1060

# you must set `machineType` to a [legacy (MLS1)

1061

# machine type](/ml-engine/docs/machine-types-online-prediction).

1062

#

1063

# The following code sample provides the Predictor interface:

1064

#

1065

# <pre style="max-width: 626px;">

1066

# class Predictor(object):

1067

# """Interface for constructing custom predictors."""

1068

#

1069

# def predict(self, instances, **kwargs):

1070

# """Performs custom prediction.

1071

#

1072

# Instances are the decoded values from the request. They have already

1073

# been deserialized from JSON.

1074

#

1075

# Args:

1076

# instances: A list of prediction input instances.

1077

# **kwargs: A dictionary of keyword args provided as additional

1078

# fields on the predict request body.

1079

#

1080

# Returns:

1081

# A list of outputs containing the prediction results. This list must

1082

# be JSON serializable.

1083

# """

1084

# raise NotImplementedError()

1085

#

1086

# @classmethod

1087

# def from_path(cls, model_dir):

1088

# """Creates an instance of Predictor using the given path.

1089

#

1090

# Loading of the predictor should be done in this method.

1091

#

1092

# Args:

1093

# model_dir: The local directory that contains the exported model

1094

# file along with any additional files uploaded when creating the

# version resource.

#

# Returns:

# An instance implementing this Predictor class.

1099

# """

1100

# raise NotImplementedError()

1101

# </pre>

1102

#

1103

# Learn more about [the Predictor interface and custom prediction

1104

# routines](/ml-engine/docs/tensorflow/custom-prediction-routines).

1105

"deploymentUri": "A String", # Required. The Cloud Storage location of the trained model used to

1106

# create the version. See the

1107

# [guide to model

1108

# deployment](/ml-engine/docs/tensorflow/deploying-models) for more

1109

# information.

1110

#

1111

# When passing Version to

1112

# projects.models.versions.create

1113

# the model service uses the specified location as the source of the model.

1114

# Once deployed, the model version is hosted by the prediction service, so

1115

# this location is useful only as a historical record.

1116

# The total number of model files can't exceed 1000.

1117

"packageUris": [ # Optional. Cloud Storage paths (`gs://…`) of packages for [custom

1118

# prediction routines](/ml-engine/docs/tensorflow/custom-prediction-routines)

1119

# or [scikit-learn pipelines with custom

1120

# code](/ml-engine/docs/scikit/exporting-for-prediction#custom-pipeline-code).

1121

#

1122

# For a custom prediction routine, one of these packages must contain your

1123

# Predictor class (see

1124

# [`predictionClass`](#Version.FIELDS.prediction_class)). Additionally,

1125

# include any dependencies used by your Predictor or scikit-learn pipeline

1126

# uses that are not already included in your selected [runtime

1127

# version](/ml-engine/docs/tensorflow/runtime-version-list).

1128

#

1129

# If you specify this field, you must also set

1130

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater.

1131

"A String",

1132

],

1133

"explanationConfig": { # Message holding configuration options for explaining model predictions. # Optional. Configures explainability features on the model's version.

1134

# Some explanation features require additional metadata to be loaded

1135

# as part of the model payload.

1136

# There are two feature attribution methods supported for TensorFlow models:

1137

# integrated gradients and sampled Shapley.

1138

# [Learn more about feature

1139

# attributions.](/ai-platform/prediction/docs/ai-explanations/overview)

1140

"integratedGradientsAttribution": { # Attributes credit by computing the Aumann-Shapley value taking advantage # Attributes credit by computing the Aumann-Shapley value taking advantage

1141

# of the model's fully differentiable structure. Refer to this paper for

1142

# more details: http://proceedings.mlr.press/v70/sundararajan17a.html

1143

# of the model's fully differentiable structure. Refer to this paper for

1144

# more details: https://arxiv.org/abs/1703.01365

1145

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

1146

# A good value to start is 50 and gradually increase until the

1147

# sum to diff property is met within the desired error range.

1148

},

1149

"sampledShapleyAttribution": { # An attribution method that approximates Shapley values for features that # An attribution method that approximates Shapley values for features that

1150

# contribute to the label being predicted. A sampling strategy is used to

1151

# approximate the value rather than considering all subsets of features.

1152

# contribute to the label being predicted. A sampling strategy is used to

1153

# approximate the value rather than considering all subsets of features.

1154

"numPaths": 42, # The number of feature permutations to consider when approximating the

1155

# Shapley values.

1156

},

1157

"xraiAttribution": { # Attributes credit by computing the XRAI taking advantage # Attributes credit by computing the XRAI taking advantage

1158

# of the model's fully differentiable structure. Refer to this paper for

1159

# more details: https://arxiv.org/abs/1906.02825

1160

# Currently only implemented for models with natural image inputs.

1161

# of the model's fully differentiable structure. Refer to this paper for

1162

# more details: https://arxiv.org/abs/1906.02825

1163

# Currently only implemented for models with natural image inputs.

1164

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

1165

# A good value to start is 50 and gradually increase until the

1166

# sum to diff property is met within the desired error range.

1167

},

1168

},

1169

"autoScaling": { # Options for automatically scaling a model. # Automatically scale the number of nodes used to serve the model in

1170

# response to increases and decreases in traffic. Care should be

1171

# taken to ramp up traffic according to the model's ability to scale

1172

# or you will start seeing increases in latency and 429 response codes.

1173

#

1174

# Note that you cannot use AutoScaling if your version uses

1175

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use specify

1176

# `manual_scaling`.

1177

"minNodes": 42, # Optional. The minimum number of nodes to allocate for this model. These

1178

# nodes are always up, starting from the time the model is deployed.

1179

# Therefore, the cost of operating this model will be at least

1180

# `rate` * `min_nodes` * number of hours since last billing cycle,

1181

# where `rate` is the cost per node-hour as documented in the

1182

# [pricing guide](/ml-engine/docs/pricing),

1183

# even if no predictions are performed. There is additional cost for each

1184

# prediction performed.

1185

#

1186

# Unlike manual scaling, if the load gets too heavy for the nodes

1187

# that are up, the service will automatically add nodes to handle the

1188

# increased load as well as scale back as traffic drops, always maintaining

1189

# at least `min_nodes`. You will be charged for the time in which additional

1190

# nodes are used.

1191

#

1192

# If `min_nodes` is not specified and AutoScaling is used with a [legacy

1193

# (MLS1) machine type](/ml-engine/docs/machine-types-online-prediction),

1194

# `min_nodes` defaults to 0, in which case, when traffic to a model stops

1195

# (and after a cool-down period), nodes will be shut down and no charges will

1196

# be incurred until traffic to the model resumes.

1197

#

1198

# If `min_nodes` is not specified and AutoScaling is used with a [Compute

1199

# Engine (N1) machine type](/ml-engine/docs/machine-types-online-prediction),

1200

# `min_nodes` defaults to 1. `min_nodes` must be at least 1 for use with a

1201

# Compute Engine machine type.

1202

#

1203

# Note that you cannot use AutoScaling if your version uses

1204

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use

1205

# ManualScaling.

1206

#

1207

# You can set `min_nodes` when creating the model version, and you can also

1208

# update `min_nodes` for an existing version:

# <pre>

# update_body.json:

# {

# 'autoScaling': {

# 'minNodes': 5

# }

# }

# </pre>

# HTTP request:

# <pre style="max-width: 626px;">

1219

# PATCH

1220

# https://ml.googleapis.com/v1/{name=projects/*/models/*/versions/*}?update_mask=autoScaling.minNodes

1221

# -d @./update_body.json

1222

# </pre>

1223

},

1224

"createTime": "A String", # Output only. The time the version was created.

1225

"labels": { # Optional. One or more labels that you can add, to organize your model

1226

# versions. Each label is a key-value pair, where both the key and the value

1227

# are arbitrary strings that you supply.

Bu Sun Kim

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

[diff] [blame]

1228

# For more information, see the documentation on

Bu Sun Kim

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

[diff] [blame]

1229

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

1230

"a_key": "A String",

Bu Sun Kim

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

[diff] [blame]

1231

},

Bu Sun Kim

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

[diff] [blame^]

1232

"requestLoggingConfig": { # Configuration for logging request-response pairs to a BigQuery table. # Optional. *Only* specify this field in a

1233

# projects.models.versions.patch

1234

# request. Specifying it in a

1235

# projects.models.versions.create

1236

# request has no effect.

Bu Sun Kim

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

[diff] [blame]

1237

#

Bu Sun Kim

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

[diff] [blame^]

1238

# Configures the request-response pair logging on predictions from this

1239

# Version.

1240

# Online prediction requests to a model version and the responses to these

1241

# requests are converted to raw strings and saved to the specified BigQuery

1242

# table. Logging is constrained by [BigQuery quotas and

1243

# limits](/bigquery/quotas). If your project exceeds BigQuery quotas or limits,

1244

# AI Platform Prediction does not log request-response pairs, but it continues

1245

# to serve predictions.

Bu Sun Kim

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

[diff] [blame]

1246

#

Bu Sun Kim

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

[diff] [blame^]

1247

# If you are using [continuous

1248

# evaluation](/ml-engine/docs/continuous-evaluation/), you do not need to

1249

# specify this configuration manually. Setting up continuous evaluation

1250

# automatically enables logging of request-response pairs.

1251

"bigqueryTableName": "A String", # Required. Fully qualified BigQuery table name in the following format:

1252

# "<var>project_id</var>.<var>dataset_name</var>.<var>table_name</var>"

Bu Sun Kim

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

[diff] [blame]

1253

#

Bu Sun Kim

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

[diff] [blame^]

1254

# The specified table must already exist, and the "Cloud ML Service Agent"

1255

# for your project must have permission to write to it. The table must have

1256

# the following [schema](/bigquery/docs/schemas):

Bu Sun Kim

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

[diff] [blame]

1257

#

Bu Sun Kim

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

[diff] [blame^]

1258

# <table>

1259

# <tr><th>Field name</th><th style="display: table-cell">Type</th>

1260

# <th style="display: table-cell">Mode</th></tr>

1261

# <tr><td>model</td><td>STRING</td><td>REQUIRED</td></tr>

1262

# <tr><td>model_version</td><td>STRING</td><td>REQUIRED</td></tr>

1263

# <tr><td>time</td><td>TIMESTAMP</td><td>REQUIRED</td></tr>

1264

# <tr><td>raw_data</td><td>STRING</td><td>REQUIRED</td></tr>

1265

# <tr><td>raw_prediction</td><td>STRING</td><td>NULLABLE</td></tr>

1266

# <tr><td>groundtruth</td><td>STRING</td><td>NULLABLE</td></tr>

1267

# </table>

1268

"samplingPercentage": 3.14, # Percentage of requests to be logged, expressed as a fraction from 0 to 1.

1269

# For example, if you want to log 10% of requests, enter `0.1`. The sampling

1270

# window is the lifetime of the model version. Defaults to 0.

Bu Sun Kim

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

[diff] [blame]

1271

},

Bu Sun Kim

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

[diff] [blame^]

1272

"errorMessage": "A String", # Output only. The details of a failure or a cancellation.

1273

"machineType": "A String", # Optional. The type of machine on which to serve the model. Currently only

1274

# applies to online prediction service. If this field is not specified, it

1275

# defaults to `mls1-c1-m2`.

Bu Sun Kim

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

[diff] [blame]

1276

#

Bu Sun Kim

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

[diff] [blame^]

1277

# Online prediction supports the following machine types:

Bu Sun Kim

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

[diff] [blame]

1278

#

Bu Sun Kim

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

[diff] [blame^]

# * `mls1-c1-m2`

# * `mls1-c4-m2`

# * `n1-standard-2`

# * `n1-standard-4`

# * `n1-standard-8`

# * `n1-standard-16`

# * `n1-standard-32`

# * `n1-highmem-2`

# * `n1-highmem-4`

# * `n1-highmem-8`

# * `n1-highmem-16`

# * `n1-highmem-32`

# * `n1-highcpu-2`

# * `n1-highcpu-4`

# * `n1-highcpu-8`

# * `n1-highcpu-16`

# * `n1-highcpu-32`

#

# `mls1-c1-m2` is generally available. All other machine types are available

1298

# in beta. Learn more about the [differences between machine

1299

# types](/ml-engine/docs/machine-types-online-prediction).

1300

"runtimeVersion": "A String", # Required. The AI Platform runtime version to use for this deployment.

1301

#

1302

# For more information, see the

1303

# [runtime version list](/ml-engine/docs/runtime-version-list) and

1304

# [how to manage runtime versions](/ml-engine/docs/versioning).

1305

"description": "A String", # Optional. The description specified for the version when it was created.

1306

"framework": "A String", # Optional. The machine learning framework AI Platform uses to train

1307

# this version of the model. Valid values are `TENSORFLOW`, `SCIKIT_LEARN`,

1308

# `XGBOOST`. If you do not specify a framework, AI Platform

1309

# will analyze files in the deployment_uri to determine a framework. If you

1310

# choose `SCIKIT_LEARN` or `XGBOOST`, you must also set the runtime version

1311

# of the model to 1.4 or greater.

1312

#

1313

# Do **not** specify a framework if you're deploying a [custom

1314

# prediction routine](/ml-engine/docs/tensorflow/custom-prediction-routines).

1315

#

1316

# If you specify a [Compute Engine (N1) machine

1317

# type](/ml-engine/docs/machine-types-online-prediction) in the

1318

# `machineType` field, you must specify `TENSORFLOW`

1319

# for the framework.

Bu Sun Kim

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

[diff] [blame]

1320

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

Bu Sun Kim

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

[diff] [blame]

1321

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

1322

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

1323

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

Bu Sun Kim

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

[diff] [blame^]

1324

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

1325

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

Bu Sun Kim

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

[diff] [blame]

1326

# ensure that their change will be applied to the model as intended.

Bu Sun Kim

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

[diff] [blame^]

1327

},

1328

"onlinePredictionConsoleLogging": True or False, # Optional. If true, online prediction nodes send `stderr` and `stdout`

1329

# streams to Stackdriver Logging. These can be more verbose than the standard

1330

# access logs (see `onlinePredictionLogging`) and can incur higher cost.

1331

# However, they are helpful for debugging. Note that

1332

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

1333

# your project receives prediction requests at a high QPS. Estimate your

1334

# costs before enabling this option.

1335

#

1336

# Default is false.

1337

"regions": [ # Optional. The list of regions where the model is going to be deployed.

1338

# Only one region per model is supported.

1339

# Defaults to 'us-central1' if nothing is set.

1340

# See the <a href="/ml-engine/docs/tensorflow/regions">available regions</a>

1341

# for AI Platform services.

1342

# Note:

1343

# * No matter where a model is deployed, it can always be accessed by

1344

# users from anywhere, both for online and batch prediction.

1345

# * The region for a batch prediction job is set by the region field when

1346

# submitting the batch prediction job and does not take its value from

# this field.

"A String",

],

"description": "A String", # Optional. The description specified for the model when it was created.

1351

"onlinePredictionLogging": True or False, # Optional. If true, online prediction access logs are sent to StackDriver

1352

# Logging. These logs are like standard server access logs, containing

1353

# information like timestamp and latency for each request. Note that

1354

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

1355

# your project receives prediction requests at a high queries per second rate

1356

# (QPS). Estimate your costs before enabling this option.

1357

#

1358

# Default is false.

1359

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

1360

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

1361

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

1362

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

1363

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

1364

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

1365

# ensure that their change will be applied to the model as intended.

1366

"labels": { # Optional. One or more labels that you can add, to organize your models.

1367

# Each label is a key-value pair, where both the key and the value are

1368

# arbitrary strings that you supply.

1369

# For more information, see the documentation on

1370

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

1371

"a_key": "A String",

1372

},

1373

"name": "A String", # Required. The name specified for the model when it was created.

1374

#

1375

# The model name must be unique within the project it is created in.

1376

}</pre>

Sai Cheemalapati

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

[diff] [blame]

</div>

Dan O'Meara

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

[diff] [blame]

1380

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

Bu Sun Kim

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

[diff] [blame]

1381

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

1382

Returns an empty policy if the resource exists and does not have a policy

set.

Args:

resource: string, REQUIRED: The resource for which the policy is being requested.

1387

See the operation documentation for the appropriate value for this field. (required)

Dan O'Meara

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

[diff] [blame]

1388

options_requestedPolicyVersion: integer, Optional. The policy format version to be returned.

1389

1390

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

1391

rejected.

1392

1393

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

1394

Policies without any conditional bindings may specify any valid value or

1395

leave the field unset.

Bu Sun Kim

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

[diff] [blame]

1396

1397

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

1398

[IAM

1399

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

Bu Sun Kim

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

[diff] [blame]

1400

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1407

Dan O'Meara

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

[diff] [blame]

1408

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

1409

# controls for Google Cloud resources.

Bu Sun Kim

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

[diff] [blame]

1410

#

1411

#

Dan O'Meara

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

[diff] [blame]

1412

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

1413

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

1414

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

1415

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

1416

# custom role.

Bu Sun Kim

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

[diff] [blame]

1417

#

Bu Sun Kim

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

[diff] [blame]

1418

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

1419

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

1420

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

1421

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

1422

# resources support conditions in their IAM policies, see the

1423

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

Dan O'Meara

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

[diff] [blame]

1424

#

1425

# **JSON example:**

Bu Sun Kim

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

[diff] [blame]

1426

#

1427

# {

Bu Sun Kim

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

[diff] [blame]

1428

# "bindings": [

Bu Sun Kim

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

[diff] [blame]

1429

# {

Bu Sun Kim

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

[diff] [blame]

1430

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

1431

# "members": [

1432

# "user:mike@example.com",

1433

# "group:admins@example.com",

1434

# "domain:google.com",

1435

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

Bu Sun Kim

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

[diff] [blame]

1436

# ]

1437

# },

1438

# {

Bu Sun Kim

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

[diff] [blame]

1439

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

1440

# "members": [

1441

# "user:eve@example.com"

1442

# ],

1443

# "condition": {

1444

# "title": "expirable access",

1445

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

1446

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

Dan O'Meara

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

[diff] [blame]

1447

# }

Bu Sun Kim

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

[diff] [blame]

1448

# }

Dan O'Meara

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

[diff] [blame]

1449

# ],

Bu Sun Kim

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

[diff] [blame]

1450

# "etag": "BwWWja0YfJA=",

1451

# "version": 3

Bu Sun Kim

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

[diff] [blame]

1452

# }

1453

#

Dan O'Meara

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

[diff] [blame]

1454

# **YAML example:**

Bu Sun Kim

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

[diff] [blame]

#

# bindings:

# - members:

# - user:mike@example.com

1459

# - group:admins@example.com

1460

# - domain:google.com

Dan O'Meara

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

[diff] [blame]

1461

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

1462

# role: roles/resourcemanager.organizationAdmin

Bu Sun Kim

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

[diff] [blame]

1463

# - members:

Dan O'Meara

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

[diff] [blame]

1464

# - user:eve@example.com

1465

# role: roles/resourcemanager.organizationViewer

1466

# condition:

1467

# title: expirable access

1468

# description: Does not grant access after Sep 2020

Bu Sun Kim

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

[diff] [blame]

1469

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

Dan O'Meara

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

[diff] [blame]

1470

# - etag: BwWWja0YfJA=

1471

# - version: 3

Bu Sun Kim

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

[diff] [blame]

1472

#

1473

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

Dan O'Meara

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

[diff] [blame]

1474

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

Bu Sun Kim

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

[diff] [blame]

1475

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

1476

#

1477

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

1478

# are rejected.

1479

#

1480

# Any operation that affects conditional role bindings must specify version

1481

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

1482

#

1483

# * Getting a policy that includes a conditional role binding

1484

# * Adding a conditional role binding to a policy

1485

# * Changing a conditional role binding in a policy

1486

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

1487

# that includes conditions

1488

#

1489

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

1490

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

1491

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

1492

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

1493

#

1494

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

1495

# specify any valid version or leave the field unset.

1496

#

1497

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

1498

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

1499

"auditConfigs": [ # Specifies cloud audit logging configuration for this policy.

1500

{ # Specifies the audit configuration for a service.

1501

# The configuration determines which permission types are logged, and what

1502

# identities, if any, are exempted from logging.

1503

# An AuditConfig must have one or more AuditLogConfigs.

1504

#

1505

# If there are AuditConfigs for both `allServices` and a specific service,

1506

# the union of the two AuditConfigs is used for that service: the log_types

1507

# specified in each AuditConfig are enabled, and the exempted_members in each

1508

# AuditLogConfig are exempted.

1509

#

1510

# Example Policy with multiple AuditConfigs:

#

# {

# "audit_configs": [

# {

# "service": "allServices"

1516

# "audit_log_configs": [

1517

# {

1518

# "log_type": "DATA_READ",

1519

# "exempted_members": [

1520

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

1525

# },

1526

# {

1527

# "log_type": "ADMIN_READ",

# }

# ]

# },

# {

# "service": "sampleservice.googleapis.com"

1533

# "audit_log_configs": [

1534

# {

1535

# "log_type": "DATA_READ",

1536

# },

1537

# {

1538

# "log_type": "DATA_WRITE",

1539

# "exempted_members": [

1540

# "user:aliya@example.com"

# ]

# }

# ]

# }

# ]

# }

#

# For sampleservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ

1549

# logging. It also exempts jose@example.com from DATA_READ logging, and

1550

# aliya@example.com from DATA_WRITE logging.

1551

"service": "A String", # Specifies a service that will be enabled for audit logging.

1552

# For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.

1553

# `allServices` is a special value that covers all services.

1554

"auditLogConfigs": [ # The configuration for logging of each type of permission.

1555

{ # Provides the configuration for logging a type of permissions.

# Example:

#

# {

# "audit_log_configs": [

1560

# {

1561

# "log_type": "DATA_READ",

1562

# "exempted_members": [

1563

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

# }

# ]

# }

#

# This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting

1573

# jose@example.com from DATA_READ logging.

1574

"exemptedMembers": [ # Specifies the identities that do not cause logging for this type of

1575

# permission.

1576

# Follows the same format of Binding.members.

1577

"A String",

1578

],

1579

"logType": "A String", # The log type that this config enables.

},

],

},

],

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

1585

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

1586

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

Bu Sun Kim

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

[diff] [blame]

1587

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

Bu Sun Kim

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

[diff] [blame]

1588

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

1589

#

1590

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

1591

# current request.

1592

#

1593

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

1594

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

1595

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

1596

#

1597

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

1598

# [IAM

1599

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

1600

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

1601

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

1602

#

1603

# Example (Comparison):

1604

#

1605

# title: "Summary size limit"

1606

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

1607

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

1608

#

1609

# Example (Equality):

1610

#

1611

# title: "Requestor is owner"

1612

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

1613

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

#

# Example (Logic):

#

# title: "Public documents"

1618

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

1619

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

1620

#

1621

# Example (Data Manipulation):

1622

#

1623

# title: "Notification string"

1624

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

1625

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

1626

#

1627

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

1628

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

1629

# documentation for additional information.

Bu Sun Kim

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

[diff] [blame^]

1630

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

1631

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

1632

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

1633

# syntax.

Bu Sun Kim

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

[diff] [blame]

1634

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

1635

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

1636

# expression.

1637

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

1638

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

Bu Sun Kim

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

[diff] [blame]

1639

},

1640

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

Bu Sun Kim

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

[diff] [blame]

1641

# `members` can have the following values:

1642

#

1643

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

1644

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

1645

#

1646

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

1647

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

1648

#

1649

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

Dan O'Meara

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

[diff] [blame]

1650

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

Bu Sun Kim

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

[diff] [blame]

1651

#

1652

#

1653

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

1654

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

1655

#

1656

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

1657

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

1658

#

Dan O'Meara

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

[diff] [blame]

1659

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

1660

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

1661

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

1662

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

1663

# retains the role in the binding.

1664

#

1665

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

1666

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

1667

# deleted. For example,

1668

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

1669

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

1670

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

1671

# role in the binding.

1672

#

1673

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

1674

# identifier) representing a Google group that has been recently

1675

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

1676

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

1677

# recovered group retains the role in the binding.

1678

#

Bu Sun Kim

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

[diff] [blame]

1679

#

1680

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

1681

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

1682

#

Bu Sun Kim

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

[diff] [blame]

1683

"A String",

Bu Sun Kim

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

[diff] [blame]

1684

],

Bu Sun Kim

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

[diff] [blame]

1685

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

1686

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

Bu Sun Kim

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

[diff] [blame]

1687

},

1688

],

Bu Sun Kim

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

[diff] [blame^]

1689

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

1690

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

1691

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

1692

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

1693

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

1694

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

1695

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

1696

#

1697

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

1698

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

1699

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

1700

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

Bu Sun Kim

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

[diff] [blame]

}</pre>

</div>

Bu Sun Kim

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

[diff] [blame]

1705

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

Sai Cheemalapati

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

[diff] [blame]

1706

<pre>Lists the models in a project.

1707

1708

Each project can contain multiple models, and each model can have multiple

1709

versions.

1710

Bu Sun Kim

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

[diff] [blame]

1711

If there are no models that match the request parameters, the list request

1712

returns an empty response body: {}.

Sai Cheemalapati

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

[diff] [blame]

1713

Bu Sun Kim

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

[diff] [blame]

1714

Args:

1715

parent: string, Required. The name of the project whose models are to be listed. (required)

Bu Sun Kim

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

[diff] [blame]

1716

filter: string, Optional. Specifies the subset of models to retrieve.

Sai Cheemalapati

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

[diff] [blame]

1717

pageToken: string, Optional. A page token to request the next page of results.

1718

1719

You get the token from the `next_page_token` field of the response from

1720

the previous call.

Bu Sun Kim

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

[diff] [blame]

1721

pageSize: integer, Optional. The number of models to retrieve per "page" of results. If there

1722

are more remaining results than this number, the response message will

1723

contain a valid value in the `next_page_token` field.

1724

1725

The default value is 20, and the maximum page size is 100.

Sai Cheemalapati

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

[diff] [blame]

1726

x__xgafv: string, V1 error format.

1727

Allowed values

1728

1 - v1 error format

1729

2 - v2 error format

Sai Cheemalapati

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

[diff] [blame]

1730

1731

Returns:

1732

An object of the form:

1733

1734

{ # Response message for the ListModels method.

Bu Sun Kim

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

[diff] [blame^]

1735

"nextPageToken": "A String", # Optional. Pass this token as the `page_token` field of the request for a

1736

# subsequent call.

Bu Sun Kim

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

[diff] [blame]

1737

"models": [ # The list of models.

Sai Cheemalapati

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

[diff] [blame]

1738

{ # Represents a machine learning solution.

Bu Sun Kim

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

[diff] [blame^]

1739

#

1740

# A model can have multiple versions, each of which is a deployed, trained

1741

# model ready to receive prediction requests. The model itself is just a

1742

# container.

1743

"defaultVersion": { # Represents a version of the model. # Output only. The default version of the model. This version will be used to

1744

# handle prediction requests that do not specify a version.

Dan O'Meara

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

[diff] [blame]

1745

#

Bu Sun Kim

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

[diff] [blame^]

1746

# You can change the default version by calling

1747

# projects.models.versions.setDefault.

1748

#

1749

# Each version is a trained model deployed in the cloud, ready to handle

1750

# prediction requests. A model can have multiple versions. You can get

1751

# information about all of the versions of a given model by calling

1752

# projects.models.versions.list.

1753

"acceleratorConfig": { # Represents a hardware accelerator request config. # Optional. Accelerator config for using GPUs for online prediction (beta).

1754

# Only specify this field if you have specified a Compute Engine (N1) machine

1755

# type in the `machineType` field. Learn more about [using GPUs for online

1756

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

1757

# Note that the AcceleratorConfig can be used in both Jobs and Versions.

1758

# Learn more about [accelerators for training](/ml-engine/docs/using-gpus) and

1759

# [accelerators for online

1760

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

1761

"count": "A String", # The number of accelerators to attach to each machine running the job.

1762

"type": "A String", # The type of accelerator to use.

1763

},

1764

"isDefault": True or False, # Output only. If true, this version will be used to handle prediction

1765

# requests that do not specify a version.

1766

#

1767

# You can change the default version by calling

1768

# projects.methods.versions.setDefault.

1769

"manualScaling": { # Options for manually scaling a model. # Manually select the number of nodes to use for serving the

1770

# model. You should generally use `auto_scaling` with an appropriate

1771

# `min_nodes` instead, but this option is available if you want more

1772

# predictable billing. Beware that latency and error rates will increase

1773

# if the traffic exceeds that capability of the system to serve it based

1774

# on the selected number of nodes.

1775

"nodes": 42, # The number of nodes to allocate for this model. These nodes are always up,

1776

# starting from the time the model is deployed, so the cost of operating

1777

# this model will be proportional to `nodes` * number of hours since

1778

# last billing cycle plus the cost for each prediction performed.

1779

},

1780

"state": "A String", # Output only. The state of a version.

1781

"name": "A String", # Required. The name specified for the version when it was created.

1782

#

1783

# The version name must be unique within the model it is created in.

1784

"serviceAccount": "A String", # Optional. Specifies the service account for resource access control.

1785

"pythonVersion": "A String", # Required. The version of Python used in prediction.

1786

#

1787

# The following Python versions are available:

1788

#

1789

# * Python '3.7' is available when `runtime_version` is set to '1.15' or

1790

# later.

1791

# * Python '3.5' is available when `runtime_version` is set to a version

1792

# from '1.4' to '1.14'.

1793

# * Python '2.7' is available when `runtime_version` is set to '1.15' or

1794

# earlier.

1795

#

1796

# Read more about the Python versions available for [each runtime

1797

# version](/ml-engine/docs/runtime-version-list).

1798

"lastUseTime": "A String", # Output only. The time the version was last used for prediction.

1799

"predictionClass": "A String", # Optional. The fully qualified name

1800

# (<var>module_name</var>.<var>class_name</var>) of a class that implements

1801

# the Predictor interface described in this reference field. The module

1802

# containing this class should be included in a package provided to the

1803

# [`packageUris` field](#Version.FIELDS.package_uris).

1804

#

1805

# Specify this field if and only if you are deploying a [custom prediction

1806

# routine (beta)](/ml-engine/docs/tensorflow/custom-prediction-routines).

1807

# If you specify this field, you must set

1808

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater and

1809

# you must set `machineType` to a [legacy (MLS1)

1810

# machine type](/ml-engine/docs/machine-types-online-prediction).

1811

#

1812

# The following code sample provides the Predictor interface:

1813

#

1814

# <pre style="max-width: 626px;">

1815

# class Predictor(object):

1816

# """Interface for constructing custom predictors."""

1817

#

1818

# def predict(self, instances, **kwargs):

1819

# """Performs custom prediction.

1820

#

1821

# Instances are the decoded values from the request. They have already

1822

# been deserialized from JSON.

1823

#

1824

# Args:

1825

# instances: A list of prediction input instances.

1826

# **kwargs: A dictionary of keyword args provided as additional

1827

# fields on the predict request body.

1828

#

1829

# Returns:

1830

# A list of outputs containing the prediction results. This list must

1831

# be JSON serializable.

1832

# """

1833

# raise NotImplementedError()

1834

#

1835

# @classmethod

1836

# def from_path(cls, model_dir):

1837

# """Creates an instance of Predictor using the given path.

1838

#

1839

# Loading of the predictor should be done in this method.

1840

#

1841

# Args:

1842

# model_dir: The local directory that contains the exported model

1843

# file along with any additional files uploaded when creating the

# version resource.

#

# Returns:

# An instance implementing this Predictor class.

1848

# """

1849

# raise NotImplementedError()

1850

# </pre>

1851

#

1852

# Learn more about [the Predictor interface and custom prediction

1853

# routines](/ml-engine/docs/tensorflow/custom-prediction-routines).

1854

"deploymentUri": "A String", # Required. The Cloud Storage location of the trained model used to

1855

# create the version. See the

1856

# [guide to model

1857

# deployment](/ml-engine/docs/tensorflow/deploying-models) for more

1858

# information.

1859

#

1860

# When passing Version to

1861

# projects.models.versions.create

1862

# the model service uses the specified location as the source of the model.

1863

# Once deployed, the model version is hosted by the prediction service, so

1864

# this location is useful only as a historical record.

1865

# The total number of model files can't exceed 1000.

1866

"packageUris": [ # Optional. Cloud Storage paths (`gs://…`) of packages for [custom

1867

# prediction routines](/ml-engine/docs/tensorflow/custom-prediction-routines)

1868

# or [scikit-learn pipelines with custom

1869

# code](/ml-engine/docs/scikit/exporting-for-prediction#custom-pipeline-code).

1870

#

1871

# For a custom prediction routine, one of these packages must contain your

1872

# Predictor class (see

1873

# [`predictionClass`](#Version.FIELDS.prediction_class)). Additionally,

1874

# include any dependencies used by your Predictor or scikit-learn pipeline

1875

# uses that are not already included in your selected [runtime

1876

# version](/ml-engine/docs/tensorflow/runtime-version-list).

1877

#

1878

# If you specify this field, you must also set

1879

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater.

1880

"A String",

1881

],

1882

"explanationConfig": { # Message holding configuration options for explaining model predictions. # Optional. Configures explainability features on the model's version.

1883

# Some explanation features require additional metadata to be loaded

1884

# as part of the model payload.

1885

# There are two feature attribution methods supported for TensorFlow models:

1886

# integrated gradients and sampled Shapley.

1887

# [Learn more about feature

1888

# attributions.](/ai-platform/prediction/docs/ai-explanations/overview)

1889

"integratedGradientsAttribution": { # Attributes credit by computing the Aumann-Shapley value taking advantage # Attributes credit by computing the Aumann-Shapley value taking advantage

1890

# of the model's fully differentiable structure. Refer to this paper for

1891

# more details: http://proceedings.mlr.press/v70/sundararajan17a.html

1892

# of the model's fully differentiable structure. Refer to this paper for

1893

# more details: https://arxiv.org/abs/1703.01365

1894

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

1895

# A good value to start is 50 and gradually increase until the

1896

# sum to diff property is met within the desired error range.

1897

},

1898

"sampledShapleyAttribution": { # An attribution method that approximates Shapley values for features that # An attribution method that approximates Shapley values for features that

1899

# contribute to the label being predicted. A sampling strategy is used to

1900

# approximate the value rather than considering all subsets of features.

1901

# contribute to the label being predicted. A sampling strategy is used to

1902

# approximate the value rather than considering all subsets of features.

1903

"numPaths": 42, # The number of feature permutations to consider when approximating the

1904

# Shapley values.

1905

},

1906

"xraiAttribution": { # Attributes credit by computing the XRAI taking advantage # Attributes credit by computing the XRAI taking advantage

1907

# of the model's fully differentiable structure. Refer to this paper for

1908

# more details: https://arxiv.org/abs/1906.02825

1909

# Currently only implemented for models with natural image inputs.

1910

# of the model's fully differentiable structure. Refer to this paper for

1911

# more details: https://arxiv.org/abs/1906.02825

1912

# Currently only implemented for models with natural image inputs.

1913

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

1914

# A good value to start is 50 and gradually increase until the

1915

# sum to diff property is met within the desired error range.

1916

},

1917

},

1918

"autoScaling": { # Options for automatically scaling a model. # Automatically scale the number of nodes used to serve the model in

1919

# response to increases and decreases in traffic. Care should be

1920

# taken to ramp up traffic according to the model's ability to scale

1921

# or you will start seeing increases in latency and 429 response codes.

1922

#

1923

# Note that you cannot use AutoScaling if your version uses

1924

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use specify

1925

# `manual_scaling`.

1926

"minNodes": 42, # Optional. The minimum number of nodes to allocate for this model. These

1927

# nodes are always up, starting from the time the model is deployed.

1928

# Therefore, the cost of operating this model will be at least

1929

# `rate` * `min_nodes` * number of hours since last billing cycle,

1930

# where `rate` is the cost per node-hour as documented in the

1931

# [pricing guide](/ml-engine/docs/pricing),

1932

# even if no predictions are performed. There is additional cost for each

1933

# prediction performed.

1934

#

1935

# Unlike manual scaling, if the load gets too heavy for the nodes

1936

# that are up, the service will automatically add nodes to handle the

1937

# increased load as well as scale back as traffic drops, always maintaining

1938

# at least `min_nodes`. You will be charged for the time in which additional

1939

# nodes are used.

1940

#

1941

# If `min_nodes` is not specified and AutoScaling is used with a [legacy

1942

# (MLS1) machine type](/ml-engine/docs/machine-types-online-prediction),

1943

# `min_nodes` defaults to 0, in which case, when traffic to a model stops

1944

# (and after a cool-down period), nodes will be shut down and no charges will

1945

# be incurred until traffic to the model resumes.

1946

#

1947

# If `min_nodes` is not specified and AutoScaling is used with a [Compute

1948

# Engine (N1) machine type](/ml-engine/docs/machine-types-online-prediction),

1949

# `min_nodes` defaults to 1. `min_nodes` must be at least 1 for use with a

1950

# Compute Engine machine type.

1951

#

1952

# Note that you cannot use AutoScaling if your version uses

1953

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use

1954

# ManualScaling.

1955

#

1956

# You can set `min_nodes` when creating the model version, and you can also

1957

# update `min_nodes` for an existing version:

# <pre>

# update_body.json:

# {

# 'autoScaling': {

# 'minNodes': 5

# }

# }

# </pre>

# HTTP request:

# <pre style="max-width: 626px;">

1968

# PATCH

1969

# https://ml.googleapis.com/v1/{name=projects/*/models/*/versions/*}?update_mask=autoScaling.minNodes

1970

# -d @./update_body.json

1971

# </pre>

1972

},

1973

"createTime": "A String", # Output only. The time the version was created.

1974

"labels": { # Optional. One or more labels that you can add, to organize your model

1975

# versions. Each label is a key-value pair, where both the key and the value

1976

# are arbitrary strings that you supply.

Bu Sun Kim

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

[diff] [blame]

1977

# For more information, see the documentation on

Bu Sun Kim

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

[diff] [blame]

1978

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

1979

"a_key": "A String",

Bu Sun Kim

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

[diff] [blame]

1980

},

Bu Sun Kim

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

[diff] [blame^]

1981

"requestLoggingConfig": { # Configuration for logging request-response pairs to a BigQuery table. # Optional. *Only* specify this field in a

1982

# projects.models.versions.patch

1983

# request. Specifying it in a

1984

# projects.models.versions.create

1985

# request has no effect.

Bu Sun Kim

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

[diff] [blame]

1986

#

Bu Sun Kim

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

[diff] [blame^]

1987

# Configures the request-response pair logging on predictions from this

1988

# Version.

1989

# Online prediction requests to a model version and the responses to these

1990

# requests are converted to raw strings and saved to the specified BigQuery

1991

# table. Logging is constrained by [BigQuery quotas and

1992

# limits](/bigquery/quotas). If your project exceeds BigQuery quotas or limits,

1993

# AI Platform Prediction does not log request-response pairs, but it continues

1994

# to serve predictions.

Bu Sun Kim

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

[diff] [blame]

1995

#

Bu Sun Kim

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

[diff] [blame^]

1996

# If you are using [continuous

1997

# evaluation](/ml-engine/docs/continuous-evaluation/), you do not need to

1998

# specify this configuration manually. Setting up continuous evaluation

1999

# automatically enables logging of request-response pairs.

2000

"bigqueryTableName": "A String", # Required. Fully qualified BigQuery table name in the following format:

2001

# "<var>project_id</var>.<var>dataset_name</var>.<var>table_name</var>"

Bu Sun Kim

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

[diff] [blame]

2002

#

Bu Sun Kim

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

[diff] [blame^]

2003

# The specified table must already exist, and the "Cloud ML Service Agent"

2004

# for your project must have permission to write to it. The table must have

2005

# the following [schema](/bigquery/docs/schemas):

Bu Sun Kim

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

[diff] [blame]

2006

#

Bu Sun Kim

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

[diff] [blame^]

2007

# <table>

2008

# <tr><th>Field name</th><th style="display: table-cell">Type</th>

2009

# <th style="display: table-cell">Mode</th></tr>

2010

# <tr><td>model</td><td>STRING</td><td>REQUIRED</td></tr>

2011

# <tr><td>model_version</td><td>STRING</td><td>REQUIRED</td></tr>

2012

# <tr><td>time</td><td>TIMESTAMP</td><td>REQUIRED</td></tr>

2013

# <tr><td>raw_data</td><td>STRING</td><td>REQUIRED</td></tr>

2014

# <tr><td>raw_prediction</td><td>STRING</td><td>NULLABLE</td></tr>

2015

# <tr><td>groundtruth</td><td>STRING</td><td>NULLABLE</td></tr>

2016

# </table>

2017

"samplingPercentage": 3.14, # Percentage of requests to be logged, expressed as a fraction from 0 to 1.

2018

# For example, if you want to log 10% of requests, enter `0.1`. The sampling

2019

# window is the lifetime of the model version. Defaults to 0.

Bu Sun Kim

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

[diff] [blame]

2020

},

Bu Sun Kim

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

[diff] [blame^]

2021

"errorMessage": "A String", # Output only. The details of a failure or a cancellation.

2022

"machineType": "A String", # Optional. The type of machine on which to serve the model. Currently only

2023

# applies to online prediction service. If this field is not specified, it

2024

# defaults to `mls1-c1-m2`.

Bu Sun Kim

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

[diff] [blame]

2025

#

Bu Sun Kim

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

[diff] [blame^]

2026

# Online prediction supports the following machine types:

Bu Sun Kim

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

[diff] [blame]

2027

#

Bu Sun Kim

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

[diff] [blame^]

# * `mls1-c1-m2`

# * `mls1-c4-m2`

# * `n1-standard-2`

# * `n1-standard-4`

# * `n1-standard-8`

# * `n1-standard-16`

# * `n1-standard-32`

# * `n1-highmem-2`

# * `n1-highmem-4`

# * `n1-highmem-8`

# * `n1-highmem-16`

# * `n1-highmem-32`

# * `n1-highcpu-2`

# * `n1-highcpu-4`

# * `n1-highcpu-8`

# * `n1-highcpu-16`

# * `n1-highcpu-32`

#

# `mls1-c1-m2` is generally available. All other machine types are available

2047

# in beta. Learn more about the [differences between machine

2048

# types](/ml-engine/docs/machine-types-online-prediction).

2049

"runtimeVersion": "A String", # Required. The AI Platform runtime version to use for this deployment.

2050

#

2051

# For more information, see the

2052

# [runtime version list](/ml-engine/docs/runtime-version-list) and

2053

# [how to manage runtime versions](/ml-engine/docs/versioning).

2054

"description": "A String", # Optional. The description specified for the version when it was created.

2055

"framework": "A String", # Optional. The machine learning framework AI Platform uses to train

2056

# this version of the model. Valid values are `TENSORFLOW`, `SCIKIT_LEARN`,

2057

# `XGBOOST`. If you do not specify a framework, AI Platform

2058

# will analyze files in the deployment_uri to determine a framework. If you

2059

# choose `SCIKIT_LEARN` or `XGBOOST`, you must also set the runtime version

2060

# of the model to 1.4 or greater.

2061

#

2062

# Do **not** specify a framework if you're deploying a [custom

2063

# prediction routine](/ml-engine/docs/tensorflow/custom-prediction-routines).

2064

#

2065

# If you specify a [Compute Engine (N1) machine

2066

# type](/ml-engine/docs/machine-types-online-prediction) in the

2067

# `machineType` field, you must specify `TENSORFLOW`

2068

# for the framework.

Bu Sun Kim

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

[diff] [blame]

2069

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

Bu Sun Kim

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

[diff] [blame]

2070

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

2071

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

2072

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

Bu Sun Kim

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

[diff] [blame^]

2073

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

2074

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

Bu Sun Kim

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

[diff] [blame]

2075

# ensure that their change will be applied to the model as intended.

Sai Cheemalapati

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

[diff] [blame]

2076

},

Bu Sun Kim

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

[diff] [blame^]

2077

"onlinePredictionConsoleLogging": True or False, # Optional. If true, online prediction nodes send `stderr` and `stdout`

2078

# streams to Stackdriver Logging. These can be more verbose than the standard

2079

# access logs (see `onlinePredictionLogging`) and can incur higher cost.

2080

# However, they are helpful for debugging. Note that

2081

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

2082

# your project receives prediction requests at a high QPS. Estimate your

2083

# costs before enabling this option.

2084

#

2085

# Default is false.

2086

"regions": [ # Optional. The list of regions where the model is going to be deployed.

2087

# Only one region per model is supported.

2088

# Defaults to 'us-central1' if nothing is set.

2089

# See the <a href="/ml-engine/docs/tensorflow/regions">available regions</a>

2090

# for AI Platform services.

2091

# Note:

2092

# * No matter where a model is deployed, it can always be accessed by

2093

# users from anywhere, both for online and batch prediction.

2094

# * The region for a batch prediction job is set by the region field when

2095

# submitting the batch prediction job and does not take its value from

# this field.

"A String",

],

"description": "A String", # Optional. The description specified for the model when it was created.

2100

"onlinePredictionLogging": True or False, # Optional. If true, online prediction access logs are sent to StackDriver

2101

# Logging. These logs are like standard server access logs, containing

2102

# information like timestamp and latency for each request. Note that

2103

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

2104

# your project receives prediction requests at a high queries per second rate

2105

# (QPS). Estimate your costs before enabling this option.

2106

#

2107

# Default is false.

2108

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

2109

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

2110

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

2111

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

2112

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

2113

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

2114

# ensure that their change will be applied to the model as intended.

2115

"labels": { # Optional. One or more labels that you can add, to organize your models.

2116

# Each label is a key-value pair, where both the key and the value are

2117

# arbitrary strings that you supply.

2118

# For more information, see the documentation on

2119

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

2120

"a_key": "A String",

2121

},

2122

"name": "A String", # Required. The name specified for the model when it was created.

2123

#

2124

# The model name must be unique within the project it is created in.

2125

},

Sai Cheemalapati

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

[diff] [blame]

2126

],

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>

2132

<pre>Retrieves the next page of results.

2133

2134

Args:

2135

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

2136

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

2137

2138

Returns:

Bu Sun Kim

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

[diff] [blame]

2139

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

Sai Cheemalapati

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

[diff] [blame]

2140

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

</pre>

</div>

Bu Sun Kim

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

[diff] [blame]

2144

Dan O'Meara

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

[diff] [blame]

2145

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

Bu Sun Kim

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

[diff] [blame]

2146

<pre>Updates a specific model resource.

2147

2148

Currently the only supported fields to update are `description` and

2149

`default_version.name`.

Args:

Dan O'Meara

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

[diff] [blame]

2153

body: object, The request body.

Bu Sun Kim

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

[diff] [blame]

2154

The object takes the form of:

2155

2156

{ # Represents a machine learning solution.

Bu Sun Kim

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

[diff] [blame^]

2157

#

2158

# A model can have multiple versions, each of which is a deployed, trained

2159

# model ready to receive prediction requests. The model itself is just a

2160

# container.

2161

"defaultVersion": { # Represents a version of the model. # Output only. The default version of the model. This version will be used to

2162

# handle prediction requests that do not specify a version.

Dan O'Meara

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

[diff] [blame]

2163

#

Bu Sun Kim

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

[diff] [blame^]

2164

# You can change the default version by calling

2165

# projects.models.versions.setDefault.

2166

#

2167

# Each version is a trained model deployed in the cloud, ready to handle

2168

# prediction requests. A model can have multiple versions. You can get

2169

# information about all of the versions of a given model by calling

2170

# projects.models.versions.list.

2171

"acceleratorConfig": { # Represents a hardware accelerator request config. # Optional. Accelerator config for using GPUs for online prediction (beta).

2172

# Only specify this field if you have specified a Compute Engine (N1) machine

2173

# type in the `machineType` field. Learn more about [using GPUs for online

2174

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

2175

# Note that the AcceleratorConfig can be used in both Jobs and Versions.

2176

# Learn more about [accelerators for training](/ml-engine/docs/using-gpus) and

2177

# [accelerators for online

2178

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

2179

"count": "A String", # The number of accelerators to attach to each machine running the job.

2180

"type": "A String", # The type of accelerator to use.

2181

},

2182

"isDefault": True or False, # Output only. If true, this version will be used to handle prediction

2183

# requests that do not specify a version.

2184

#

2185

# You can change the default version by calling

2186

# projects.methods.versions.setDefault.

2187

"manualScaling": { # Options for manually scaling a model. # Manually select the number of nodes to use for serving the

2188

# model. You should generally use `auto_scaling` with an appropriate

2189

# `min_nodes` instead, but this option is available if you want more

2190

# predictable billing. Beware that latency and error rates will increase

2191

# if the traffic exceeds that capability of the system to serve it based

2192

# on the selected number of nodes.

2193

"nodes": 42, # The number of nodes to allocate for this model. These nodes are always up,

2194

# starting from the time the model is deployed, so the cost of operating

2195

# this model will be proportional to `nodes` * number of hours since

2196

# last billing cycle plus the cost for each prediction performed.

2197

},

2198

"state": "A String", # Output only. The state of a version.

2199

"name": "A String", # Required. The name specified for the version when it was created.

2200

#

2201

# The version name must be unique within the model it is created in.

2202

"serviceAccount": "A String", # Optional. Specifies the service account for resource access control.

2203

"pythonVersion": "A String", # Required. The version of Python used in prediction.

2204

#

2205

# The following Python versions are available:

2206

#

2207

# * Python '3.7' is available when `runtime_version` is set to '1.15' or

2208

# later.

2209

# * Python '3.5' is available when `runtime_version` is set to a version

2210

# from '1.4' to '1.14'.

2211

# * Python '2.7' is available when `runtime_version` is set to '1.15' or

2212

# earlier.

2213

#

2214

# Read more about the Python versions available for [each runtime

2215

# version](/ml-engine/docs/runtime-version-list).

2216

"lastUseTime": "A String", # Output only. The time the version was last used for prediction.

2217

"predictionClass": "A String", # Optional. The fully qualified name

2218

# (<var>module_name</var>.<var>class_name</var>) of a class that implements

2219

# the Predictor interface described in this reference field. The module

2220

# containing this class should be included in a package provided to the

2221

# [`packageUris` field](#Version.FIELDS.package_uris).

2222

#

2223

# Specify this field if and only if you are deploying a [custom prediction

2224

# routine (beta)](/ml-engine/docs/tensorflow/custom-prediction-routines).

2225

# If you specify this field, you must set

2226

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater and

2227

# you must set `machineType` to a [legacy (MLS1)

2228

# machine type](/ml-engine/docs/machine-types-online-prediction).

2229

#

2230

# The following code sample provides the Predictor interface:

2231

#

2232

# <pre style="max-width: 626px;">

2233

# class Predictor(object):

2234

# """Interface for constructing custom predictors."""

2235

#

2236

# def predict(self, instances, **kwargs):

2237

# """Performs custom prediction.

2238

#

2239

# Instances are the decoded values from the request. They have already

2240

# been deserialized from JSON.

2241

#

2242

# Args:

2243

# instances: A list of prediction input instances.

2244

# **kwargs: A dictionary of keyword args provided as additional

2245

# fields on the predict request body.

2246

#

2247

# Returns:

2248

# A list of outputs containing the prediction results. This list must

2249

# be JSON serializable.

2250

# """

2251

# raise NotImplementedError()

2252

#

2253

# @classmethod

2254

# def from_path(cls, model_dir):

2255

# """Creates an instance of Predictor using the given path.

2256

#

2257

# Loading of the predictor should be done in this method.

2258

#

2259

# Args:

2260

# model_dir: The local directory that contains the exported model

2261

# file along with any additional files uploaded when creating the

# version resource.

#

# Returns:

# An instance implementing this Predictor class.

2266

# """

2267

# raise NotImplementedError()

2268

# </pre>

2269

#

2270

# Learn more about [the Predictor interface and custom prediction

2271

# routines](/ml-engine/docs/tensorflow/custom-prediction-routines).

2272

"deploymentUri": "A String", # Required. The Cloud Storage location of the trained model used to

2273

# create the version. See the

2274

# [guide to model

2275

# deployment](/ml-engine/docs/tensorflow/deploying-models) for more

2276

# information.

2277

#

2278

# When passing Version to

2279

# projects.models.versions.create

2280

# the model service uses the specified location as the source of the model.

2281

# Once deployed, the model version is hosted by the prediction service, so

2282

# this location is useful only as a historical record.

2283

# The total number of model files can't exceed 1000.

2284

"packageUris": [ # Optional. Cloud Storage paths (`gs://…`) of packages for [custom

2285

# prediction routines](/ml-engine/docs/tensorflow/custom-prediction-routines)

2286

# or [scikit-learn pipelines with custom

2287

# code](/ml-engine/docs/scikit/exporting-for-prediction#custom-pipeline-code).

2288

#

2289

# For a custom prediction routine, one of these packages must contain your

2290

# Predictor class (see

2291

# [`predictionClass`](#Version.FIELDS.prediction_class)). Additionally,

2292

# include any dependencies used by your Predictor or scikit-learn pipeline

2293

# uses that are not already included in your selected [runtime

2294

# version](/ml-engine/docs/tensorflow/runtime-version-list).

2295

#

2296

# If you specify this field, you must also set

2297

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater.

2298

"A String",

2299

],

2300

"explanationConfig": { # Message holding configuration options for explaining model predictions. # Optional. Configures explainability features on the model's version.

2301

# Some explanation features require additional metadata to be loaded

2302

# as part of the model payload.

2303

# There are two feature attribution methods supported for TensorFlow models:

2304

# integrated gradients and sampled Shapley.

2305

# [Learn more about feature

2306

# attributions.](/ai-platform/prediction/docs/ai-explanations/overview)

2307

"integratedGradientsAttribution": { # Attributes credit by computing the Aumann-Shapley value taking advantage # Attributes credit by computing the Aumann-Shapley value taking advantage

2308

# of the model's fully differentiable structure. Refer to this paper for

2309

# more details: http://proceedings.mlr.press/v70/sundararajan17a.html

2310

# of the model's fully differentiable structure. Refer to this paper for

2311

# more details: https://arxiv.org/abs/1703.01365

2312

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

2313

# A good value to start is 50 and gradually increase until the

2314

# sum to diff property is met within the desired error range.

2315

},

2316

"sampledShapleyAttribution": { # An attribution method that approximates Shapley values for features that # An attribution method that approximates Shapley values for features that

2317

# contribute to the label being predicted. A sampling strategy is used to

2318

# approximate the value rather than considering all subsets of features.

2319

# contribute to the label being predicted. A sampling strategy is used to

2320

# approximate the value rather than considering all subsets of features.

2321

"numPaths": 42, # The number of feature permutations to consider when approximating the

2322

# Shapley values.

2323

},

2324

"xraiAttribution": { # Attributes credit by computing the XRAI taking advantage # Attributes credit by computing the XRAI taking advantage

2325

# of the model's fully differentiable structure. Refer to this paper for

2326

# more details: https://arxiv.org/abs/1906.02825

2327

# Currently only implemented for models with natural image inputs.

2328

# of the model's fully differentiable structure. Refer to this paper for

2329

# more details: https://arxiv.org/abs/1906.02825

2330

# Currently only implemented for models with natural image inputs.

2331

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

2332

# A good value to start is 50 and gradually increase until the

2333

# sum to diff property is met within the desired error range.

2334

},

2335

},

2336

"autoScaling": { # Options for automatically scaling a model. # Automatically scale the number of nodes used to serve the model in

2337

# response to increases and decreases in traffic. Care should be

2338

# taken to ramp up traffic according to the model's ability to scale

2339

# or you will start seeing increases in latency and 429 response codes.

2340

#

2341

# Note that you cannot use AutoScaling if your version uses

2342

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use specify

2343

# `manual_scaling`.

2344

"minNodes": 42, # Optional. The minimum number of nodes to allocate for this model. These

2345

# nodes are always up, starting from the time the model is deployed.

2346

# Therefore, the cost of operating this model will be at least

2347

# `rate` * `min_nodes` * number of hours since last billing cycle,

2348

# where `rate` is the cost per node-hour as documented in the

2349

# [pricing guide](/ml-engine/docs/pricing),

2350

# even if no predictions are performed. There is additional cost for each

2351

# prediction performed.

2352

#

2353

# Unlike manual scaling, if the load gets too heavy for the nodes

2354

# that are up, the service will automatically add nodes to handle the

2355

# increased load as well as scale back as traffic drops, always maintaining

2356

# at least `min_nodes`. You will be charged for the time in which additional

2357

# nodes are used.

2358

#

2359

# If `min_nodes` is not specified and AutoScaling is used with a [legacy

2360

# (MLS1) machine type](/ml-engine/docs/machine-types-online-prediction),

2361

# `min_nodes` defaults to 0, in which case, when traffic to a model stops

2362

# (and after a cool-down period), nodes will be shut down and no charges will

2363

# be incurred until traffic to the model resumes.

2364

#

2365

# If `min_nodes` is not specified and AutoScaling is used with a [Compute

2366

# Engine (N1) machine type](/ml-engine/docs/machine-types-online-prediction),

2367

# `min_nodes` defaults to 1. `min_nodes` must be at least 1 for use with a

2368

# Compute Engine machine type.

2369

#

2370

# Note that you cannot use AutoScaling if your version uses

2371

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use

2372

# ManualScaling.

2373

#

2374

# You can set `min_nodes` when creating the model version, and you can also

2375

# update `min_nodes` for an existing version:

# <pre>

# update_body.json:

# {

# 'autoScaling': {

# 'minNodes': 5

# }

# }

# </pre>

# HTTP request:

# <pre style="max-width: 626px;">

2386

# PATCH

2387

# https://ml.googleapis.com/v1/{name=projects/*/models/*/versions/*}?update_mask=autoScaling.minNodes

2388

# -d @./update_body.json

2389

# </pre>

2390

},

2391

"createTime": "A String", # Output only. The time the version was created.

2392

"labels": { # Optional. One or more labels that you can add, to organize your model

2393

# versions. Each label is a key-value pair, where both the key and the value

2394

# are arbitrary strings that you supply.

Bu Sun Kim

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

[diff] [blame]

2395

# For more information, see the documentation on

Bu Sun Kim

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

[diff] [blame]

2396

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

2397

"a_key": "A String",

Bu Sun Kim

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

[diff] [blame]

2398

},

Bu Sun Kim

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

[diff] [blame^]

2399

"requestLoggingConfig": { # Configuration for logging request-response pairs to a BigQuery table. # Optional. *Only* specify this field in a

2400

# projects.models.versions.patch

2401

# request. Specifying it in a

2402

# projects.models.versions.create

2403

# request has no effect.

Bu Sun Kim

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

[diff] [blame]

2404

#

Bu Sun Kim

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

[diff] [blame^]

2405

# Configures the request-response pair logging on predictions from this

2406

# Version.

2407

# Online prediction requests to a model version and the responses to these

2408

# requests are converted to raw strings and saved to the specified BigQuery

2409

# table. Logging is constrained by [BigQuery quotas and

2410

# limits](/bigquery/quotas). If your project exceeds BigQuery quotas or limits,

2411

# AI Platform Prediction does not log request-response pairs, but it continues

2412

# to serve predictions.

2413

#

2414

# If you are using [continuous

2415

# evaluation](/ml-engine/docs/continuous-evaluation/), you do not need to

2416

# specify this configuration manually. Setting up continuous evaluation

2417

# automatically enables logging of request-response pairs.

2418

"bigqueryTableName": "A String", # Required. Fully qualified BigQuery table name in the following format:

2419

# "<var>project_id</var>.<var>dataset_name</var>.<var>table_name</var>"

Bu Sun Kim

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

[diff] [blame]

2420

#

Bu Sun Kim

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

[diff] [blame^]

2421

# The specified table must already exist, and the "Cloud ML Service Agent"

2422

# for your project must have permission to write to it. The table must have

2423

# the following [schema](/bigquery/docs/schemas):

Bu Sun Kim

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

[diff] [blame]

2424

#

Bu Sun Kim

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

[diff] [blame^]

2425

# <table>

2426

# <tr><th>Field name</th><th style="display: table-cell">Type</th>

2427

# <th style="display: table-cell">Mode</th></tr>

2428

# <tr><td>model</td><td>STRING</td><td>REQUIRED</td></tr>

2429

# <tr><td>model_version</td><td>STRING</td><td>REQUIRED</td></tr>

2430

# <tr><td>time</td><td>TIMESTAMP</td><td>REQUIRED</td></tr>

2431

# <tr><td>raw_data</td><td>STRING</td><td>REQUIRED</td></tr>

2432

# <tr><td>raw_prediction</td><td>STRING</td><td>NULLABLE</td></tr>

2433

# <tr><td>groundtruth</td><td>STRING</td><td>NULLABLE</td></tr>

2434

# </table>

2435

"samplingPercentage": 3.14, # Percentage of requests to be logged, expressed as a fraction from 0 to 1.

2436

# For example, if you want to log 10% of requests, enter `0.1`. The sampling

2437

# window is the lifetime of the model version. Defaults to 0.

Bu Sun Kim

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

[diff] [blame]

2438

},

Bu Sun Kim

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

[diff] [blame^]

2439

"errorMessage": "A String", # Output only. The details of a failure or a cancellation.

2440

"machineType": "A String", # Optional. The type of machine on which to serve the model. Currently only

2441

# applies to online prediction service. If this field is not specified, it

2442

# defaults to `mls1-c1-m2`.

2443

#

2444

# Online prediction supports the following machine types:

#

# * `mls1-c1-m2`

# * `mls1-c4-m2`

# * `n1-standard-2`

# * `n1-standard-4`

# * `n1-standard-8`

# * `n1-standard-16`

# * `n1-standard-32`

# * `n1-highmem-2`

# * `n1-highmem-4`

# * `n1-highmem-8`

# * `n1-highmem-16`

# * `n1-highmem-32`

# * `n1-highcpu-2`

# * `n1-highcpu-4`

# * `n1-highcpu-8`

# * `n1-highcpu-16`

# * `n1-highcpu-32`

#

# `mls1-c1-m2` is generally available. All other machine types are available

2465

# in beta. Learn more about the [differences between machine

2466

# types](/ml-engine/docs/machine-types-online-prediction).

2467

"runtimeVersion": "A String", # Required. The AI Platform runtime version to use for this deployment.

2468

#

2469

# For more information, see the

2470

# [runtime version list](/ml-engine/docs/runtime-version-list) and

2471

# [how to manage runtime versions](/ml-engine/docs/versioning).

2472

"description": "A String", # Optional. The description specified for the version when it was created.

2473

"framework": "A String", # Optional. The machine learning framework AI Platform uses to train

2474

# this version of the model. Valid values are `TENSORFLOW`, `SCIKIT_LEARN`,

2475

# `XGBOOST`. If you do not specify a framework, AI Platform

2476

# will analyze files in the deployment_uri to determine a framework. If you

2477

# choose `SCIKIT_LEARN` or `XGBOOST`, you must also set the runtime version

2478

# of the model to 1.4 or greater.

2479

#

2480

# Do **not** specify a framework if you're deploying a [custom

2481

# prediction routine](/ml-engine/docs/tensorflow/custom-prediction-routines).

2482

#

2483

# If you specify a [Compute Engine (N1) machine

2484

# type](/ml-engine/docs/machine-types-online-prediction) in the

2485

# `machineType` field, you must specify `TENSORFLOW`

2486

# for the framework.

Bu Sun Kim

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

[diff] [blame]

2487

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

Bu Sun Kim

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

[diff] [blame]

2488

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

2489

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

2490

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

Bu Sun Kim

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

[diff] [blame^]

2491

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

2492

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

Bu Sun Kim

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

[diff] [blame]

2493

# ensure that their change will be applied to the model as intended.

Bu Sun Kim

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

[diff] [blame^]

2494

},

2495

"onlinePredictionConsoleLogging": True or False, # Optional. If true, online prediction nodes send `stderr` and `stdout`

2496

# streams to Stackdriver Logging. These can be more verbose than the standard

2497

# access logs (see `onlinePredictionLogging`) and can incur higher cost.

2498

# However, they are helpful for debugging. Note that

2499

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

2500

# your project receives prediction requests at a high QPS. Estimate your

2501

# costs before enabling this option.

2502

#

2503

# Default is false.

2504

"regions": [ # Optional. The list of regions where the model is going to be deployed.

2505

# Only one region per model is supported.

2506

# Defaults to 'us-central1' if nothing is set.

2507

# See the <a href="/ml-engine/docs/tensorflow/regions">available regions</a>

2508

# for AI Platform services.

2509

# Note:

2510

# * No matter where a model is deployed, it can always be accessed by

2511

# users from anywhere, both for online and batch prediction.

2512

# * The region for a batch prediction job is set by the region field when

2513

# submitting the batch prediction job and does not take its value from

# this field.

"A String",

],

"description": "A String", # Optional. The description specified for the model when it was created.

2518

"onlinePredictionLogging": True or False, # Optional. If true, online prediction access logs are sent to StackDriver

2519

# Logging. These logs are like standard server access logs, containing

2520

# information like timestamp and latency for each request. Note that

2521

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

2522

# your project receives prediction requests at a high queries per second rate

2523

# (QPS). Estimate your costs before enabling this option.

2524

#

2525

# Default is false.

2526

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

2527

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

2528

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

2529

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

2530

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

2531

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

2532

# ensure that their change will be applied to the model as intended.

2533

"labels": { # Optional. One or more labels that you can add, to organize your models.

2534

# Each label is a key-value pair, where both the key and the value are

2535

# arbitrary strings that you supply.

2536

# For more information, see the documentation on

2537

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

2538

"a_key": "A String",

2539

},

2540

"name": "A String", # Required. The name specified for the model when it was created.

2541

#

2542

# The model name must be unique within the project it is created in.

2543

}

Bu Sun Kim

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

[diff] [blame]

2544

2545

updateMask: string, Required. Specifies the path, relative to `Model`, of the field to update.

2546

Bu Sun Kim

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

[diff] [blame]

2547

For example, to change the description of a model to "foo" and set its

2548

default version to "version_1", the `update_mask` parameter would be

Bu Sun Kim

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

[diff] [blame]

2549

specified as `description`, `default_version.name`, and the `PATCH`

2550

request body would specify the new value, as follows:

2551

{

Bu Sun Kim

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

[diff] [blame]

2552

"description": "foo",

2553

"defaultVersion": {

2554

"name":"version_1"

Bu Sun Kim

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

[diff] [blame]

}

}

Currently the supported update masks are `description` and

2559

`default_version.name`.

2560

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2567

2568

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

2569

# network API call.

Bu Sun Kim

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

[diff] [blame]

2570

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

2571

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

2572

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

Bu Sun Kim

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

[diff] [blame]

2573

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

2574

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

2575

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

2576

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

2577

#

2578

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

2579

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

Bu Sun Kim

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

[diff] [blame^]

2580

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

2581

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

2582

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

2583

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

Bu Sun Kim

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

[diff] [blame]

2584

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

2585

# message types for APIs to use.

2586

{

2587

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

2588

},

2589

],

Bu Sun Kim

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

[diff] [blame]

2590

},

2591

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

2592

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

2593

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

2594

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

2595

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

2596

},

2597

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

2598

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

2599

# available.

Bu Sun Kim

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

[diff] [blame^]

2600

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

2601

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

2602

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

2603

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

2604

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

2605

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

2606

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

2607

# `TakeSnapshotResponse`.

2608

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

2609

},

Bu Sun Kim

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

[diff] [blame]

}</pre>

</div>

Dan O'Meara

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

[diff] [blame]

2614

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

Bu Sun Kim

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

[diff] [blame]

2615

<pre>Sets the access control policy on the specified resource. Replaces any

2616

existing policy.

2617

Bu Sun Kim

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

[diff] [blame]

2618

Can return `NOT_FOUND`, `INVALID_ARGUMENT`, and `PERMISSION_DENIED` errors.

Dan O'Meara

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

[diff] [blame]

2619

Bu Sun Kim

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

[diff] [blame]

2620

Args:

2621

resource: string, REQUIRED: The resource for which the policy is being specified.

2622

See the operation documentation for the appropriate value for this field. (required)

Dan O'Meara

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

[diff] [blame]

2623

body: object, The request body.

Bu Sun Kim

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

[diff] [blame]

2624

The object takes the form of:

2625

2626

{ # Request message for `SetIamPolicy` method.

Bu Sun Kim

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

[diff] [blame^]

2627

"updateMask": "A String", # OPTIONAL: A FieldMask specifying which fields of the policy to modify. Only

2628

# the fields in the mask will be modified. If no mask is provided, the

2629

# following default mask is used:

2630

#

2631

# `paths: "bindings, etag"`

Bu Sun Kim

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

[diff] [blame]

2632

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

Bu Sun Kim

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

[diff] [blame]

2633

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

2634

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

2635

# might reject them.

Dan O'Meara

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

[diff] [blame]

2636

# controls for Google Cloud resources.

Bu Sun Kim

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

[diff] [blame]

2637

#

2638

#

Dan O'Meara

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

[diff] [blame]

2639

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

2640

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

2641

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

2642

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

2643

# custom role.

Bu Sun Kim

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

[diff] [blame]

2644

#

Bu Sun Kim

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

[diff] [blame]

2645

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

2646

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

2647

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

2648

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

2649

# resources support conditions in their IAM policies, see the

2650

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

Dan O'Meara

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

[diff] [blame]

2651

#

2652

# **JSON example:**

Bu Sun Kim

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

[diff] [blame]

2653

#

2654

# {

Bu Sun Kim

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

[diff] [blame]

2655

# "bindings": [

Bu Sun Kim

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

[diff] [blame]

2656

# {

Bu Sun Kim

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

[diff] [blame]

2657

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

2658

# "members": [

2659

# "user:mike@example.com",

2660

# "group:admins@example.com",

2661

# "domain:google.com",

2662

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

Bu Sun Kim

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

[diff] [blame]

2663

# ]

2664

# },

2665

# {

Bu Sun Kim

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

[diff] [blame]

2666

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

2667

# "members": [

2668

# "user:eve@example.com"

2669

# ],

2670

# "condition": {

2671

# "title": "expirable access",

2672

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

2673

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

Dan O'Meara

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

[diff] [blame]

2674

# }

Bu Sun Kim

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

[diff] [blame]

2675

# }

Dan O'Meara

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

[diff] [blame]

2676

# ],

Bu Sun Kim

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

[diff] [blame]

2677

# "etag": "BwWWja0YfJA=",

2678

# "version": 3

Bu Sun Kim

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

[diff] [blame]

2679

# }

2680

#

Dan O'Meara

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

[diff] [blame]

2681

# **YAML example:**

Bu Sun Kim

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

[diff] [blame]

#

# bindings:

# - members:

# - user:mike@example.com

2686

# - group:admins@example.com

2687

# - domain:google.com

Dan O'Meara

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

[diff] [blame]

2688

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

2689

# role: roles/resourcemanager.organizationAdmin

Bu Sun Kim

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

[diff] [blame]

2690

# - members:

Dan O'Meara

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

[diff] [blame]

2691

# - user:eve@example.com

2692

# role: roles/resourcemanager.organizationViewer

2693

# condition:

2694

# title: expirable access

2695

# description: Does not grant access after Sep 2020

Bu Sun Kim

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

[diff] [blame]

2696

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

Dan O'Meara

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

[diff] [blame]

2697

# - etag: BwWWja0YfJA=

2698

# - version: 3

Bu Sun Kim

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

[diff] [blame]

2699

#

2700

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

Dan O'Meara

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

[diff] [blame]

2701

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

Bu Sun Kim

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

[diff] [blame]

2702

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

2703

#

2704

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

2705

# are rejected.

2706

#

2707

# Any operation that affects conditional role bindings must specify version

2708

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

2709

#

2710

# * Getting a policy that includes a conditional role binding

2711

# * Adding a conditional role binding to a policy

2712

# * Changing a conditional role binding in a policy

2713

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

2714

# that includes conditions

2715

#

2716

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

2717

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

2718

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

2719

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

2720

#

2721

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

2722

# specify any valid version or leave the field unset.

2723

#

2724

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

2725

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

2726

"auditConfigs": [ # Specifies cloud audit logging configuration for this policy.

2727

{ # Specifies the audit configuration for a service.

2728

# The configuration determines which permission types are logged, and what

2729

# identities, if any, are exempted from logging.

2730

# An AuditConfig must have one or more AuditLogConfigs.

2731

#

2732

# If there are AuditConfigs for both `allServices` and a specific service,

2733

# the union of the two AuditConfigs is used for that service: the log_types

2734

# specified in each AuditConfig are enabled, and the exempted_members in each

2735

# AuditLogConfig are exempted.

2736

#

2737

# Example Policy with multiple AuditConfigs:

#

# {

# "audit_configs": [

# {

# "service": "allServices"

2743

# "audit_log_configs": [

2744

# {

2745

# "log_type": "DATA_READ",

2746

# "exempted_members": [

2747

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

2752

# },

2753

# {

2754

# "log_type": "ADMIN_READ",

# }

# ]

# },

# {

# "service": "sampleservice.googleapis.com"

2760

# "audit_log_configs": [

2761

# {

2762

# "log_type": "DATA_READ",

2763

# },

2764

# {

2765

# "log_type": "DATA_WRITE",

2766

# "exempted_members": [

2767

# "user:aliya@example.com"

# ]

# }

# ]

# }

# ]

# }

#

# For sampleservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ

2776

# logging. It also exempts jose@example.com from DATA_READ logging, and

2777

# aliya@example.com from DATA_WRITE logging.

2778

"service": "A String", # Specifies a service that will be enabled for audit logging.

2779

# For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.

2780

# `allServices` is a special value that covers all services.

2781

"auditLogConfigs": [ # The configuration for logging of each type of permission.

2782

{ # Provides the configuration for logging a type of permissions.

# Example:

#

# {

# "audit_log_configs": [

2787

# {

2788

# "log_type": "DATA_READ",

2789

# "exempted_members": [

2790

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

# }

# ]

# }

#

# This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting

2800

# jose@example.com from DATA_READ logging.

2801

"exemptedMembers": [ # Specifies the identities that do not cause logging for this type of

2802

# permission.

2803

# Follows the same format of Binding.members.

2804

"A String",

2805

],

2806

"logType": "A String", # The log type that this config enables.

},

],

},

],

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

2812

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

2813

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

Bu Sun Kim

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

[diff] [blame]

2814

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

Bu Sun Kim

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

[diff] [blame]

2815

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

2816

#

2817

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

2818

# current request.

2819

#

2820

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

2821

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

2822

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

2823

#

2824

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

2825

# [IAM

2826

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

2827

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

2828

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

2829

#

2830

# Example (Comparison):

2831

#

2832

# title: "Summary size limit"

2833

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

2834

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

2835

#

2836

# Example (Equality):

2837

#

2838

# title: "Requestor is owner"

2839

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

2840

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

#

# Example (Logic):

#

# title: "Public documents"

2845

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

2846

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

2847

#

2848

# Example (Data Manipulation):

2849

#

2850

# title: "Notification string"

2851

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

2852

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

2853

#

2854

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

2855

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

2856

# documentation for additional information.

Bu Sun Kim

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

[diff] [blame^]

2857

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

2858

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

2859

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

2860

# syntax.

Bu Sun Kim

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

[diff] [blame]

2861

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

2862

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

2863

# expression.

2864

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

2865

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

Bu Sun Kim

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

[diff] [blame]

2866

},

2867

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

Bu Sun Kim

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

[diff] [blame]

2868

# `members` can have the following values:

2869

#

2870

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

2871

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

2872

#

2873

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

2874

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

2875

#

2876

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

Dan O'Meara

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

[diff] [blame]

2877

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

Bu Sun Kim

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

[diff] [blame]

2878

#

2879

#

2880

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

2881

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

2882

#

2883

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

2884

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

2885

#

Dan O'Meara

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

[diff] [blame]

2886

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

2887

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

2888

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

2889

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

2890

# retains the role in the binding.

2891

#

2892

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

2893

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

2894

# deleted. For example,

2895

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

2896

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

2897

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

2898

# role in the binding.

2899

#

2900

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

2901

# identifier) representing a Google group that has been recently

2902

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

2903

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

2904

# recovered group retains the role in the binding.

2905

#

Bu Sun Kim

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

[diff] [blame]

2906

#

2907

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

2908

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

2909

#

Bu Sun Kim

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

[diff] [blame]

2910

"A String",

Bu Sun Kim

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

[diff] [blame]

2911

],

Bu Sun Kim

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

[diff] [blame]

2912

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

2913

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

Bu Sun Kim

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

[diff] [blame]

2914

},

2915

],

Bu Sun Kim

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

[diff] [blame^]

2916

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

2917

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

2918

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

2919

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

2920

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

2921

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

2922

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

2923

#

2924

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

2925

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

2926

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

2927

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

Bu Sun Kim

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

[diff] [blame]

2928

},

Bu Sun Kim

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

[diff] [blame]

2929

}

2930

2931

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2938

Dan O'Meara

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

[diff] [blame]

2939

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

2940

# controls for Google Cloud resources.

Bu Sun Kim

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

[diff] [blame]

2941

#

2942

#

Dan O'Meara

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

[diff] [blame]

2943

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

2944

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

2945

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

2946

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

2947

# custom role.

Bu Sun Kim

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

[diff] [blame]

2948

#

Bu Sun Kim

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

[diff] [blame]

2949

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

2950

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

2951

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

2952

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

2953

# resources support conditions in their IAM policies, see the

2954

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

Dan O'Meara

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

[diff] [blame]

2955

#

2956

# **JSON example:**

Bu Sun Kim

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

[diff] [blame]

2957

#

2958

# {

Bu Sun Kim

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

[diff] [blame]

2959

# "bindings": [

Bu Sun Kim

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

[diff] [blame]

2960

# {

Bu Sun Kim

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

[diff] [blame]

2961

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

2962

# "members": [

2963

# "user:mike@example.com",

2964

# "group:admins@example.com",

2965

# "domain:google.com",

2966

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

Bu Sun Kim

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

[diff] [blame]

2967

# ]

2968

# },

2969

# {

Bu Sun Kim

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

[diff] [blame]

2970

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

2971

# "members": [

2972

# "user:eve@example.com"

2973

# ],

2974

# "condition": {

2975

# "title": "expirable access",

2976

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

2977

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

Dan O'Meara

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

[diff] [blame]

2978

# }

Bu Sun Kim

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

[diff] [blame]

2979

# }

Dan O'Meara

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

[diff] [blame]

2980

# ],

Bu Sun Kim

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

[diff] [blame]

2981

# "etag": "BwWWja0YfJA=",

2982

# "version": 3

Bu Sun Kim

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

[diff] [blame]

2983

# }

2984

#

Dan O'Meara

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

[diff] [blame]

2985

# **YAML example:**

Bu Sun Kim

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

[diff] [blame]

#

# bindings:

# - members:

# - user:mike@example.com

2990

# - group:admins@example.com

2991

# - domain:google.com

Dan O'Meara

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

[diff] [blame]

2992

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

2993

# role: roles/resourcemanager.organizationAdmin

Bu Sun Kim

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

[diff] [blame]

2994

# - members:

Dan O'Meara

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

[diff] [blame]

2995

# - user:eve@example.com

2996

# role: roles/resourcemanager.organizationViewer

2997

# condition:

2998

# title: expirable access

2999

# description: Does not grant access after Sep 2020

Bu Sun Kim

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

[diff] [blame]

3000

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

Dan O'Meara

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

[diff] [blame]

3001

# - etag: BwWWja0YfJA=

3002

# - version: 3

Bu Sun Kim

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

[diff] [blame]

3003

#

3004

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

Dan O'Meara

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

[diff] [blame]

3005

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

Bu Sun Kim

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

[diff] [blame]

3006

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

3007

#

3008

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

3009

# are rejected.

3010

#

3011

# Any operation that affects conditional role bindings must specify version

3012

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

3013

#

3014

# * Getting a policy that includes a conditional role binding

3015

# * Adding a conditional role binding to a policy

3016

# * Changing a conditional role binding in a policy

3017

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

3018

# that includes conditions

3019

#

3020

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

3021

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

3022

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

3023

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

3024

#

3025

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

3026

# specify any valid version or leave the field unset.

3027

#

3028

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

3029

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

3030

"auditConfigs": [ # Specifies cloud audit logging configuration for this policy.

3031

{ # Specifies the audit configuration for a service.

3032

# The configuration determines which permission types are logged, and what

3033

# identities, if any, are exempted from logging.

3034

# An AuditConfig must have one or more AuditLogConfigs.

3035

#

3036

# If there are AuditConfigs for both `allServices` and a specific service,

3037

# the union of the two AuditConfigs is used for that service: the log_types

3038

# specified in each AuditConfig are enabled, and the exempted_members in each

3039

# AuditLogConfig are exempted.

3040

#

3041

# Example Policy with multiple AuditConfigs:

#

# {

# "audit_configs": [

# {

# "service": "allServices"

3047

# "audit_log_configs": [

3048

# {

3049

# "log_type": "DATA_READ",

3050

# "exempted_members": [

3051

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

3056

# },

3057

# {

3058

# "log_type": "ADMIN_READ",

# }

# ]

# },

# {

# "service": "sampleservice.googleapis.com"

3064

# "audit_log_configs": [

3065

# {

3066

# "log_type": "DATA_READ",

3067

# },

3068

# {

3069

# "log_type": "DATA_WRITE",

3070

# "exempted_members": [

3071

# "user:aliya@example.com"

# ]

# }

# ]

# }

# ]

# }

#

# For sampleservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ

3080

# logging. It also exempts jose@example.com from DATA_READ logging, and

3081

# aliya@example.com from DATA_WRITE logging.

3082

"service": "A String", # Specifies a service that will be enabled for audit logging.

3083

# For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.

3084

# `allServices` is a special value that covers all services.

3085

"auditLogConfigs": [ # The configuration for logging of each type of permission.

3086

{ # Provides the configuration for logging a type of permissions.

# Example:

#

# {

# "audit_log_configs": [

3091

# {

3092

# "log_type": "DATA_READ",

3093

# "exempted_members": [

3094

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

# }

# ]

# }

#

# This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting

3104

# jose@example.com from DATA_READ logging.

3105

"exemptedMembers": [ # Specifies the identities that do not cause logging for this type of

3106

# permission.

3107

# Follows the same format of Binding.members.

3108

"A String",

3109

],

3110

"logType": "A String", # The log type that this config enables.

},

],

},

],

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

3116

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

3117

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

Bu Sun Kim

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

[diff] [blame]

3118

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

Bu Sun Kim

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

[diff] [blame]

3119

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

3120

#

3121

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

3122

# current request.

3123

#

3124

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

3125

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

3126

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

3127

#

3128

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

3129

# [IAM

3130

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

3131

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

3132

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

3133

#

3134

# Example (Comparison):

3135

#

3136

# title: "Summary size limit"

3137

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

3138

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

3139

#

3140

# Example (Equality):

3141

#

3142

# title: "Requestor is owner"

3143

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

3144

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

#

# Example (Logic):

#

# title: "Public documents"

3149

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

3150

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

3151

#

3152

# Example (Data Manipulation):

3153

#

3154

# title: "Notification string"

3155

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

3156

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

3157

#

3158

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

3159

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

3160

# documentation for additional information.

Bu Sun Kim

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

[diff] [blame^]

3161

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

3162

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

3163

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

3164

# syntax.

Bu Sun Kim

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

[diff] [blame]

3165

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

3166

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

3167

# expression.

3168

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

3169

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

Bu Sun Kim

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

[diff] [blame]

3170

},

3171

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

Bu Sun Kim

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

[diff] [blame]

3172

# `members` can have the following values:

3173

#

3174

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

3175

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

3176

#

3177

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

3178

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

3179

#

3180

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

Dan O'Meara

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

[diff] [blame]

3181

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

Bu Sun Kim

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

[diff] [blame]

3182

#

3183

#

3184

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

3185

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

3186

#

3187

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

3188

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

3189

#

Dan O'Meara

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

[diff] [blame]

3190

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

3191

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

3192

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

3193

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

3194

# retains the role in the binding.

3195

#

3196

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

3197

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

3198

# deleted. For example,

3199

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

3200

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

3201

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

3202

# role in the binding.

3203

#

3204

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

3205

# identifier) representing a Google group that has been recently

3206

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

3207

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

3208

# recovered group retains the role in the binding.

3209

#

Bu Sun Kim

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

[diff] [blame]

3210

#

3211

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

3212

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

3213

#

Bu Sun Kim

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

[diff] [blame]

3214

"A String",

Bu Sun Kim

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

[diff] [blame]

3215

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3216

"role": "A String", # Role that is assigned to `members`.

3217

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3218

},

3219

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3220

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

3221

# prevent simultaneous updates of a policy from overwriting each other.

3222

# It is strongly suggested that systems make use of the `etag` in the

3223

# read-modify-write cycle to perform policy updates in order to avoid race

3224

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

3225

# systems are expected to put that etag in the request to `setIamPolicy` to

3226

# ensure that their change will be applied to the same version of the policy.

3227

#

3228

# **Important:** If you use IAM Conditions, you must include the `etag` field

3229

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

3230

# you to overwrite a version `3` policy with a version `1` policy, and all of

3231

# the conditions in the version `3` policy are lost.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

}</pre>

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3236

<code class="details" id="testIamPermissions">testIamPermissions(resource, body=None, x__xgafv=None)</code>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3237

<pre>Returns permissions that a caller has on the specified resource.

3238

If the resource does not exist, this will return an empty set of

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3239

permissions, not a `NOT_FOUND` error.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3240

3241

Note: This operation is designed to be used for building permission-aware

3242

UIs and command-line tools, not for authorization checking. This operation

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3243

may "fail open" without warning.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3244

3245

Args:

3246

resource: string, REQUIRED: The resource for which the policy detail is being requested.

3247

See the operation documentation for the appropriate value for this field. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3248

body: object, The request body.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3249

The object takes the form of:

3250

3251

{ # Request message for `TestIamPermissions` method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3252

"permissions": [ # The set of permissions to check for the `resource`. Permissions with

3253

# wildcards (such as '*' or 'storage.*') are not allowed. For more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3254

# information see

3255

# [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3256

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -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:

3267

3268

{ # Response message for `TestIamPermissions` method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3269

"permissions": [ # A subset of `TestPermissionsRequest.permissions` that the caller is

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3270

# allowed.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3271

"A String",

Bu Sun Kim