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.

Dan O'Meara

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

[diff] [blame]

124

#

Sai Cheemalapati

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

[diff] [blame]

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.

Bu Sun Kim

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

[diff] [blame]

128

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

Bu Sun Kim

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

[diff] [blame]

129

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

130

# arbitrary strings that you supply.

131

# For more information, see the documentation on

Bu Sun Kim

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

[diff] [blame]

132

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

133

"a_key": "A String",

Bu Sun Kim

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

[diff] [blame]

134

},

Bu Sun Kim

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

[diff] [blame]

135

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

136

#

137

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

138

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

139

# handle prediction requests that do not specify a version.

Bu Sun Kim

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

[diff] [blame]

140

#

Sai Cheemalapati

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

[diff] [blame]

141

# You can change the default version by calling

Dan O'Meara

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

[diff] [blame]

142

# projects.models.versions.setDefault.

Sai Cheemalapati

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

[diff] [blame]

143

#

144

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

145

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

146

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

Dan O'Meara

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

[diff] [blame]

147

# projects.models.versions.list.

Bu Sun Kim

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

[diff] [blame]

148

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

149

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

150

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

151

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

152

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

153

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

154

# on the selected number of nodes.

155

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

156

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

157

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

158

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

Dan O'Meara

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

[diff] [blame]

159

},

Bu Sun Kim

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

[diff] [blame]

160

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

161

#

162

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

163

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

164

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

165

#

166

# The following Python versions are available:

167

#

168

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

169

# later.

170

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

171

# from '1.4' to '1.14'.

172

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

173

# earlier.

174

#

175

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

176

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

177

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

178

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

Dan O'Meara

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

[diff] [blame]

179

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

180

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

181

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

182

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

Sai Cheemalapati

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

[diff] [blame]

183

#

Bu Sun Kim

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

[diff] [blame]

184

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

185

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

186

# If you specify this field, you must set

Dan O'Meara

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

[diff] [blame]

187

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

188

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

189

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

Bu Sun Kim

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

[diff] [blame]

190

#

191

# The following code sample provides the Predictor interface:

192

#

Bu Sun Kim

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

[diff] [blame]

193

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

Bu Sun Kim

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

[diff] [blame]

194

# class Predictor(object):

Bu Sun Kim

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

[diff] [blame]

195

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

Bu Sun Kim

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

[diff] [blame]

196

#

197

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

Bu Sun Kim

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

[diff] [blame]

198

# """Performs custom prediction.

Bu Sun Kim

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

[diff] [blame]

199

#

200

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

201

# been deserialized from JSON.

202

#

203

# Args:

204

# instances: A list of prediction input instances.

205

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

206

# fields on the predict request body.

207

#

208

# Returns:

209

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

210

# be JSON serializable.

Bu Sun Kim

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

[diff] [blame]

211

# """

Bu Sun Kim

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

[diff] [blame]

212

# raise NotImplementedError()

213

#

214

# @classmethod

215

# def from_path(cls, model_dir):

Bu Sun Kim

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

[diff] [blame]

216

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

Bu Sun Kim

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

[diff] [blame]

217

#

218

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

219

#

220

# Args:

221

# model_dir: The local directory that contains the exported model

222

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

227

# """

Bu Sun Kim

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

[diff] [blame]

228

# raise NotImplementedError()

Dan O'Meara

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

[diff] [blame]

229

# </pre>

Bu Sun Kim

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

[diff] [blame]

230

#

231

# Learn more about [the Predictor interface and custom prediction

232

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

Bu Sun Kim

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

[diff] [blame]

233

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

Bu Sun Kim

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

[diff] [blame]

234

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

235

# or [scikit-learn pipelines with custom

236

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

237

#

238

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

239

# Predictor class (see

240

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

241

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

242

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

243

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

244

#

245

# If you specify this field, you must also set

246

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

Bu Sun Kim

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

[diff] [blame]

247

"A String",

Bu Sun Kim

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

[diff] [blame]

248

],

Bu Sun Kim

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

[diff] [blame]

249

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

250

# Some explanation features require additional metadata to be loaded

251

# as part of the model payload.

252

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

253

# integrated gradients and sampled Shapley.

254

# [Learn more about feature

255

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

256

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

257

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

258

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

259

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

260

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

261

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

262

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

263

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

264

},

265

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

266

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

267

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

268

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

269

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

270

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

271

# Shapley values.

272

},

273

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

274

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

275

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

276

# Currently only implemented for models with natural image inputs.

277

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

278

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

279

# Currently only implemented for models with natural image inputs.

280

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

281

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

282

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

283

},

284

},

285

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

Bu Sun Kim

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

[diff] [blame]

286

# create the version. See the

287

# [guide to model

288

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

289

# information.

290

#

291

# When passing Version to

Dan O'Meara

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

[diff] [blame]

292

# projects.models.versions.create

Bu Sun Kim

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

[diff] [blame]

293

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

294

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

295

# this location is useful only as a historical record.

Bu Sun Kim

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

[diff] [blame]

296

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

297

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

298

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

Bu Sun Kim

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

[diff] [blame]

299

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

300

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

301

#

302

# Note that you cannot use AutoScaling if your version uses

303

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

304

# `manual_scaling`.

Bu Sun Kim

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

[diff] [blame]

305

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

306

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

307

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

308

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

309

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

310

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

311

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

312

# prediction performed.

313

#

314

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

315

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

316

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

317

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

318

# nodes are used.

319

#

320

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

321

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

322

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

323

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

324

# be incurred until traffic to the model resumes.

325

#

326

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

327

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

328

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

329

# Compute Engine machine type.

330

#

331

# Note that you cannot use AutoScaling if your version uses

332

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

333

# ManualScaling.

334

#

335

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

336

# update `min_nodes` for an existing version:

337

# <pre>

338

# update_body.json:

339

# {

Bu Sun Kim

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

[diff] [blame]

340

# 'autoScaling': {

341

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

346

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

Dan O'Meara

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

[diff] [blame]

347

# PATCH

348

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

349

# -d @./update_body.json

350

# </pre>

351

},

Bu Sun Kim

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

[diff] [blame]

352

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

353

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

354

# are arbitrary strings that you supply.

355

# For more information, see the documentation on

356

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

357

"a_key": "A String",

358

},

359

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

360

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

361

# projects.models.versions.patch

362

# request. Specifying it in a

363

# projects.models.versions.create

364

# request has no effect.

365

#

366

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

367

# Version.

368

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

369

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

370

# table. Logging is constrained by [BigQuery quotas and

371

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

372

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

373

# to serve predictions.

374

#

375

# If you are using [continuous

376

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

377

# specify this configuration manually. Setting up continuous evaluation

378

# automatically enables logging of request-response pairs.

Bu Sun Kim

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

[diff] [blame]

379

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

380

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

Dan O'Meara

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

[diff] [blame]

381

#

Bu Sun Kim

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

[diff] [blame]

382

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

Dan O'Meara

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

[diff] [blame]

383

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

384

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

385

#

386

# <table>

Bu Sun Kim

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

[diff] [blame]

387

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

388

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

Dan O'Meara

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

[diff] [blame]

389

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

390

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

391

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

392

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

393

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

394

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

395

# </table>

Bu Sun Kim

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

[diff] [blame]

396

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

397

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

398

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

399

},

400

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

401

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

402

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

403

# defaults to `mls1-c1-m2`.

404

#

405

# 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

426

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

427

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

428

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

429

#

430

# For more information, see the

431

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

432

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

433

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

434

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

435

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

436

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

437

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

438

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

439

# of the model to 1.4 or greater.

440

#

441

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

442

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

443

#

444

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

445

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

446

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

447

# for the framework.

448

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

449

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

450

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

451

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

452

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

453

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

454

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

455

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

456

# requests that do not specify a version.

457

#

458

# You can change the default version by calling

459

# projects.methods.versions.setDefault.

460

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

461

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

462

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

463

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

464

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

465

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

466

# [accelerators for online

467

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

468

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

469

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

Dan O'Meara

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

[diff] [blame]

470

},

Sai Cheemalapati

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

[diff] [blame]

471

},

Bu Sun Kim

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

[diff] [blame]

472

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

473

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

474

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

475

# However, they are helpful for debugging. Note that

476

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

477

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

478

# costs before enabling this option.

479

#

480

# Default is false.

481

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

482

# Only one region per model is supported.

483

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

484

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

485

# for AI Platform services.

486

# Note:

487

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

488

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

489

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

490

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

495

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

496

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

497

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

498

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

499

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

500

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

Bu Sun Kim

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

[diff] [blame]

501

#

Bu Sun Kim

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

[diff] [blame]

502

# Default is false.

Bu Sun Kim

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

[diff] [blame]

503

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

504

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

505

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

506

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

507

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

508

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

509

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

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.

525

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

526

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

527

# arbitrary strings that you supply.

528

# For more information, see the documentation on

529

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

530

"a_key": "A String",

531

},

532

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

533

#

534

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

535

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

536

# handle prediction requests that do not specify a version.

537

#

538

# You can change the default version by calling

539

# projects.models.versions.setDefault.

540

#

541

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

542

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

543

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

544

# projects.models.versions.list.

545

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

546

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

547

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

548

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

549

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

550

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

551

# on the selected number of nodes.

552

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

553

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

554

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

555

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

556

},

557

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

558

#

559

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

560

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

561

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

562

#

563

# The following Python versions are available:

564

#

565

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

566

# later.

567

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

568

# from '1.4' to '1.14'.

569

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

570

# earlier.

571

#

572

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

573

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

574

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

575

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

576

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

577

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

578

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

579

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

580

#

581

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

582

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

583

# If you specify this field, you must set

584

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

585

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

586

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

587

#

588

# The following code sample provides the Predictor interface:

589

#

590

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

591

# class Predictor(object):

592

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

593

#

594

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

595

# """Performs custom prediction.

596

#

597

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

598

# been deserialized from JSON.

599

#

600

# Args:

601

# instances: A list of prediction input instances.

602

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

603

# fields on the predict request body.

604

#

605

# Returns:

606

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

607

# be JSON serializable.

608

# """

609

# raise NotImplementedError()

610

#

611

# @classmethod

612

# def from_path(cls, model_dir):

613

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

614

#

615

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

616

#

617

# Args:

618

# model_dir: The local directory that contains the exported model

619

# file along with any additional files uploaded when creating the

# version resource.

#

# Returns:

# An instance implementing this Predictor class.

624

# """

625

# raise NotImplementedError()

626

# </pre>

627

#

628

# Learn more about [the Predictor interface and custom prediction

629

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

630

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

631

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

632

# or [scikit-learn pipelines with custom

633

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

634

#

635

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

636

# Predictor class (see

637

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

638

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

639

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

640

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

641

#

642

# If you specify this field, you must also set

643

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

644

"A String",

645

],

646

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

647

# Some explanation features require additional metadata to be loaded

648

# as part of the model payload.

649

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

650

# integrated gradients and sampled Shapley.

651

# [Learn more about feature

652

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

653

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

654

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

655

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

656

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

657

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

658

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

659

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

660

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

661

},

662

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

663

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

664

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

665

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

666

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

667

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

668

# Shapley values.

669

},

670

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

671

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

672

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

673

# Currently only implemented for models with natural image inputs.

674

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

675

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

676

# Currently only implemented for models with natural image inputs.

677

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

678

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

679

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

680

},

681

},

682

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

683

# create the version. See the

684

# [guide to model

685

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

686

# information.

687

#

688

# When passing Version to

689

# projects.models.versions.create

690

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

691

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

692

# this location is useful only as a historical record.

693

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

694

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

695

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

696

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

697

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

698

#

699

# Note that you cannot use AutoScaling if your version uses

700

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

701

# `manual_scaling`.

702

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

703

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

704

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

705

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

706

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

707

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

708

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

709

# prediction performed.

710

#

711

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

712

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

713

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

714

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

715

# nodes are used.

716

#

717

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

718

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

719

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

720

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

721

# be incurred until traffic to the model resumes.

722

#

723

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

724

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

725

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

726

# Compute Engine machine type.

727

#

728

# Note that you cannot use AutoScaling if your version uses

729

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

730

# ManualScaling.

731

#

732

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

733

# update `min_nodes` for an existing version:

# <pre>

# update_body.json:

# {

# 'autoScaling': {

# 'minNodes': 5

# }

# }

# </pre>

# HTTP request:

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

744

# PATCH

745

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

746

# -d @./update_body.json

747

# </pre>

748

},

749

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

750

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

751

# are arbitrary strings that you supply.

752

# For more information, see the documentation on

753

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

754

"a_key": "A String",

755

},

756

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

757

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

758

# projects.models.versions.patch

759

# request. Specifying it in a

760

# projects.models.versions.create

761

# request has no effect.

762

#

763

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

764

# Version.

765

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

766

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

767

# table. Logging is constrained by [BigQuery quotas and

768

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

769

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

770

# to serve predictions.

771

#

772

# If you are using [continuous

773

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

774

# specify this configuration manually. Setting up continuous evaluation

775

# automatically enables logging of request-response pairs.

776

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

777

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

778

#

779

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

780

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

781

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

782

#

783

# <table>

784

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

785

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

786

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

787

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

788

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

789

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

790

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

791

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

792

# </table>

793

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

794

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

795

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

796

},

797

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

798

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

799

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

800

# defaults to `mls1-c1-m2`.

801

#

802

# 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

823

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

824

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

825

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

826

#

827

# For more information, see the

828

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

829

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

830

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

831

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

832

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

833

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

834

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

835

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

836

# of the model to 1.4 or greater.

837

#

838

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

839

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

840

#

841

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

842

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

843

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

844

# for the framework.

845

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

846

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

847

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

848

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

849

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

850

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

851

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

852

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

853

# requests that do not specify a version.

854

#

855

# You can change the default version by calling

856

# projects.methods.versions.setDefault.

857

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

858

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

859

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

860

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

861

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

862

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

863

# [accelerators for online

864

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

865

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

866

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

867

},

868

},

869

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

870

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

871

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

872

# However, they are helpful for debugging. Note that

873

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

874

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

875

# costs before enabling this option.

876

#

877

# Default is false.

878

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

879

# Only one region per model is supported.

880

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

881

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

882

# for AI Platform services.

883

# Note:

884

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

885

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

886

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

887

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

892

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

893

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

894

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

895

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

896

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

897

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

898

#

899

# Default is false.

900

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

901

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

902

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

903

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

904

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

905

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

906

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

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

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

Sai Cheemalapati

4ba8c23

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

[diff] [blame]

931

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

932

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

933

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

934

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

935

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

936

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

937

# `TakeSnapshotResponse`.

Bu Sun Kim

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

[diff] [blame]

938

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

Sai Cheemalapati

4ba8c23

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

[diff] [blame]

939

},

Bu Sun Kim

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

[diff] [blame]

940

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

941

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

Bu Sun Kim

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

[diff] [blame]

942

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

Bu Sun Kim

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

[diff] [blame]

943

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

944

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

945

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

946

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

947

#

948

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

949

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

950

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

951

# message types for APIs to use.

952

{

953

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

954

},

955

],

956

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

957

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

958

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

959

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

960

},

961

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

962

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

963

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

964

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

965

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

966

},

967

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

968

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

969

# available.

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.

Dan O'Meara

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

[diff] [blame]

990

#

Bu Sun Kim

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

[diff] [blame]

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

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

995

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

996

# arbitrary strings that you supply.

Bu Sun Kim

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

[diff] [blame]

997

# For more information, see the documentation on

Bu Sun Kim

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

[diff] [blame]

998

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

999

"a_key": "A String",

Bu Sun Kim

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

[diff] [blame]

1000

},

Bu Sun Kim

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

[diff] [blame]

1001

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

Bu Sun Kim

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

[diff] [blame]

1002

#

Bu Sun Kim

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

[diff] [blame]

1003

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

1004

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

1005

# handle prediction requests that do not specify a version.

Bu Sun Kim

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

[diff] [blame]

1006

#

Bu Sun Kim

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

[diff] [blame]

1007

# You can change the default version by calling

1008

# projects.models.versions.setDefault.

Bu Sun Kim

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

[diff] [blame]

1009

#

Bu Sun Kim

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

[diff] [blame]

1010

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

1011

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

1012

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

1013

# projects.models.versions.list.

1014

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

1015

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

1016

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

1017

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

1018

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

1019

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

1020

# on the selected number of nodes.

1021

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

1022

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

1023

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

1024

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

1025

},

1026

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

1027

#

1028

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

1029

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

1030

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

1031

#

1032

# The following Python versions are available:

1033

#

1034

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

1035

# later.

1036

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

1037

# from '1.4' to '1.14'.

1038

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

1039

# earlier.

1040

#

1041

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

1042

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

1043

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

1044

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

1045

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

1046

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

1047

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

1048

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

1049

#

1050

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

1051

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

1052

# If you specify this field, you must set

1053

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

1054

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

1055

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

1056

#

1057

# The following code sample provides the Predictor interface:

1058

#

1059

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

1060

# class Predictor(object):

1061

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

1062

#

1063

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

1064

# """Performs custom prediction.

1065

#

1066

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

1067

# been deserialized from JSON.

1068

#

1069

# Args:

1070

# instances: A list of prediction input instances.

1071

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

1072

# fields on the predict request body.

1073

#

1074

# Returns:

1075

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

1076

# be JSON serializable.

1077

# """

1078

# raise NotImplementedError()

1079

#

1080

# @classmethod

1081

# def from_path(cls, model_dir):

1082

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

1083

#

1084

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

1085

#

1086

# Args:

1087

# model_dir: The local directory that contains the exported model

1088

# file along with any additional files uploaded when creating the

# version resource.

#

# Returns:

# An instance implementing this Predictor class.

1093

# """

1094

# raise NotImplementedError()

1095

# </pre>

1096

#

1097

# Learn more about [the Predictor interface and custom prediction

1098

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

1099

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

1100

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

1101

# or [scikit-learn pipelines with custom

1102

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

1103

#

1104

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

1105

# Predictor class (see

1106

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

1107

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

1108

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

1109

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

1110

#

1111

# If you specify this field, you must also set

1112

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

1113

"A String",

1114

],

1115

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

1116

# Some explanation features require additional metadata to be loaded

1117

# as part of the model payload.

1118

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

1119

# integrated gradients and sampled Shapley.

1120

# [Learn more about feature

1121

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

1122

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

1123

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

1124

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

1125

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

1126

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

1127

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

1128

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

1129

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

1130

},

1131

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

1132

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

1133

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

1134

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

1135

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

1136

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

1137

# Shapley values.

1138

},

1139

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

1140

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

1141

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

1142

# Currently only implemented for models with natural image inputs.

1143

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

1144

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

1145

# Currently only implemented for models with natural image inputs.

1146

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

1147

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

1148

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

1149

},

1150

},

1151

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

1152

# create the version. See the

1153

# [guide to model

1154

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

1155

# information.

1156

#

1157

# When passing Version to

1158

# projects.models.versions.create

1159

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

1160

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

1161

# this location is useful only as a historical record.

1162

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

1163

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

1164

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

1165

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

1166

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

1167

#

1168

# Note that you cannot use AutoScaling if your version uses

1169

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

1170

# `manual_scaling`.

1171

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

1172

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

1173

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

1174

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

1175

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

1176

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

1177

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

1178

# prediction performed.

1179

#

1180

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

1181

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

1182

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

1183

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

1184

# nodes are used.

1185

#

1186

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

1187

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

1188

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

1189

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

1190

# be incurred until traffic to the model resumes.

1191

#

1192

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

1193

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

1194

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

1195

# Compute Engine machine type.

1196

#

1197

# Note that you cannot use AutoScaling if your version uses

1198

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

1199

# ManualScaling.

1200

#

1201

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

1202

# update `min_nodes` for an existing version:

# <pre>

# update_body.json:

# {

# 'autoScaling': {

# 'minNodes': 5

# }

# }

# </pre>

# HTTP request:

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

1213

# PATCH

1214

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

1215

# -d @./update_body.json

1216

# </pre>

1217

},

1218

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

1219

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

1220

# are arbitrary strings that you supply.

1221

# For more information, see the documentation on

1222

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

1223

"a_key": "A String",

1224

},

1225

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

1226

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

1227

# projects.models.versions.patch

1228

# request. Specifying it in a

1229

# projects.models.versions.create

1230

# request has no effect.

1231

#

1232

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

1233

# Version.

1234

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

1235

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

1236

# table. Logging is constrained by [BigQuery quotas and

1237

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

1238

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

1239

# to serve predictions.

1240

#

1241

# If you are using [continuous

1242

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

1243

# specify this configuration manually. Setting up continuous evaluation

1244

# automatically enables logging of request-response pairs.

1245

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

1246

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

1247

#

1248

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

1249

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

1250

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

1251

#

1252

# <table>

1253

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

1254

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

1255

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

1256

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

1257

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

1258

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

1259

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

1260

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

1261

# </table>

1262

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

1263

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

1264

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

1265

},

1266

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

1267

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

1268

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

1269

# defaults to `mls1-c1-m2`.

1270

#

1271

# 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

1292

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

1293

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

1294

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

1295

#

1296

# For more information, see the

1297

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

1298

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

1299

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

1300

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

1301

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

1302

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

1303

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

1304

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

1305

# of the model to 1.4 or greater.

1306

#

1307

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

1308

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

1309

#

1310

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

1311

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

1312

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

1313

# for the framework.

1314

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

1315

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

1316

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

1317

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

1318

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

1319

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

1320

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

1321

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

1322

# requests that do not specify a version.

1323

#

1324

# You can change the default version by calling

1325

# projects.methods.versions.setDefault.

1326

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

1327

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

1328

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

1329

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

1330

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

1331

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

1332

# [accelerators for online

1333

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

1334

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

1335

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

1336

},

1337

},

1338

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

1339

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

1340

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

1341

# However, they are helpful for debugging. Note that

1342

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

1343

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

1344

# costs before enabling this option.

Bu Sun Kim

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

[diff] [blame]

1345

#

Bu Sun Kim

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

[diff] [blame]

1346

# Default is false.

1347

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

1348

# Only one region per model is supported.

1349

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

1350

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

1351

# for AI Platform services.

1352

# Note:

1353

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

1354

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

1355

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

1356

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

1357

# this field.

1358

"A String",

Sai Cheemalapati

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

[diff] [blame]

1359

],

Bu Sun Kim

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

[diff] [blame]

1360

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

1361

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

1362

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

1363

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

1364

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

1365

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

1366

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

1367

#

1368

# Default is false.

1369

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

1370

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

1371

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

1372

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

Bu Sun Kim

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

[diff] [blame]

1373

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

1374

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

Bu Sun Kim

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

[diff] [blame]

1375

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

Bu Sun Kim

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

[diff] [blame]

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

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

1476

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

1477

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

1478

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

1479

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

1480

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

1481

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

1482

#

1483

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

1484

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

1485

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

1486

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

1487

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

1488

#

1489

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

1490

# are rejected.

1491

#

1492

# Any operation that affects conditional role bindings must specify version

1493

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

1494

#

1495

# * Getting a policy that includes a conditional role binding

1496

# * Adding a conditional role binding to a policy

1497

# * Changing a conditional role binding in a policy

1498

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

1499

# that includes conditions

1500

#

1501

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

1502

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

1503

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

1504

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

1505

#

1506

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

1507

# specify any valid version or leave the field unset.

1508

#

1509

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

1510

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

1511

"auditConfigs": [ # Specifies cloud audit logging configuration for this policy.

1512

{ # Specifies the audit configuration for a service.

1513

# The configuration determines which permission types are logged, and what

1514

# identities, if any, are exempted from logging.

1515

# An AuditConfig must have one or more AuditLogConfigs.

1516

#

1517

# If there are AuditConfigs for both `allServices` and a specific service,

1518

# the union of the two AuditConfigs is used for that service: the log_types

1519

# specified in each AuditConfig are enabled, and the exempted_members in each

1520

# AuditLogConfig are exempted.

1521

#

1522

# Example Policy with multiple AuditConfigs:

#

# {

# "audit_configs": [

# {

# "service": "allServices"

1528

# "audit_log_configs": [

1529

# {

1530

# "log_type": "DATA_READ",

1531

# "exempted_members": [

1532

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

1537

# },

1538

# {

1539

# "log_type": "ADMIN_READ",

# }

# ]

# },

# {

# "service": "sampleservice.googleapis.com"

1545

# "audit_log_configs": [

1546

# {

1547

# "log_type": "DATA_READ",

1548

# },

1549

# {

1550

# "log_type": "DATA_WRITE",

1551

# "exempted_members": [

1552

# "user:aliya@example.com"

# ]

# }

# ]

# }

# ]

# }

#

# For sampleservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ

1561

# logging. It also exempts jose@example.com from DATA_READ logging, and

1562

# aliya@example.com from DATA_WRITE logging.

1563

"service": "A String", # Specifies a service that will be enabled for audit logging.

1564

# For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.

1565

# `allServices` is a special value that covers all services.

1566

"auditLogConfigs": [ # The configuration for logging of each type of permission.

1567

{ # Provides the configuration for logging a type of permissions.

# Example:

#

# {

# "audit_log_configs": [

1572

# {

1573

# "log_type": "DATA_READ",

1574

# "exempted_members": [

1575

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

# }

# ]

# }

#

# This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting

1585

# jose@example.com from DATA_READ logging.

1586

"exemptedMembers": [ # Specifies the identities that do not cause logging for this type of

1587

# permission.

1588

# Follows the same format of Binding.members.

1589

"A String",

1590

],

1591

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

1597

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

1598

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

Bu Sun Kim

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

[diff] [blame]

1599

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

Bu Sun Kim

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

[diff] [blame]

1600

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

1601

#

1602

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

1603

# current request.

1604

#

1605

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

1606

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

1607

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

1608

#

1609

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

1610

# [IAM

1611

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

1612

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

1613

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

1614

#

1615

# Example (Comparison):

1616

#

1617

# title: "Summary size limit"

1618

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

1619

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

1620

#

1621

# Example (Equality):

1622

#

1623

# title: "Requestor is owner"

1624

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

1625

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

#

# Example (Logic):

#

# title: "Public documents"

1630

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

1631

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

1632

#

1633

# Example (Data Manipulation):

1634

#

1635

# title: "Notification string"

1636

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

1637

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

1638

#

1639

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

1640

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

1641

# documentation for additional information.

1642

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

1643

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

1644

# expression.

1645

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

1646

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

1647

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

1648

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

1649

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

1650

# syntax.

1651

},

1652

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

Bu Sun Kim

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

[diff] [blame]

1653

# `members` can have the following values:

1654

#

1655

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

1656

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

1657

#

1658

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

1659

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

1660

#

1661

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

Dan O'Meara

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

[diff] [blame]

1662

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

Bu Sun Kim

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

[diff] [blame]

1663

#

1664

#

1665

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

1666

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

1667

#

1668

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

1669

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

1670

#

Dan O'Meara

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

[diff] [blame]

1671

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

1672

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

1673

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

1674

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

1675

# retains the role in the binding.

1676

#

1677

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

1678

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

1679

# deleted. For example,

1680

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

1681

# If the service account is undeleted, this value reverts to

1682

# `serviceAccount:{emailid}` and the undeleted service account retains the

1683

# role in the binding.

1684

#

1685

# * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique

1686

# identifier) representing a Google group that has been recently

1687

# deleted. For example, `admins@example.com?uid=123456789012345678901`. If

1688

# the group is recovered, this value reverts to `group:{emailid}` and the

1689

# recovered group retains the role in the binding.

1690

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1691

#

1692

# * `domain:{domain}`: The G Suite domain (primary) that represents all the

1693

# users of that domain. For example, `google.com` or `example.com`.

1694

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1695

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1696

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1697

"role": "A String", # Role that is assigned to `members`.

1698

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1699

},

1700

],

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-20 12:08:20 -0700

[diff] [blame]

1735

"models": [ # The list of models.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1736

{ # Represents a machine learning solution.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1737

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1738

# A model can have multiple versions, each of which is a deployed, trained

1739

# model ready to receive prediction requests. The model itself is just a

1740

# container.

1741

"labels": { # Optional. One or more labels that you can add, to organize your models.

1742

# Each label is a key-value pair, where both the key and the value are

1743

# arbitrary strings that you supply.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1744

# For more information, see the documentation on

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1745

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

1746

"a_key": "A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1747

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1748

"name": "A String", # Required. The name specified for the model when it was created.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1749

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1750

# The model name must be unique within the project it is created in.

1751

"defaultVersion": { # Represents a version of the model. # Output only. The default version of the model. This version will be used to

1752

# handle prediction requests that do not specify a version.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1753

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1754

# You can change the default version by calling

1755

# projects.models.versions.setDefault.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1756

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1757

# Each version is a trained model deployed in the cloud, ready to handle

1758

# prediction requests. A model can have multiple versions. You can get

1759

# information about all of the versions of a given model by calling

1760

# projects.models.versions.list.

1761

"state": "A String", # Output only. The state of a version.

1762

"manualScaling": { # Options for manually scaling a model. # Manually select the number of nodes to use for serving the

1763

# model. You should generally use `auto_scaling` with an appropriate

1764

# `min_nodes` instead, but this option is available if you want more

1765

# predictable billing. Beware that latency and error rates will increase

1766

# if the traffic exceeds that capability of the system to serve it based

1767

# on the selected number of nodes.

1768

"nodes": 42, # The number of nodes to allocate for this model. These nodes are always up,

1769

# starting from the time the model is deployed, so the cost of operating

1770

# this model will be proportional to `nodes` * number of hours since

1771

# last billing cycle plus the cost for each prediction performed.

1772

},

1773

"name": "A String", # Required. The name specified for the version when it was created.

1774

#

1775

# The version name must be unique within the model it is created in.

1776

"serviceAccount": "A String", # Optional. Specifies the service account for resource access control.

1777

"pythonVersion": "A String", # Required. The version of Python used in prediction.

1778

#

1779

# The following Python versions are available:

1780

#

1781

# * Python '3.7' is available when `runtime_version` is set to '1.15' or

1782

# later.

1783

# * Python '3.5' is available when `runtime_version` is set to a version

1784

# from '1.4' to '1.14'.

1785

# * Python '2.7' is available when `runtime_version` is set to '1.15' or

1786

# earlier.

1787

#

1788

# Read more about the Python versions available for [each runtime

1789

# version](/ml-engine/docs/runtime-version-list).

1790

"lastUseTime": "A String", # Output only. The time the version was last used for prediction.

1791

"predictionClass": "A String", # Optional. The fully qualified name

1792

# (<var>module_name</var>.<var>class_name</var>) of a class that implements

1793

# the Predictor interface described in this reference field. The module

1794

# containing this class should be included in a package provided to the

1795

# [`packageUris` field](#Version.FIELDS.package_uris).

1796

#

1797

# Specify this field if and only if you are deploying a [custom prediction

1798

# routine (beta)](/ml-engine/docs/tensorflow/custom-prediction-routines).

1799

# If you specify this field, you must set

1800

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater and

1801

# you must set `machineType` to a [legacy (MLS1)

1802

# machine type](/ml-engine/docs/machine-types-online-prediction).

1803

#

1804

# The following code sample provides the Predictor interface:

1805

#

1806

# <pre style="max-width: 626px;">

1807

# class Predictor(object):

1808

# """Interface for constructing custom predictors."""

1809

#

1810

# def predict(self, instances, **kwargs):

1811

# """Performs custom prediction.

1812

#

1813

# Instances are the decoded values from the request. They have already

1814

# been deserialized from JSON.

1815

#

1816

# Args:

1817

# instances: A list of prediction input instances.

1818

# **kwargs: A dictionary of keyword args provided as additional

1819

# fields on the predict request body.

1820

#

1821

# Returns:

1822

# A list of outputs containing the prediction results. This list must

1823

# be JSON serializable.

1824

# """

1825

# raise NotImplementedError()

1826

#

1827

# @classmethod

1828

# def from_path(cls, model_dir):

1829

# """Creates an instance of Predictor using the given path.

1830

#

1831

# Loading of the predictor should be done in this method.

1832

#

1833

# Args:

1834

# model_dir: The local directory that contains the exported model

1835

# file along with any additional files uploaded when creating the

# version resource.

#

# Returns:

# An instance implementing this Predictor class.

1840

# """

1841

# raise NotImplementedError()

1842

# </pre>

1843

#

1844

# Learn more about [the Predictor interface and custom prediction

1845

# routines](/ml-engine/docs/tensorflow/custom-prediction-routines).

1846

"packageUris": [ # Optional. Cloud Storage paths (`gs://…`) of packages for [custom

1847

# prediction routines](/ml-engine/docs/tensorflow/custom-prediction-routines)

1848

# or [scikit-learn pipelines with custom

1849

# code](/ml-engine/docs/scikit/exporting-for-prediction#custom-pipeline-code).

1850

#

1851

# For a custom prediction routine, one of these packages must contain your

1852

# Predictor class (see

1853

# [`predictionClass`](#Version.FIELDS.prediction_class)). Additionally,

1854

# include any dependencies used by your Predictor or scikit-learn pipeline

1855

# uses that are not already included in your selected [runtime

1856

# version](/ml-engine/docs/tensorflow/runtime-version-list).

1857

#

1858

# If you specify this field, you must also set

1859

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater.

1860

"A String",

1861

],

1862

"explanationConfig": { # Message holding configuration options for explaining model predictions. # Optional. Configures explainability features on the model's version.

1863

# Some explanation features require additional metadata to be loaded

1864

# as part of the model payload.

1865

# There are two feature attribution methods supported for TensorFlow models:

1866

# integrated gradients and sampled Shapley.

1867

# [Learn more about feature

1868

# attributions.](/ai-platform/prediction/docs/ai-explanations/overview)

1869

"integratedGradientsAttribution": { # Attributes credit by computing the Aumann-Shapley value taking advantage # Attributes credit by computing the Aumann-Shapley value taking advantage

1870

# of the model's fully differentiable structure. Refer to this paper for

1871

# more details: http://proceedings.mlr.press/v70/sundararajan17a.html

1872

# of the model's fully differentiable structure. Refer to this paper for

1873

# more details: https://arxiv.org/abs/1703.01365

1874

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

1875

# A good value to start is 50 and gradually increase until the

1876

# sum to diff property is met within the desired error range.

1877

},

1878

"sampledShapleyAttribution": { # An attribution method that approximates Shapley values for features that # An attribution method that approximates Shapley values for features that

1879

# contribute to the label being predicted. A sampling strategy is used to

1880

# approximate the value rather than considering all subsets of features.

1881

# contribute to the label being predicted. A sampling strategy is used to

1882

# approximate the value rather than considering all subsets of features.

1883

"numPaths": 42, # The number of feature permutations to consider when approximating the

1884

# Shapley values.

1885

},

1886

"xraiAttribution": { # Attributes credit by computing the XRAI taking advantage # Attributes credit by computing the XRAI taking advantage

1887

# of the model's fully differentiable structure. Refer to this paper for

1888

# more details: https://arxiv.org/abs/1906.02825

1889

# Currently only implemented for models with natural image inputs.

1890

# of the model's fully differentiable structure. Refer to this paper for

1891

# more details: https://arxiv.org/abs/1906.02825

1892

# Currently only implemented for models with natural image inputs.

1893

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

1894

# A good value to start is 50 and gradually increase until the

1895

# sum to diff property is met within the desired error range.

1896

},

1897

},

1898

"deploymentUri": "A String", # Required. The Cloud Storage location of the trained model used to

1899

# create the version. See the

1900

# [guide to model

1901

# deployment](/ml-engine/docs/tensorflow/deploying-models) for more

1902

# information.

1903

#

1904

# When passing Version to

1905

# projects.models.versions.create

1906

# the model service uses the specified location as the source of the model.

1907

# Once deployed, the model version is hosted by the prediction service, so

1908

# this location is useful only as a historical record.

1909

# The total number of model files can't exceed 1000.

1910

"autoScaling": { # Options for automatically scaling a model. # Automatically scale the number of nodes used to serve the model in

1911

# response to increases and decreases in traffic. Care should be

1912

# taken to ramp up traffic according to the model's ability to scale

1913

# or you will start seeing increases in latency and 429 response codes.

1914

#

1915

# Note that you cannot use AutoScaling if your version uses

1916

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use specify

1917

# `manual_scaling`.

1918

"minNodes": 42, # Optional. The minimum number of nodes to allocate for this model. These

1919

# nodes are always up, starting from the time the model is deployed.

1920

# Therefore, the cost of operating this model will be at least

1921

# `rate` * `min_nodes` * number of hours since last billing cycle,

1922

# where `rate` is the cost per node-hour as documented in the

1923

# [pricing guide](/ml-engine/docs/pricing),

1924

# even if no predictions are performed. There is additional cost for each

1925

# prediction performed.

1926

#

1927

# Unlike manual scaling, if the load gets too heavy for the nodes

1928

# that are up, the service will automatically add nodes to handle the

1929

# increased load as well as scale back as traffic drops, always maintaining

1930

# at least `min_nodes`. You will be charged for the time in which additional

1931

# nodes are used.

1932

#

1933

# If `min_nodes` is not specified and AutoScaling is used with a [legacy

1934

# (MLS1) machine type](/ml-engine/docs/machine-types-online-prediction),

1935

# `min_nodes` defaults to 0, in which case, when traffic to a model stops

1936

# (and after a cool-down period), nodes will be shut down and no charges will

1937

# be incurred until traffic to the model resumes.

1938

#

1939

# If `min_nodes` is not specified and AutoScaling is used with a [Compute

1940

# Engine (N1) machine type](/ml-engine/docs/machine-types-online-prediction),

1941

# `min_nodes` defaults to 1. `min_nodes` must be at least 1 for use with a

1942

# Compute Engine machine type.

1943

#

1944

# Note that you cannot use AutoScaling if your version uses

1945

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use

1946

# ManualScaling.

1947

#

1948

# You can set `min_nodes` when creating the model version, and you can also

1949

# update `min_nodes` for an existing version:

# <pre>

# update_body.json:

# {

# 'autoScaling': {

# 'minNodes': 5

# }

# }

# </pre>

# HTTP request:

# <pre style="max-width: 626px;">

1960

# PATCH

1961

# https://ml.googleapis.com/v1/{name=projects/*/models/*/versions/*}?update_mask=autoScaling.minNodes

1962

# -d @./update_body.json

1963

# </pre>

1964

},

1965

"labels": { # Optional. One or more labels that you can add, to organize your model

1966

# versions. Each label is a key-value pair, where both the key and the value

1967

# are arbitrary strings that you supply.

1968

# For more information, see the documentation on

1969

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

1970

"a_key": "A String",

1971

},

1972

"createTime": "A String", # Output only. The time the version was created.

1973

"requestLoggingConfig": { # Configuration for logging request-response pairs to a BigQuery table. # Optional. *Only* specify this field in a

1974

# projects.models.versions.patch

1975

# request. Specifying it in a

1976

# projects.models.versions.create

1977

# request has no effect.

1978

#

1979

# Configures the request-response pair logging on predictions from this

1980

# Version.

1981

# Online prediction requests to a model version and the responses to these

1982

# requests are converted to raw strings and saved to the specified BigQuery

1983

# table. Logging is constrained by [BigQuery quotas and

1984

# limits](/bigquery/quotas). If your project exceeds BigQuery quotas or limits,

1985

# AI Platform Prediction does not log request-response pairs, but it continues

1986

# to serve predictions.

1987

#

1988

# If you are using [continuous

1989

# evaluation](/ml-engine/docs/continuous-evaluation/), you do not need to

1990

# specify this configuration manually. Setting up continuous evaluation

1991

# automatically enables logging of request-response pairs.

1992

"bigqueryTableName": "A String", # Required. Fully qualified BigQuery table name in the following format:

1993

# "<var>project_id</var>.<var>dataset_name</var>.<var>table_name</var>"

1994

#

1995

# The specified table must already exist, and the "Cloud ML Service Agent"

1996

# for your project must have permission to write to it. The table must have

1997

# the following [schema](/bigquery/docs/schemas):

1998

#

1999

# <table>

2000

# <tr><th>Field name</th><th style="display: table-cell">Type</th>

2001

# <th style="display: table-cell">Mode</th></tr>

2002

# <tr><td>model</td><td>STRING</td><td>REQUIRED</td></tr>

2003

# <tr><td>model_version</td><td>STRING</td><td>REQUIRED</td></tr>

2004

# <tr><td>time</td><td>TIMESTAMP</td><td>REQUIRED</td></tr>

2005

# <tr><td>raw_data</td><td>STRING</td><td>REQUIRED</td></tr>

2006

# <tr><td>raw_prediction</td><td>STRING</td><td>NULLABLE</td></tr>

2007

# <tr><td>groundtruth</td><td>STRING</td><td>NULLABLE</td></tr>

2008

# </table>

2009

"samplingPercentage": 3.14, # Percentage of requests to be logged, expressed as a fraction from 0 to 1.

2010

# For example, if you want to log 10% of requests, enter `0.1`. The sampling

2011

# window is the lifetime of the model version. Defaults to 0.

2012

},

2013

"errorMessage": "A String", # Output only. The details of a failure or a cancellation.

2014

"machineType": "A String", # Optional. The type of machine on which to serve the model. Currently only

2015

# applies to online prediction service. If this field is not specified, it

2016

# defaults to `mls1-c1-m2`.

2017

#

2018

# 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

2039

# in beta. Learn more about the [differences between machine

2040

# types](/ml-engine/docs/machine-types-online-prediction).

2041

"runtimeVersion": "A String", # Required. The AI Platform runtime version to use for this deployment.

2042

#

2043

# For more information, see the

2044

# [runtime version list](/ml-engine/docs/runtime-version-list) and

2045

# [how to manage runtime versions](/ml-engine/docs/versioning).

2046

"description": "A String", # Optional. The description specified for the version when it was created.

2047

"framework": "A String", # Optional. The machine learning framework AI Platform uses to train

2048

# this version of the model. Valid values are `TENSORFLOW`, `SCIKIT_LEARN`,

2049

# `XGBOOST`. If you do not specify a framework, AI Platform

2050

# will analyze files in the deployment_uri to determine a framework. If you

2051

# choose `SCIKIT_LEARN` or `XGBOOST`, you must also set the runtime version

2052

# of the model to 1.4 or greater.

2053

#

2054

# Do **not** specify a framework if you're deploying a [custom

2055

# prediction routine](/ml-engine/docs/tensorflow/custom-prediction-routines).

2056

#

2057

# If you specify a [Compute Engine (N1) machine

2058

# type](/ml-engine/docs/machine-types-online-prediction) in the

2059

# `machineType` field, you must specify `TENSORFLOW`

2060

# for the framework.

2061

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

2062

# prevent simultaneous updates of a model from overwriting each other.

2063

# It is strongly suggested that systems make use of the `etag` in the

2064

# read-modify-write cycle to perform model updates in order to avoid race

2065

# conditions: An `etag` is returned in the response to `GetVersion`, and

2066

# systems are expected to put that etag in the request to `UpdateVersion` to

2067

# ensure that their change will be applied to the model as intended.

2068

"isDefault": True or False, # Output only. If true, this version will be used to handle prediction

2069

# requests that do not specify a version.

2070

#

2071

# You can change the default version by calling

2072

# projects.methods.versions.setDefault.

2073

"acceleratorConfig": { # Represents a hardware accelerator request config. # Optional. Accelerator config for using GPUs for online prediction (beta).

2074

# Only specify this field if you have specified a Compute Engine (N1) machine

2075

# type in the `machineType` field. Learn more about [using GPUs for online

2076

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

2077

# Note that the AcceleratorConfig can be used in both Jobs and Versions.

2078

# Learn more about [accelerators for training](/ml-engine/docs/using-gpus) and

2079

# [accelerators for online

2080

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

2081

"count": "A String", # The number of accelerators to attach to each machine running the job.

2082

"type": "A String", # The type of accelerator to use.

2083

},

2084

},

2085

"onlinePredictionConsoleLogging": True or False, # Optional. If true, online prediction nodes send `stderr` and `stdout`

2086

# streams to Stackdriver Logging. These can be more verbose than the standard

2087

# access logs (see `onlinePredictionLogging`) and can incur higher cost.

2088

# However, they are helpful for debugging. Note that

2089

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

2090

# your project receives prediction requests at a high QPS. Estimate your

2091

# costs before enabling this option.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2092

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2093

# Default is false.

2094

"regions": [ # Optional. The list of regions where the model is going to be deployed.

2095

# Only one region per model is supported.

2096

# Defaults to 'us-central1' if nothing is set.

2097

# See the <a href="/ml-engine/docs/tensorflow/regions">available regions</a>

2098

# for AI Platform services.

2099

# Note:

2100

# * No matter where a model is deployed, it can always be accessed by

2101

# users from anywhere, both for online and batch prediction.

2102

# * The region for a batch prediction job is set by the region field when

2103

# submitting the batch prediction job and does not take its value from

2104

# this field.

2105

"A String",

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2106

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2107

"description": "A String", # Optional. The description specified for the model when it was created.

2108

"onlinePredictionLogging": True or False, # Optional. If true, online prediction access logs are sent to StackDriver

2109

# Logging. These logs are like standard server access logs, containing

2110

# information like timestamp and latency for each request. Note that

2111

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

2112

# your project receives prediction requests at a high queries per second rate

2113

# (QPS). Estimate your costs before enabling this option.

2114

#

2115

# Default is false.

2116

"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]

2117

# prevent simultaneous updates of a model from overwriting each other.

2118

# It is strongly suggested that systems make use of the `etag` in the

2119

# read-modify-write cycle to perform model updates in order to avoid race

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2120

# conditions: An `etag` is returned in the response to `GetModel`, and

2121

# systems are expected to put that etag in the request to `UpdateModel` to

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2122

# ensure that their change will be applied to the model as intended.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2123

},

2124

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2125

"nextPageToken": "A String", # Optional. Pass this token as the `page_token` field of the request for a

2126

# subsequent call.

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.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2157

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

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

"labels": { # Optional. One or more labels that you can add, to organize your models.

2162

# Each label is a key-value pair, where both the key and the value are

2163

# arbitrary strings that you supply.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2164

# For more information, see the documentation on

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2165

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

2166

"a_key": "A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2167

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2168

"name": "A String", # Required. The name specified for the model when it was created.

2169

#

2170

# The model name must be unique within the project it is created in.

2171

"defaultVersion": { # Represents a version of the model. # Output only. The default version of the model. This version will be used to

2172

# handle prediction requests that do not specify a version.

2173

#

2174

# You can change the default version by calling

2175

# projects.models.versions.setDefault.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2176

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2177

# Each version is a trained model deployed in the cloud, ready to handle

2178

# prediction requests. A model can have multiple versions. You can get

2179

# information about all of the versions of a given model by calling

2180

# projects.models.versions.list.

2181

"state": "A String", # Output only. The state of a version.

2182

"manualScaling": { # Options for manually scaling a model. # Manually select the number of nodes to use for serving the

2183

# model. You should generally use `auto_scaling` with an appropriate

2184

# `min_nodes` instead, but this option is available if you want more

2185

# predictable billing. Beware that latency and error rates will increase

2186

# if the traffic exceeds that capability of the system to serve it based

2187

# on the selected number of nodes.

2188

"nodes": 42, # The number of nodes to allocate for this model. These nodes are always up,

2189

# starting from the time the model is deployed, so the cost of operating

2190

# this model will be proportional to `nodes` * number of hours since

2191

# last billing cycle plus the cost for each prediction performed.

2192

},

2193

"name": "A String", # Required. The name specified for the version when it was created.

2194

#

2195

# The version name must be unique within the model it is created in.

2196

"serviceAccount": "A String", # Optional. Specifies the service account for resource access control.

2197

"pythonVersion": "A String", # Required. The version of Python used in prediction.

2198

#

2199

# The following Python versions are available:

2200

#

2201

# * Python '3.7' is available when `runtime_version` is set to '1.15' or

2202

# later.

2203

# * Python '3.5' is available when `runtime_version` is set to a version

2204

# from '1.4' to '1.14'.

2205

# * Python '2.7' is available when `runtime_version` is set to '1.15' or

2206

# earlier.

2207

#

2208

# Read more about the Python versions available for [each runtime

2209

# version](/ml-engine/docs/runtime-version-list).

2210

"lastUseTime": "A String", # Output only. The time the version was last used for prediction.

2211

"predictionClass": "A String", # Optional. The fully qualified name

2212

# (<var>module_name</var>.<var>class_name</var>) of a class that implements

2213

# the Predictor interface described in this reference field. The module

2214

# containing this class should be included in a package provided to the

2215

# [`packageUris` field](#Version.FIELDS.package_uris).

2216

#

2217

# Specify this field if and only if you are deploying a [custom prediction

2218

# routine (beta)](/ml-engine/docs/tensorflow/custom-prediction-routines).

2219

# If you specify this field, you must set

2220

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater and

2221

# you must set `machineType` to a [legacy (MLS1)

2222

# machine type](/ml-engine/docs/machine-types-online-prediction).

2223

#

2224

# The following code sample provides the Predictor interface:

2225

#

2226

# <pre style="max-width: 626px;">

2227

# class Predictor(object):

2228

# """Interface for constructing custom predictors."""

2229

#

2230

# def predict(self, instances, **kwargs):

2231

# """Performs custom prediction.

2232

#

2233

# Instances are the decoded values from the request. They have already

2234

# been deserialized from JSON.

2235

#

2236

# Args:

2237

# instances: A list of prediction input instances.

2238

# **kwargs: A dictionary of keyword args provided as additional

2239

# fields on the predict request body.

2240

#

2241

# Returns:

2242

# A list of outputs containing the prediction results. This list must

2243

# be JSON serializable.

2244

# """

2245

# raise NotImplementedError()

2246

#

2247

# @classmethod

2248

# def from_path(cls, model_dir):

2249

# """Creates an instance of Predictor using the given path.

2250

#

2251

# Loading of the predictor should be done in this method.

2252

#

2253

# Args:

2254

# model_dir: The local directory that contains the exported model

2255

# file along with any additional files uploaded when creating the

# version resource.

#

# Returns:

# An instance implementing this Predictor class.

2260

# """

2261

# raise NotImplementedError()

2262

# </pre>

2263

#

2264

# Learn more about [the Predictor interface and custom prediction

2265

# routines](/ml-engine/docs/tensorflow/custom-prediction-routines).

2266

"packageUris": [ # Optional. Cloud Storage paths (`gs://…`) of packages for [custom

2267

# prediction routines](/ml-engine/docs/tensorflow/custom-prediction-routines)

2268

# or [scikit-learn pipelines with custom

2269

# code](/ml-engine/docs/scikit/exporting-for-prediction#custom-pipeline-code).

2270

#

2271

# For a custom prediction routine, one of these packages must contain your

2272

# Predictor class (see

2273

# [`predictionClass`](#Version.FIELDS.prediction_class)). Additionally,

2274

# include any dependencies used by your Predictor or scikit-learn pipeline

2275

# uses that are not already included in your selected [runtime

2276

# version](/ml-engine/docs/tensorflow/runtime-version-list).

2277

#

2278

# If you specify this field, you must also set

2279

# [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater.

2280

"A String",

2281

],

2282

"explanationConfig": { # Message holding configuration options for explaining model predictions. # Optional. Configures explainability features on the model's version.

2283

# Some explanation features require additional metadata to be loaded

2284

# as part of the model payload.

2285

# There are two feature attribution methods supported for TensorFlow models:

2286

# integrated gradients and sampled Shapley.

2287

# [Learn more about feature

2288

# attributions.](/ai-platform/prediction/docs/ai-explanations/overview)

2289

"integratedGradientsAttribution": { # Attributes credit by computing the Aumann-Shapley value taking advantage # Attributes credit by computing the Aumann-Shapley value taking advantage

2290

# of the model's fully differentiable structure. Refer to this paper for

2291

# more details: http://proceedings.mlr.press/v70/sundararajan17a.html

2292

# of the model's fully differentiable structure. Refer to this paper for

2293

# more details: https://arxiv.org/abs/1703.01365

2294

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

2295

# A good value to start is 50 and gradually increase until the

2296

# sum to diff property is met within the desired error range.

2297

},

2298

"sampledShapleyAttribution": { # An attribution method that approximates Shapley values for features that # An attribution method that approximates Shapley values for features that

2299

# contribute to the label being predicted. A sampling strategy is used to

2300

# approximate the value rather than considering all subsets of features.

2301

# contribute to the label being predicted. A sampling strategy is used to

2302

# approximate the value rather than considering all subsets of features.

2303

"numPaths": 42, # The number of feature permutations to consider when approximating the

2304

# Shapley values.

2305

},

2306

"xraiAttribution": { # Attributes credit by computing the XRAI taking advantage # Attributes credit by computing the XRAI taking advantage

2307

# of the model's fully differentiable structure. Refer to this paper for

2308

# more details: https://arxiv.org/abs/1906.02825

2309

# Currently only implemented for models with natural image inputs.

2310

# of the model's fully differentiable structure. Refer to this paper for

2311

# more details: https://arxiv.org/abs/1906.02825

2312

# Currently only implemented for models with natural image inputs.

2313

"numIntegralSteps": 42, # Number of steps for approximating the path integral.

2314

# A good value to start is 50 and gradually increase until the

2315

# sum to diff property is met within the desired error range.

2316

},

2317

},

2318

"deploymentUri": "A String", # Required. The Cloud Storage location of the trained model used to

2319

# create the version. See the

2320

# [guide to model

2321

# deployment](/ml-engine/docs/tensorflow/deploying-models) for more

2322

# information.

2323

#

2324

# When passing Version to

2325

# projects.models.versions.create

2326

# the model service uses the specified location as the source of the model.

2327

# Once deployed, the model version is hosted by the prediction service, so

2328

# this location is useful only as a historical record.

2329

# The total number of model files can't exceed 1000.

2330

"autoScaling": { # Options for automatically scaling a model. # Automatically scale the number of nodes used to serve the model in

2331

# response to increases and decreases in traffic. Care should be

2332

# taken to ramp up traffic according to the model's ability to scale

2333

# or you will start seeing increases in latency and 429 response codes.

2334

#

2335

# Note that you cannot use AutoScaling if your version uses

2336

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use specify

2337

# `manual_scaling`.

2338

"minNodes": 42, # Optional. The minimum number of nodes to allocate for this model. These

2339

# nodes are always up, starting from the time the model is deployed.

2340

# Therefore, the cost of operating this model will be at least

2341

# `rate` * `min_nodes` * number of hours since last billing cycle,

2342

# where `rate` is the cost per node-hour as documented in the

2343

# [pricing guide](/ml-engine/docs/pricing),

2344

# even if no predictions are performed. There is additional cost for each

2345

# prediction performed.

2346

#

2347

# Unlike manual scaling, if the load gets too heavy for the nodes

2348

# that are up, the service will automatically add nodes to handle the

2349

# increased load as well as scale back as traffic drops, always maintaining

2350

# at least `min_nodes`. You will be charged for the time in which additional

2351

# nodes are used.

2352

#

2353

# If `min_nodes` is not specified and AutoScaling is used with a [legacy

2354

# (MLS1) machine type](/ml-engine/docs/machine-types-online-prediction),

2355

# `min_nodes` defaults to 0, in which case, when traffic to a model stops

2356

# (and after a cool-down period), nodes will be shut down and no charges will

2357

# be incurred until traffic to the model resumes.

2358

#

2359

# If `min_nodes` is not specified and AutoScaling is used with a [Compute

2360

# Engine (N1) machine type](/ml-engine/docs/machine-types-online-prediction),

2361

# `min_nodes` defaults to 1. `min_nodes` must be at least 1 for use with a

2362

# Compute Engine machine type.

2363

#

2364

# Note that you cannot use AutoScaling if your version uses

2365

# [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use

2366

# ManualScaling.

2367

#

2368

# You can set `min_nodes` when creating the model version, and you can also

2369

# update `min_nodes` for an existing version:

# <pre>

# update_body.json:

# {

# 'autoScaling': {

# 'minNodes': 5

# }

# }

# </pre>

# HTTP request:

# <pre style="max-width: 626px;">

2380

# PATCH

2381

# https://ml.googleapis.com/v1/{name=projects/*/models/*/versions/*}?update_mask=autoScaling.minNodes

2382

# -d @./update_body.json

2383

# </pre>

2384

},

2385

"labels": { # Optional. One or more labels that you can add, to organize your model

2386

# versions. Each label is a key-value pair, where both the key and the value

2387

# are arbitrary strings that you supply.

2388

# For more information, see the documentation on

2389

# <a href="/ml-engine/docs/tensorflow/resource-labels">using labels</a>.

2390

"a_key": "A String",

2391

},

2392

"createTime": "A String", # Output only. The time the version was created.

2393

"requestLoggingConfig": { # Configuration for logging request-response pairs to a BigQuery table. # Optional. *Only* specify this field in a

2394

# projects.models.versions.patch

2395

# request. Specifying it in a

2396

# projects.models.versions.create

2397

# request has no effect.

2398

#

2399

# Configures the request-response pair logging on predictions from this

2400

# Version.

2401

# Online prediction requests to a model version and the responses to these

2402

# requests are converted to raw strings and saved to the specified BigQuery

2403

# table. Logging is constrained by [BigQuery quotas and

2404

# limits](/bigquery/quotas). If your project exceeds BigQuery quotas or limits,

2405

# AI Platform Prediction does not log request-response pairs, but it continues

2406

# to serve predictions.

2407

#

2408

# If you are using [continuous

2409

# evaluation](/ml-engine/docs/continuous-evaluation/), you do not need to

2410

# specify this configuration manually. Setting up continuous evaluation

2411

# automatically enables logging of request-response pairs.

2412

"bigqueryTableName": "A String", # Required. Fully qualified BigQuery table name in the following format:

2413

# "<var>project_id</var>.<var>dataset_name</var>.<var>table_name</var>"

2414

#

2415

# The specified table must already exist, and the "Cloud ML Service Agent"

2416

# for your project must have permission to write to it. The table must have

2417

# the following [schema](/bigquery/docs/schemas):

2418

#

2419

# <table>

2420

# <tr><th>Field name</th><th style="display: table-cell">Type</th>

2421

# <th style="display: table-cell">Mode</th></tr>

2422

# <tr><td>model</td><td>STRING</td><td>REQUIRED</td></tr>

2423

# <tr><td>model_version</td><td>STRING</td><td>REQUIRED</td></tr>

2424

# <tr><td>time</td><td>TIMESTAMP</td><td>REQUIRED</td></tr>

2425

# <tr><td>raw_data</td><td>STRING</td><td>REQUIRED</td></tr>

2426

# <tr><td>raw_prediction</td><td>STRING</td><td>NULLABLE</td></tr>

2427

# <tr><td>groundtruth</td><td>STRING</td><td>NULLABLE</td></tr>

2428

# </table>

2429

"samplingPercentage": 3.14, # Percentage of requests to be logged, expressed as a fraction from 0 to 1.

2430

# For example, if you want to log 10% of requests, enter `0.1`. The sampling

2431

# window is the lifetime of the model version. Defaults to 0.

2432

},

2433

"errorMessage": "A String", # Output only. The details of a failure or a cancellation.

2434

"machineType": "A String", # Optional. The type of machine on which to serve the model. Currently only

2435

# applies to online prediction service. If this field is not specified, it

2436

# defaults to `mls1-c1-m2`.

2437

#

2438

# 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

2459

# in beta. Learn more about the [differences between machine

2460

# types](/ml-engine/docs/machine-types-online-prediction).

2461

"runtimeVersion": "A String", # Required. The AI Platform runtime version to use for this deployment.

2462

#

2463

# For more information, see the

2464

# [runtime version list](/ml-engine/docs/runtime-version-list) and

2465

# [how to manage runtime versions](/ml-engine/docs/versioning).

2466

"description": "A String", # Optional. The description specified for the version when it was created.

2467

"framework": "A String", # Optional. The machine learning framework AI Platform uses to train

2468

# this version of the model. Valid values are `TENSORFLOW`, `SCIKIT_LEARN`,

2469

# `XGBOOST`. If you do not specify a framework, AI Platform

2470

# will analyze files in the deployment_uri to determine a framework. If you

2471

# choose `SCIKIT_LEARN` or `XGBOOST`, you must also set the runtime version

2472

# of the model to 1.4 or greater.

2473

#

2474

# Do **not** specify a framework if you're deploying a [custom

2475

# prediction routine](/ml-engine/docs/tensorflow/custom-prediction-routines).

2476

#

2477

# If you specify a [Compute Engine (N1) machine

2478

# type](/ml-engine/docs/machine-types-online-prediction) in the

2479

# `machineType` field, you must specify `TENSORFLOW`

2480

# for the framework.

2481

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

2482

# prevent simultaneous updates of a model from overwriting each other.

2483

# It is strongly suggested that systems make use of the `etag` in the

2484

# read-modify-write cycle to perform model updates in order to avoid race

2485

# conditions: An `etag` is returned in the response to `GetVersion`, and

2486

# systems are expected to put that etag in the request to `UpdateVersion` to

2487

# ensure that their change will be applied to the model as intended.

2488

"isDefault": True or False, # Output only. If true, this version will be used to handle prediction

2489

# requests that do not specify a version.

2490

#

2491

# You can change the default version by calling

2492

# projects.methods.versions.setDefault.

2493

"acceleratorConfig": { # Represents a hardware accelerator request config. # Optional. Accelerator config for using GPUs for online prediction (beta).

2494

# Only specify this field if you have specified a Compute Engine (N1) machine

2495

# type in the `machineType` field. Learn more about [using GPUs for online

2496

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

2497

# Note that the AcceleratorConfig can be used in both Jobs and Versions.

2498

# Learn more about [accelerators for training](/ml-engine/docs/using-gpus) and

2499

# [accelerators for online

2500

# prediction](/ml-engine/docs/machine-types-online-prediction#gpus).

2501

"count": "A String", # The number of accelerators to attach to each machine running the job.

2502

"type": "A String", # The type of accelerator to use.

2503

},

2504

},

2505

"onlinePredictionConsoleLogging": True or False, # Optional. If true, online prediction nodes send `stderr` and `stdout`

2506

# streams to Stackdriver Logging. These can be more verbose than the standard

2507

# access logs (see `onlinePredictionLogging`) and can incur higher cost.

2508

# However, they are helpful for debugging. Note that

2509

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

2510

# your project receives prediction requests at a high QPS. Estimate your

2511

# costs before enabling this option.

2512

#

2513

# Default is false.

2514

"regions": [ # Optional. The list of regions where the model is going to be deployed.

2515

# Only one region per model is supported.

2516

# Defaults to 'us-central1' if nothing is set.

2517

# See the <a href="/ml-engine/docs/tensorflow/regions">available regions</a>

2518

# for AI Platform services.

2519

# Note:

2520

# * No matter where a model is deployed, it can always be accessed by

2521

# users from anywhere, both for online and batch prediction.

2522

# * The region for a batch prediction job is set by the region field when

2523

# submitting the batch prediction job and does not take its value from

2524

# this field.

2525

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2526

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2527

"description": "A String", # Optional. The description specified for the model when it was created.

2528

"onlinePredictionLogging": True or False, # Optional. If true, online prediction access logs are sent to StackDriver

2529

# Logging. These logs are like standard server access logs, containing

2530

# information like timestamp and latency for each request. Note that

2531

# [Stackdriver logs may incur a cost](/stackdriver/pricing), especially if

2532

# your project receives prediction requests at a high queries per second rate

2533

# (QPS). Estimate your costs before enabling this option.

2534

#

2535

# Default is false.

2536

"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]

2537

# prevent simultaneous updates of a model from overwriting each other.

2538

# It is strongly suggested that systems make use of the `etag` in the

2539

# read-modify-write cycle to perform model updates in order to avoid race

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2540

# conditions: An `etag` is returned in the response to `GetModel`, and

2541

# systems are expected to put that etag in the request to `UpdateModel` to

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2542

# ensure that their change will be applied to the model as intended.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

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

"response": { # The normal response of the operation in case of success. If the original

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2571

# method returns no data on success, such as `Delete`, the response is

2572

# `google.protobuf.Empty`. If the original method is standard

2573

# `Get`/`Create`/`Update`, the response should be the resource. For other

2574

# methods, the response should have the type `XxxResponse`, where `Xxx`

2575

# is the original method name. For example, if the original method name

2576

# is `TakeSnapshot()`, the inferred response type is

2577

# `TakeSnapshotResponse`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2578

"a_key": "", # Properties of the object. Contains field @type with type URL.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2579

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2580

"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]

2581

# originally returns it. If you use the default HTTP mapping, the

2582

# `name` should be a resource name ending with `operations/{unique_id}`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2583

"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.

2584

# different programming environments, including REST APIs and RPC APIs. It is

2585

# used by [gRPC](https://github.com/grpc). Each `Status` message contains

2586

# three pieces of data: error code, error message, and error details.

2587

#

2588

# You can find out more about this error model and how to work with it in the

2589

# [API Design Guide](https://cloud.google.com/apis/design/errors).

2590

"details": [ # A list of messages that carry the error details. There is a common set of

2591

# message types for APIs to use.

2592

{

2593

"a_key": "", # Properties of the object. Contains field @type with type URL.

2594

},

2595

],

2596

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

2597

"message": "A String", # A developer-facing error message, which should be in English. Any

2598

# user-facing error message should be localized and sent in the

2599

# google.rpc.Status.details field, or localized by the client.

2600

},

2601

"metadata": { # Service-specific metadata associated with the operation. It typically

2602

# contains progress information and common metadata such as create time.

2603

# Some services might not provide such metadata. Any method that returns a

2604

# long-running operation should document the metadata type, if any.

2605

"a_key": "", # Properties of the object. Contains field @type with type URL.

2606

},

2607

"done": True or False, # If the value is `false`, it means the operation is still in progress.

2608

# If `true`, the operation is completed, and either `error` or `response` is

2609

# available.

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-20 12:08:20 -0700

[diff] [blame]

2627

"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]

2628

# the policy is limited to a few 10s of KB. An empty policy is a

2629

# valid policy but certain Cloud Platform services (such as Projects)

2630

# might reject them.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2631

# controls for Google Cloud resources.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2632

#

2633

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2634

# A `Policy` is a collection of `bindings`. A `binding` binds one or more

2635

# `members` to a single `role`. Members can be user accounts, service accounts,

2636

# Google groups, and domains (such as G Suite). A `role` is a named list of

2637

# permissions; each `role` can be an IAM predefined role or a user-created

2638

# custom role.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2639

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2640

# For some types of Google Cloud resources, a `binding` can also specify a

2641

# `condition`, which is a logical expression that allows access to a resource

2642

# only if the expression evaluates to `true`. A condition can add constraints

2643

# based on attributes of the request, the resource, or both. To learn which

2644

# resources support conditions in their IAM policies, see the

2645

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2646

#

2647

# **JSON example:**

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2648

#

2649

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2650

# "bindings": [

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2651

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2652

# "role": "roles/resourcemanager.organizationAdmin",

2653

# "members": [

2654

# "user:mike@example.com",

2655

# "group:admins@example.com",

2656

# "domain:google.com",

2657

# "serviceAccount:my-project-id@appspot.gserviceaccount.com"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2658

# ]

2659

# },

2660

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2661

# "role": "roles/resourcemanager.organizationViewer",

2662

# "members": [

2663

# "user:eve@example.com"

2664

# ],

2665

# "condition": {

2666

# "title": "expirable access",

2667

# "description": "Does not grant access after Sep 2020",

2668

# "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2669

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2670

# }

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2671

# ],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2672

# "etag": "BwWWja0YfJA=",

2673

# "version": 3

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2674

# }

2675

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2676

# **YAML example:**

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

#

# bindings:

# - members:

# - user:mike@example.com

2681

# - group:admins@example.com

2682

# - domain:google.com

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2683

# - serviceAccount:my-project-id@appspot.gserviceaccount.com

2684

# role: roles/resourcemanager.organizationAdmin

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2685

# - members:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2686

# - user:eve@example.com

2687

# role: roles/resourcemanager.organizationViewer

2688

# condition:

2689

# title: expirable access

2690

# description: Does not grant access after Sep 2020

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2691

# expression: request.time < timestamp('2020-10-01T00:00:00.000Z')

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2692

# - etag: BwWWja0YfJA=

2693

# - version: 3

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2694

#

2695

# For a description of IAM and its features, see the

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2696

# [IAM documentation](https://cloud.google.com/iam/docs/).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2697

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

2698

# prevent simultaneous updates of a policy from overwriting each other.

2699

# It is strongly suggested that systems make use of the `etag` in the

2700

# read-modify-write cycle to perform policy updates in order to avoid race

2701

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

2702

# systems are expected to put that etag in the request to `setIamPolicy` to

2703

# ensure that their change will be applied to the same version of the policy.

2704

#

2705

# **Important:** If you use IAM Conditions, you must include the `etag` field

2706

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

2707

# you to overwrite a version `3` policy with a version `1` policy, and all of

2708

# the conditions in the version `3` policy are lost.

2709

"version": 42, # Specifies the format of the policy.

2710

#

2711

# Valid values are `0`, `1`, and `3`. Requests that specify an invalid value

2712

# are rejected.

2713

#

2714

# Any operation that affects conditional role bindings must specify version

2715

# `3`. This requirement applies to the following operations:

2716

#

2717

# * Getting a policy that includes a conditional role binding

2718

# * Adding a conditional role binding to a policy

2719

# * Changing a conditional role binding in a policy

2720

# * Removing any role binding, with or without a condition, from a policy

2721

# that includes conditions

2722

#

2723

# **Important:** If you use IAM Conditions, you must include the `etag` field

2724

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

2725

# you to overwrite a version `3` policy with a version `1` policy, and all of

2726

# the conditions in the version `3` policy are lost.

2727

#

2728

# If a policy does not include any conditions, operations on that policy may

2729

# specify any valid version or leave the field unset.

2730

#

2731

# To learn which resources support conditions in their IAM policies, see the

2732

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

2733

"auditConfigs": [ # Specifies cloud audit logging configuration for this policy.

2734

{ # Specifies the audit configuration for a service.

2735

# The configuration determines which permission types are logged, and what

2736

# identities, if any, are exempted from logging.

2737

# An AuditConfig must have one or more AuditLogConfigs.

2738

#

2739

# If there are AuditConfigs for both `allServices` and a specific service,

2740

# the union of the two AuditConfigs is used for that service: the log_types

2741

# specified in each AuditConfig are enabled, and the exempted_members in each

2742

# AuditLogConfig are exempted.

2743

#

2744

# Example Policy with multiple AuditConfigs:

#

# {

# "audit_configs": [

# {

# "service": "allServices"

2750

# "audit_log_configs": [

2751

# {

2752

# "log_type": "DATA_READ",

2753

# "exempted_members": [

2754

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

2759

# },

2760

# {

2761

# "log_type": "ADMIN_READ",

# }

# ]

# },

# {

# "service": "sampleservice.googleapis.com"

2767

# "audit_log_configs": [

2768

# {

2769

# "log_type": "DATA_READ",

2770

# },

2771

# {

2772

# "log_type": "DATA_WRITE",

2773

# "exempted_members": [

2774

# "user:aliya@example.com"

# ]

# }

# ]

# }

# ]

# }

#

# For sampleservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ

2783

# logging. It also exempts jose@example.com from DATA_READ logging, and

2784

# aliya@example.com from DATA_WRITE logging.

2785

"service": "A String", # Specifies a service that will be enabled for audit logging.

2786

# For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.

2787

# `allServices` is a special value that covers all services.

2788

"auditLogConfigs": [ # The configuration for logging of each type of permission.

2789

{ # Provides the configuration for logging a type of permissions.

# Example:

#

# {

# "audit_log_configs": [

2794

# {

2795

# "log_type": "DATA_READ",

2796

# "exempted_members": [

2797

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

# }

# ]

# }

#

# This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting

2807

# jose@example.com from DATA_READ logging.

2808

"exemptedMembers": [ # Specifies the identities that do not cause logging for this type of

2809

# permission.

2810

# Follows the same format of Binding.members.

2811

"A String",

2812

],

2813

"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]

2819

# `condition` that determines how and when the `bindings` are applied. Each

2820

# of the `bindings` must contain at least one member.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2821

{ # Associates `members` with a `role`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2822

"condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.

2823

#

2824

# If the condition evaluates to `true`, then this binding applies to the

2825

# current request.

2826

#

2827

# If the condition evaluates to `false`, then this binding does not apply to

2828

# the current request. However, a different role binding might grant the same

2829

# role to one or more of the members in this binding.

2830

#

2831

# To learn which resources support conditions in their IAM policies, see the

2832

# [IAM

2833

# documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

2834

# syntax. CEL is a C-like expression language. The syntax and semantics of CEL

2835

# are documented at https://github.com/google/cel-spec.

2836

#

2837

# Example (Comparison):

2838

#

2839

# title: "Summary size limit"

2840

# description: "Determines if a summary is less than 100 chars"

2841

# expression: "document.summary.size() < 100"

2842

#

2843

# Example (Equality):

2844

#

2845

# title: "Requestor is owner"

2846

# description: "Determines if requestor is the document owner"

2847

# expression: "document.owner == request.auth.claims.email"

#

# Example (Logic):

#

# title: "Public documents"

2852

# description: "Determine whether the document should be publicly visible"

2853

# expression: "document.type != 'private' && document.type != 'internal'"

2854

#

2855

# Example (Data Manipulation):

2856

#

2857

# title: "Notification string"

2858

# description: "Create a notification string with a timestamp."

2859

# expression: "'New message received at ' + string(document.create_time)"

2860

#

2861

# The exact variables and functions that may be referenced within an expression

2862

# are determined by the service that evaluates it. See the service

2863

# documentation for additional information.

2864

"title": "A String", # Optional. Title for the expression, i.e. a short string describing

2865

# its purpose. This can be used e.g. in UIs which allow to enter the

2866

# expression.

2867

"location": "A String", # Optional. String indicating the location of the expression for error

2868

# reporting, e.g. a file name and a position in the file.

2869

"description": "A String", # Optional. Description of the expression. This is a longer text which

2870

# describes the expression, e.g. when hovered over it in a UI.

2871

"expression": "A String", # Textual representation of an expression in Common Expression Language

2872

# syntax.

2873

},

2874

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2875

# `members` can have the following values:

2876

#

2877

# * `allUsers`: A special identifier that represents anyone who is

2878

# on the internet; with or without a Google account.

2879

#

2880

# * `allAuthenticatedUsers`: A special identifier that represents anyone

2881

# who is authenticated with a Google account or a service account.

2882

#

2883

# * `user:{emailid}`: An email address that represents a specific Google

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2884

# account. For example, `alice@example.com` .

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2885

#

2886

#

2887

# * `serviceAccount:{emailid}`: An email address that represents a service

2888

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

2889

#

2890

# * `group:{emailid}`: An email address that represents a Google group.

2891

# For example, `admins@example.com`.

2892

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2893

# * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique

2894

# identifier) representing a user that has been recently deleted. For

2895

# example, `alice@example.com?uid=123456789012345678901`. If the user is

2896

# recovered, this value reverts to `user:{emailid}` and the recovered user

2897

# retains the role in the binding.

2898

#

2899

# * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus

2900

# unique identifier) representing a service account that has been recently

2901

# deleted. For example,

2902

# `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.

2903

# If the service account is undeleted, this value reverts to

2904

# `serviceAccount:{emailid}` and the undeleted service account retains the

2905

# role in the binding.

2906

#

2907

# * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique

2908

# identifier) representing a Google group that has been recently

2909

# deleted. For example, `admins@example.com?uid=123456789012345678901`. If

2910

# the group is recovered, this value reverts to `group:{emailid}` and the

2911

# recovered group retains the role in the binding.

2912

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2913

#

2914

# * `domain:{domain}`: The G Suite domain (primary) that represents all the

2915

# users of that domain. For example, `google.com` or `example.com`.

2916

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2917

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2918

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2919

"role": "A String", # Role that is assigned to `members`.

2920

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2921

},

2922

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2923

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2924

"updateMask": "A String", # OPTIONAL: A FieldMask specifying which fields of the policy to modify. Only

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2925

# the fields in the mask will be modified. If no mask is provided, the

2926

# following default mask is used:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2927

#

2928

# `paths: "bindings, etag"`

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

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

3007

# prevent simultaneous updates of a policy from overwriting each other.

3008

# It is strongly suggested that systems make use of the `etag` in the

3009

# read-modify-write cycle to perform policy updates in order to avoid race

3010

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

3011

# systems are expected to put that etag in the request to `setIamPolicy` to

3012

# ensure that their change will be applied to the same version of the policy.

3013

#

3014

# **Important:** If you use IAM Conditions, you must include the `etag` field

3015

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

3016

# you to overwrite a version `3` policy with a version `1` policy, and all of

3017

# the conditions in the version `3` policy are lost.

3018

"version": 42, # Specifies the format of the policy.

3019

#

3020

# Valid values are `0`, `1`, and `3`. Requests that specify an invalid value

3021

# are rejected.

3022

#

3023

# Any operation that affects conditional role bindings must specify version

3024

# `3`. This requirement applies to the following operations:

3025

#

3026

# * Getting a policy that includes a conditional role binding

3027

# * Adding a conditional role binding to a policy

3028

# * Changing a conditional role binding in a policy

3029

# * Removing any role binding, with or without a condition, from a policy

3030

# that includes conditions

3031

#

3032

# **Important:** If you use IAM Conditions, you must include the `etag` field

3033

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

3034

# you to overwrite a version `3` policy with a version `1` policy, and all of

3035

# the conditions in the version `3` policy are lost.

3036

#

3037

# If a policy does not include any conditions, operations on that policy may

3038

# specify any valid version or leave the field unset.

3039

#

3040

# To learn which resources support conditions in their IAM policies, see the

3041

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

3042

"auditConfigs": [ # Specifies cloud audit logging configuration for this policy.

3043

{ # Specifies the audit configuration for a service.

3044

# The configuration determines which permission types are logged, and what

3045

# identities, if any, are exempted from logging.

3046

# An AuditConfig must have one or more AuditLogConfigs.

3047

#

3048

# If there are AuditConfigs for both `allServices` and a specific service,

3049

# the union of the two AuditConfigs is used for that service: the log_types

3050

# specified in each AuditConfig are enabled, and the exempted_members in each

3051

# AuditLogConfig are exempted.

3052

#

3053

# Example Policy with multiple AuditConfigs:

#

# {

# "audit_configs": [

# {

# "service": "allServices"

3059

# "audit_log_configs": [

3060

# {

3061

# "log_type": "DATA_READ",

3062

# "exempted_members": [

3063

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

3068

# },

3069

# {

3070

# "log_type": "ADMIN_READ",

# }

# ]

# },

# {

# "service": "sampleservice.googleapis.com"

3076

# "audit_log_configs": [

3077

# {

3078

# "log_type": "DATA_READ",

3079

# },

3080

# {

3081

# "log_type": "DATA_WRITE",

3082

# "exempted_members": [

3083

# "user:aliya@example.com"

# ]

# }

# ]

# }

# ]

# }

#

# For sampleservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ

3092

# logging. It also exempts jose@example.com from DATA_READ logging, and

3093

# aliya@example.com from DATA_WRITE logging.

3094

"service": "A String", # Specifies a service that will be enabled for audit logging.

3095

# For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.

3096

# `allServices` is a special value that covers all services.

3097

"auditLogConfigs": [ # The configuration for logging of each type of permission.

3098

{ # Provides the configuration for logging a type of permissions.

# Example:

#

# {

# "audit_log_configs": [

3103

# {

3104

# "log_type": "DATA_READ",

3105

# "exempted_members": [

3106

# "user:jose@example.com"

# ]

# },

# {

# "log_type": "DATA_WRITE",

# }

# ]

# }

#

# This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting

3116

# jose@example.com from DATA_READ logging.

3117

"exemptedMembers": [ # Specifies the identities that do not cause logging for this type of

3118

# permission.

3119

# Follows the same format of Binding.members.

3120

"A String",

3121

],

3122

"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]

3128

# `condition` that determines how and when the `bindings` are applied. Each

3129

# of the `bindings` must contain at least one member.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3130

{ # Associates `members` with a `role`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3131

"condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.

3132

#

3133

# If the condition evaluates to `true`, then this binding applies to the

3134

# current request.

3135

#

3136

# If the condition evaluates to `false`, then this binding does not apply to

3137

# the current request. However, a different role binding might grant the same

3138

# role to one or more of the members in this binding.

3139

#

3140

# To learn which resources support conditions in their IAM policies, see the

3141

# [IAM

3142

# documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

3143

# syntax. CEL is a C-like expression language. The syntax and semantics of CEL

3144

# are documented at https://github.com/google/cel-spec.

3145

#

3146

# Example (Comparison):

3147

#

3148

# title: "Summary size limit"

3149

# description: "Determines if a summary is less than 100 chars"

3150

# expression: "document.summary.size() < 100"

3151

#

3152

# Example (Equality):

3153

#

3154

# title: "Requestor is owner"

3155

# description: "Determines if requestor is the document owner"

3156

# expression: "document.owner == request.auth.claims.email"

#

# Example (Logic):

#

# title: "Public documents"

3161

# description: "Determine whether the document should be publicly visible"

3162

# expression: "document.type != 'private' && document.type != 'internal'"

3163

#

3164

# Example (Data Manipulation):

3165

#

3166

# title: "Notification string"

3167

# description: "Create a notification string with a timestamp."

3168

# expression: "'New message received at ' + string(document.create_time)"

3169

#

3170

# The exact variables and functions that may be referenced within an expression

3171

# are determined by the service that evaluates it. See the service

3172

# documentation for additional information.

3173

"title": "A String", # Optional. Title for the expression, i.e. a short string describing

3174

# its purpose. This can be used e.g. in UIs which allow to enter the

3175

# expression.

3176

"location": "A String", # Optional. String indicating the location of the expression for error

3177

# reporting, e.g. a file name and a position in the file.

3178

"description": "A String", # Optional. Description of the expression. This is a longer text which

3179

# describes the expression, e.g. when hovered over it in a UI.

3180

"expression": "A String", # Textual representation of an expression in Common Expression Language

3181

# syntax.

3182

},

3183

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3184

# `members` can have the following values:

3185

#

3186

# * `allUsers`: A special identifier that represents anyone who is

3187

# on the internet; with or without a Google account.

3188

#

3189

# * `allAuthenticatedUsers`: A special identifier that represents anyone

3190

# who is authenticated with a Google account or a service account.

3191

#

3192

# * `user:{emailid}`: An email address that represents a specific Google

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3193

# account. For example, `alice@example.com` .

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3194

#

3195

#

3196

# * `serviceAccount:{emailid}`: An email address that represents a service

3197

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

3198

#

3199

# * `group:{emailid}`: An email address that represents a Google group.

3200

# For example, `admins@example.com`.

3201

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3202

# * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique

3203

# identifier) representing a user that has been recently deleted. For

3204

# example, `alice@example.com?uid=123456789012345678901`. If the user is

3205

# recovered, this value reverts to `user:{emailid}` and the recovered user

3206

# retains the role in the binding.

3207

#

3208

# * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus

3209

# unique identifier) representing a service account that has been recently

3210

# deleted. For example,

3211

# `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.

3212

# If the service account is undeleted, this value reverts to

3213

# `serviceAccount:{emailid}` and the undeleted service account retains the

3214

# role in the binding.

3215

#

3216

# * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique

3217

# identifier) representing a Google group that has been recently

3218

# deleted. For example, `admins@example.com?uid=123456789012345678901`. If

3219

# the group is recovered, this value reverts to `group:{emailid}` and the

3220

# recovered group retains the role in the binding.

3221

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3222

#

3223

# * `domain:{domain}`: The G Suite domain (primary) that represents all the

3224

# users of that domain. For example, `google.com` or `example.com`.

3225

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3226

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3227

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3228

"role": "A String", # Role that is assigned to `members`.

3229

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3230

},

3231

],

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