Blame - docs/dyn/cloudtasks_v2.projects.locations.queues.html - platform/external/python/google-api-python-client

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

[diff] [blame]

83

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

Bu Sun Kim

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

[diff] [blame]

84

<p class="firstline">Creates a queue.</p>

85

86

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

87

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

88

89

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

90

<p class="firstline">Gets a queue.</p>

91

92

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

93

<p class="firstline">Gets the access control policy for a Queue.</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>

Bu Sun Kim

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

[diff] [blame]

96

<p class="firstline">Lists queues.</p>

97

98

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

99

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

100

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 queue.</p>

103

104

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

105

<p class="firstline">Pauses the queue.</p>

106

107

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

108

<p class="firstline">Purges a queue by deleting all of its tasks.</p>

109

110

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

111

<p class="firstline">Resume a queue.</p>

112

Dan O'Meara

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

[diff] [blame]

113

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

114

<p class="firstline">Sets the access control policy for a Queue. Replaces any existing</p>

115

Dan O'Meara

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

[diff] [blame]

116

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

117

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

118

<h3>Method Details</h3>

119

Dan O'Meara

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

[diff] [blame]

120

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

Bu Sun Kim

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

[diff] [blame]

121

<pre>Creates a queue.

122

123

Queues created with this method allow tasks to live for a maximum of 31

124

days. After a task is 31 days old, the task will be deleted regardless of whether

125

it was dispatched or not.

126

127

WARNING: Using this method may have unintended side effects if you are

128

using an App Engine `queue.yaml` or `queue.xml` file to manage your queues.

129

Read

130

[Overview of Queue Management and

131

queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using

132

this method.

133

134

Args:

Dan O'Meara

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

[diff] [blame]

135

parent: string, Required. The location name in which the queue will be created.

Bu Sun Kim

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

[diff] [blame]

136

For example: `projects/PROJECT_ID/locations/LOCATION_ID`

137

138

The list of allowed locations can be obtained by calling Cloud

Bu Sun Kim

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

[diff] [blame^]

139

Tasks' implementation of

Bu Sun Kim

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

[diff] [blame]

140

ListLocations. (required)

Dan O'Meara

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

[diff] [blame]

141

body: object, The request body.

Bu Sun Kim

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

[diff] [blame]

142

The object takes the form of:

143

144

{ # A queue is a container of related tasks. Queues are configured to manage

145

# how those tasks are dispatched. Configurable properties include rate limits,

146

# retry options, queue types, and others.

Bu Sun Kim

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

[diff] [blame^]

147

"purgeTime": "A String", # Output only. The last time this queue was purged.

148

#

149

# All tasks that were created before this time

150

# were purged.

151

#

152

# A queue can be purged using PurgeQueue, the

153

# [App Engine Task Queue SDK, or the Cloud

154

# Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue).

155

#

156

# Purge time will be truncated to the nearest microsecond. Purge

157

# time will be unset if the queue has never been purged.

158

"retryConfig": { # Retry config. # Settings that determine the retry behavior.

159

#

160

# * For tasks created using Cloud Tasks: the queue-level retry settings

161

# apply to all tasks in the queue that were created using Cloud Tasks.

162

# Retry settings cannot be set on individual tasks.

163

# * For tasks created using the App Engine SDK: the queue-level retry

164

# settings apply to all tasks in the queue which do not have retry settings

165

# explicitly set on the task and were created by the App Engine SDK. See

166

# [App Engine

167

# documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks).

168

#

169

# These settings determine when a failed task attempt is retried.

170

"minBackoff": "A String", # A task will be scheduled for retry between

171

# min_backoff and

172

# max_backoff duration after it fails,

173

# if the queue's RetryConfig specifies that the task should be

174

# retried.

175

#

176

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `min_backoff` will be truncated to the nearest second.

181

#

182

# This field has the same meaning as

183

# [min_backoff_seconds in

184

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

185

"maxBackoff": "A String", # A task will be scheduled for retry between

186

# min_backoff and

187

# max_backoff duration after it fails,

188

# if the queue's RetryConfig specifies that the task should be

189

# retried.

190

#

191

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_backoff` will be truncated to the nearest second.

196

#

197

# This field has the same meaning as

198

# [max_backoff_seconds in

199

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

200

"maxRetryDuration": "A String", # If positive, `max_retry_duration` specifies the time limit for

201

# retrying a failed task, measured from when the task was first

202

# attempted. Once `max_retry_duration` time has passed *and* the

203

# task has been attempted max_attempts

204

# times, no further attempts will be made and the task will be

205

# deleted.

206

#

207

# If zero, then the task age is unlimited.

208

#

209

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_retry_duration` will be truncated to the nearest second.

214

#

215

# This field has the same meaning as

216

# [task_age_limit in

217

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

218

"maxAttempts": 42, # Number of attempts per task.

219

#

220

# Cloud Tasks will attempt the task `max_attempts` times (that is, if the

221

# first attempt fails, then there will be `max_attempts - 1` retries). Must

222

# be >= -1.

223

#

224

# If unspecified when the queue is created, Cloud Tasks will pick the

225

# default.

226

#

227

# -1 indicates unlimited attempts.

228

#

229

# This field has the same meaning as

230

# [task_retry_limit in

231

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

232

"maxDoublings": 42, # The time between retries will double `max_doublings` times.

233

#

234

# A task's retry interval starts at

235

# min_backoff, then doubles

236

# `max_doublings` times, then increases linearly, and finally

237

# retries at intervals of

238

# max_backoff up to

239

# max_attempts times.

240

#

241

# For example, if min_backoff is 10s,

242

# max_backoff is 300s, and

243

# `max_doublings` is 3, then the a task will first be retried in

244

# 10s. The retry interval will double three times, and then

245

# increase linearly by 2^3 * 10s. Finally, the task will retry at

246

# intervals of max_backoff until the

247

# task has been attempted max_attempts

248

# times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s,

249

# 240s, 300s, 300s, ....

250

#

251

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# This field has the same meaning as

256

# [max_doublings in

257

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

258

},

259

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

260

#

261

# `state` can only be changed by called

262

# PauseQueue,

263

# ResumeQueue, or uploading

264

# [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref).

265

# UpdateQueue cannot be used to change `state`.

266

"name": "A String", # Caller-specified and required in CreateQueue,

Bu Sun Kim

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

[diff] [blame]

267

# after which it becomes output only.

#

# The queue name.

#

# The queue name must have the following format:

272

# `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID`

273

#

274

# * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]),

275

# hyphens (-), colons (:), or periods (.).

276

# For more information, see

277

# [Identifying

278

# projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)

Bu Sun Kim

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

[diff] [blame^]

279

# * `LOCATION_ID` is the canonical ID for the queue's location.

Bu Sun Kim

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

[diff] [blame]

280

# The list of available locations can be obtained by calling

281

# ListLocations.

282

# For more information, see https://cloud.google.com/about/locations/.

283

# * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or

284

# hyphens (-). The maximum length is 100 characters.

Bu Sun Kim

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

[diff] [blame^]

285

"rateLimits": { # Rate limits. # Rate limits for task dispatches.

Bu Sun Kim

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

[diff] [blame]

286

#

287

# rate_limits and retry_config are

288

# related because they both control task attempts. However they control task

289

# attempts in different ways:

290

#

291

# * rate_limits controls the total rate of

292

# dispatches from a queue (i.e. all traffic dispatched from the

293

# queue, regardless of whether the dispatch is from a first

294

# attempt or a retry).

295

# * retry_config controls what happens to

296

# particular a task after its first attempt fails. That is,

297

# retry_config controls task retries (the

298

# second attempt, third attempt, etc).

299

#

Bu Sun Kim

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

[diff] [blame^]

300

# The queue's actual dispatch rate is the result of:

Bu Sun Kim

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

[diff] [blame]

301

#

302

# * Number of tasks in the queue

303

# * User-specified throttling: rate_limits,

304

# retry_config, and the

Bu Sun Kim

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

[diff] [blame^]

305

# queue's state.

Bu Sun Kim

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

[diff] [blame]

306

# * System throttling due to `429` (Too Many Requests) or `503` (Service

307

# Unavailable) responses from the worker, high error rates, or to smooth

308

# sudden large traffic spikes.

309

#

310

# This message determines the maximum rate that tasks can be dispatched by a

311

# queue, regardless of whether the dispatch is a first task attempt or a retry.

312

#

313

# Note: The debugging command, RunTask, will run a task

314

# even if the queue has reached its RateLimits.

Bu Sun Kim

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

[diff] [blame^]

315

"maxConcurrentDispatches": 42, # The maximum number of concurrent tasks that Cloud Tasks allows

Bu Sun Kim

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

[diff] [blame]

316

# to be dispatched for this queue. After this threshold has been

317

# reached, Cloud Tasks stops dispatching tasks until the number of

318

# concurrent requests decreases.

319

#

320

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# The maximum allowed value is 5,000.

325

#

326

#

327

# This field has the same meaning as

328

# [max_concurrent_requests in

329

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests).

Bu Sun Kim

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

[diff] [blame^]

330

"maxDispatchesPerSecond": 3.14, # The maximum rate at which tasks are dispatched from this queue.

331

#

332

# If unspecified when the queue is created, Cloud Tasks will pick the

333

# default.

334

#

335

# * The maximum allowed value is 500.

336

#

337

#

338

# This field has the same meaning as

339

# [rate in

340

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate).

341

"maxBurstSize": 42, # Output only. The max burst size.

Bu Sun Kim

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

[diff] [blame]

342

#

343

# Max burst size limits how fast tasks in queue are processed when

344

# many tasks are in the queue and the rate is high. This field

345

# allows the queue to have a high rate so processing starts shortly

346

# after a task is enqueued, but still limits resource usage when

347

# many tasks are enqueued in a short period of time.

348

#

349

# The [token bucket](https://wikipedia.org/wiki/Token_Bucket)

350

# algorithm is used to control the rate of task dispatches. Each

351

# queue has a token bucket that holds tokens, up to the maximum

352

# specified by `max_burst_size`. Each time a task is dispatched, a

353

# token is removed from the bucket. Tasks will be dispatched until

Bu Sun Kim

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

[diff] [blame^]

354

# the queue's bucket runs out of tokens. The bucket will be

Bu Sun Kim

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

[diff] [blame]

355

# continuously refilled with new tokens based on

356

# max_dispatches_per_second.

357

#

358

# Cloud Tasks will pick the value of `max_burst_size` based on the

359

# value of

360

# max_dispatches_per_second.

361

#

Dan O'Meara

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

[diff] [blame]

362

# For queues that were created or updated using

Bu Sun Kim

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

[diff] [blame]

363

# `queue.yaml/xml`, `max_burst_size` is equal to

364

# [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size).

365

# Since `max_burst_size` is output only, if

366

# UpdateQueue is called on a queue

367

# created by `queue.yaml/xml`, `max_burst_size` will be reset based

368

# on the value of

369

# max_dispatches_per_second,

370

# regardless of whether

371

# max_dispatches_per_second

372

# is updated.

Bu Sun Kim

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

[diff] [blame]

373

},

Bu Sun Kim

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

[diff] [blame^]

374

"stackdriverLoggingConfig": { # Configuration options for writing logs to # Configuration options for writing logs to

375

# [Stackdriver Logging](https://cloud.google.com/logging/docs/). If this

376

# field is unset, then no logs are written.

377

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

378

"samplingRatio": 3.14, # Specifies the fraction of operations to write to

379

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

380

# This field may contain any value between 0.0 and 1.0, inclusive.

381

# 0.0 is the default and means that no operations are logged.

382

},

383

"appEngineRoutingOverride": { # App Engine Routing. # Overrides for

Bu Sun Kim

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

[diff] [blame]

384

# task-level app_engine_routing.

385

# These settings apply only to

386

# App Engine tasks in this queue.

Dan O'Meara

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

[diff] [blame]

387

# Http tasks are not affected.

Bu Sun Kim

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

[diff] [blame]

388

#

389

# If set, `app_engine_routing_override` is used for all

390

# App Engine tasks in the queue, no matter what the

391

# setting is for the

392

# task-level app_engine_routing.

393

#

394

# Defines routing characteristics specific to App Engine - service, version,

395

# and instance.

396

#

397

# For more information about services, versions, and instances see

398

# [An Overview of App

399

# Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),

400

# [Microservices Architecture on Google App

401

# Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine),

402

# [App Engine Standard request

403

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed),

404

# and [App Engine Flex request

405

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

Dan O'Meara

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

[diff] [blame]

406

#

407

# Using AppEngineRouting requires

408

# [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)

409

# Google IAM permission for the project

410

# and the following scope:

411

#

412

# `https://www.googleapis.com/auth/cloud-platform`

Bu Sun Kim

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

[diff] [blame^]

413

"service": "A String", # App service.

Bu Sun Kim

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

[diff] [blame]

414

#

415

# By default, the task is sent to the service which is the default

416

# service when the task is attempted.

417

#

418

# For some queues or tasks which were created using the App Engine

419

# Task Queue API, host is not parsable

420

# into service,

421

# version, and

422

# instance. For example, some tasks

423

# which were created using the App Engine SDK use a custom domain

424

# name; custom domains are not parsed by Cloud Tasks. If

425

# host is not parsable, then

426

# service,

427

# version, and

428

# instance are the empty string.

Bu Sun Kim

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

[diff] [blame^]

429

"instance": "A String", # App instance.

Dan O'Meara

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

[diff] [blame]

430

#

Bu Sun Kim

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

[diff] [blame^]

431

# By default, the task is sent to an instance which is available when

432

# the task is attempted.

Bu Sun Kim

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

[diff] [blame]

433

#

Bu Sun Kim

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

[diff] [blame^]

434

# Requests can only be sent to a specific instance if

435

# [manual scaling is used in App Engine

436

# Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes).

437

# App Engine Flex does not support instances. For more information, see

438

# [App Engine Standard request

439

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)

440

# and [App Engine Flex request

441

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

442

"version": "A String", # App version.

Bu Sun Kim

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

[diff] [blame]

443

#

Bu Sun Kim

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

[diff] [blame^]

444

# By default, the task is sent to the version which is the default

445

# version when the task is attempted.

Bu Sun Kim

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

[diff] [blame]

446

#

Bu Sun Kim

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

[diff] [blame^]

447

# For some queues or tasks which were created using the App Engine

448

# Task Queue API, host is not parsable

449

# into service,

450

# version, and

451

# instance. For example, some tasks

452

# which were created using the App Engine SDK use a custom domain

453

# name; custom domains are not parsed by Cloud Tasks. If

454

# host is not parsable, then

455

# service,

456

# version, and

457

# instance are the empty string.

458

"host": "A String", # Output only. The host that the task is sent to.

Bu Sun Kim

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

[diff] [blame]

459

#

Bu Sun Kim

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

[diff] [blame^]

460

# The host is constructed from the domain name of the app associated with

461

# the queue's project ID (for example <app-id>.appspot.com), and the

462

# service, version,

463

# and instance. Tasks which were created using

464

# the App Engine SDK might have a custom domain name.

Bu Sun Kim

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

[diff] [blame]

465

#

Bu Sun Kim

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

[diff] [blame^]

466

# For more information, see

467

# [How Requests are

468

# Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed).

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:

479

480

{ # A queue is a container of related tasks. Queues are configured to manage

481

# how those tasks are dispatched. Configurable properties include rate limits,

482

# retry options, queue types, and others.

Bu Sun Kim

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

[diff] [blame^]

483

"purgeTime": "A String", # Output only. The last time this queue was purged.

484

#

485

# All tasks that were created before this time

486

# were purged.

487

#

488

# A queue can be purged using PurgeQueue, the

489

# [App Engine Task Queue SDK, or the Cloud

490

# Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue).

491

#

492

# Purge time will be truncated to the nearest microsecond. Purge

493

# time will be unset if the queue has never been purged.

494

"retryConfig": { # Retry config. # Settings that determine the retry behavior.

495

#

496

# * For tasks created using Cloud Tasks: the queue-level retry settings

497

# apply to all tasks in the queue that were created using Cloud Tasks.

498

# Retry settings cannot be set on individual tasks.

499

# * For tasks created using the App Engine SDK: the queue-level retry

500

# settings apply to all tasks in the queue which do not have retry settings

501

# explicitly set on the task and were created by the App Engine SDK. See

502

# [App Engine

503

# documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks).

504

#

505

# These settings determine when a failed task attempt is retried.

506

"minBackoff": "A String", # A task will be scheduled for retry between

507

# min_backoff and

508

# max_backoff duration after it fails,

509

# if the queue's RetryConfig specifies that the task should be

510

# retried.

511

#

512

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `min_backoff` will be truncated to the nearest second.

517

#

518

# This field has the same meaning as

519

# [min_backoff_seconds in

520

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

521

"maxBackoff": "A String", # A task will be scheduled for retry between

522

# min_backoff and

523

# max_backoff duration after it fails,

524

# if the queue's RetryConfig specifies that the task should be

525

# retried.

526

#

527

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_backoff` will be truncated to the nearest second.

532

#

533

# This field has the same meaning as

534

# [max_backoff_seconds in

535

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

536

"maxRetryDuration": "A String", # If positive, `max_retry_duration` specifies the time limit for

537

# retrying a failed task, measured from when the task was first

538

# attempted. Once `max_retry_duration` time has passed *and* the

539

# task has been attempted max_attempts

540

# times, no further attempts will be made and the task will be

541

# deleted.

542

#

543

# If zero, then the task age is unlimited.

544

#

545

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_retry_duration` will be truncated to the nearest second.

550

#

551

# This field has the same meaning as

552

# [task_age_limit in

553

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

554

"maxAttempts": 42, # Number of attempts per task.

555

#

556

# Cloud Tasks will attempt the task `max_attempts` times (that is, if the

557

# first attempt fails, then there will be `max_attempts - 1` retries). Must

558

# be >= -1.

559

#

560

# If unspecified when the queue is created, Cloud Tasks will pick the

561

# default.

562

#

563

# -1 indicates unlimited attempts.

564

#

565

# This field has the same meaning as

566

# [task_retry_limit in

567

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

568

"maxDoublings": 42, # The time between retries will double `max_doublings` times.

569

#

570

# A task's retry interval starts at

571

# min_backoff, then doubles

572

# `max_doublings` times, then increases linearly, and finally

573

# retries at intervals of

574

# max_backoff up to

575

# max_attempts times.

576

#

577

# For example, if min_backoff is 10s,

578

# max_backoff is 300s, and

579

# `max_doublings` is 3, then the a task will first be retried in

580

# 10s. The retry interval will double three times, and then

581

# increase linearly by 2^3 * 10s. Finally, the task will retry at

582

# intervals of max_backoff until the

583

# task has been attempted max_attempts

584

# times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s,

585

# 240s, 300s, 300s, ....

586

#

587

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# This field has the same meaning as

592

# [max_doublings in

593

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

594

},

595

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

596

#

597

# `state` can only be changed by called

598

# PauseQueue,

599

# ResumeQueue, or uploading

600

# [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref).

601

# UpdateQueue cannot be used to change `state`.

602

"name": "A String", # Caller-specified and required in CreateQueue,

Bu Sun Kim

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

[diff] [blame]

603

# after which it becomes output only.

#

# The queue name.

#

# The queue name must have the following format:

608

# `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID`

609

#

610

# * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]),

611

# hyphens (-), colons (:), or periods (.).

612

# For more information, see

613

# [Identifying

614

# projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)

Bu Sun Kim

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

[diff] [blame^]

615

# * `LOCATION_ID` is the canonical ID for the queue's location.

Bu Sun Kim

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

[diff] [blame]

616

# The list of available locations can be obtained by calling

617

# ListLocations.

618

# For more information, see https://cloud.google.com/about/locations/.

619

# * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or

620

# hyphens (-). The maximum length is 100 characters.

Bu Sun Kim

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

[diff] [blame^]

621

"rateLimits": { # Rate limits. # Rate limits for task dispatches.

Bu Sun Kim

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

[diff] [blame]

622

#

623

# rate_limits and retry_config are

624

# related because they both control task attempts. However they control task

625

# attempts in different ways:

626

#

627

# * rate_limits controls the total rate of

628

# dispatches from a queue (i.e. all traffic dispatched from the

629

# queue, regardless of whether the dispatch is from a first

630

# attempt or a retry).

631

# * retry_config controls what happens to

632

# particular a task after its first attempt fails. That is,

633

# retry_config controls task retries (the

634

# second attempt, third attempt, etc).

635

#

Bu Sun Kim

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

[diff] [blame^]

636

# The queue's actual dispatch rate is the result of:

Bu Sun Kim

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

[diff] [blame]

637

#

638

# * Number of tasks in the queue

639

# * User-specified throttling: rate_limits,

640

# retry_config, and the

Bu Sun Kim

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

[diff] [blame^]

641

# queue's state.

Bu Sun Kim

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

[diff] [blame]

642

# * System throttling due to `429` (Too Many Requests) or `503` (Service

643

# Unavailable) responses from the worker, high error rates, or to smooth

644

# sudden large traffic spikes.

645

#

646

# This message determines the maximum rate that tasks can be dispatched by a

647

# queue, regardless of whether the dispatch is a first task attempt or a retry.

648

#

649

# Note: The debugging command, RunTask, will run a task

650

# even if the queue has reached its RateLimits.

Bu Sun Kim

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

[diff] [blame^]

651

"maxConcurrentDispatches": 42, # The maximum number of concurrent tasks that Cloud Tasks allows

Bu Sun Kim

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

[diff] [blame]

652

# to be dispatched for this queue. After this threshold has been

653

# reached, Cloud Tasks stops dispatching tasks until the number of

654

# concurrent requests decreases.

655

#

656

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# The maximum allowed value is 5,000.

661

#

662

#

663

# This field has the same meaning as

664

# [max_concurrent_requests in

665

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests).

Bu Sun Kim

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

[diff] [blame^]

666

"maxDispatchesPerSecond": 3.14, # The maximum rate at which tasks are dispatched from this queue.

667

#

668

# If unspecified when the queue is created, Cloud Tasks will pick the

669

# default.

670

#

671

# * The maximum allowed value is 500.

672

#

673

#

674

# This field has the same meaning as

675

# [rate in

676

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate).

677

"maxBurstSize": 42, # Output only. The max burst size.

Bu Sun Kim

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

[diff] [blame]

678

#

679

# Max burst size limits how fast tasks in queue are processed when

680

# many tasks are in the queue and the rate is high. This field

681

# allows the queue to have a high rate so processing starts shortly

682

# after a task is enqueued, but still limits resource usage when

683

# many tasks are enqueued in a short period of time.

684

#

685

# The [token bucket](https://wikipedia.org/wiki/Token_Bucket)

686

# algorithm is used to control the rate of task dispatches. Each

687

# queue has a token bucket that holds tokens, up to the maximum

688

# specified by `max_burst_size`. Each time a task is dispatched, a

689

# token is removed from the bucket. Tasks will be dispatched until

Bu Sun Kim

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

[diff] [blame^]

690

# the queue's bucket runs out of tokens. The bucket will be

Bu Sun Kim

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

[diff] [blame]

691

# continuously refilled with new tokens based on

692

# max_dispatches_per_second.

693

#

694

# Cloud Tasks will pick the value of `max_burst_size` based on the

695

# value of

696

# max_dispatches_per_second.

697

#

Dan O'Meara

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

[diff] [blame]

698

# For queues that were created or updated using

Bu Sun Kim

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

[diff] [blame]

699

# `queue.yaml/xml`, `max_burst_size` is equal to

700

# [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size).

701

# Since `max_burst_size` is output only, if

702

# UpdateQueue is called on a queue

703

# created by `queue.yaml/xml`, `max_burst_size` will be reset based

704

# on the value of

705

# max_dispatches_per_second,

706

# regardless of whether

707

# max_dispatches_per_second

708

# is updated.

Bu Sun Kim

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

[diff] [blame]

709

},

Bu Sun Kim

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

[diff] [blame^]

710

"stackdriverLoggingConfig": { # Configuration options for writing logs to # Configuration options for writing logs to

711

# [Stackdriver Logging](https://cloud.google.com/logging/docs/). If this

712

# field is unset, then no logs are written.

713

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

714

"samplingRatio": 3.14, # Specifies the fraction of operations to write to

715

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

716

# This field may contain any value between 0.0 and 1.0, inclusive.

717

# 0.0 is the default and means that no operations are logged.

718

},

719

"appEngineRoutingOverride": { # App Engine Routing. # Overrides for

Bu Sun Kim

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

[diff] [blame]

720

# task-level app_engine_routing.

721

# These settings apply only to

722

# App Engine tasks in this queue.

Dan O'Meara

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

[diff] [blame]

723

# Http tasks are not affected.

Bu Sun Kim

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

[diff] [blame]

724

#

725

# If set, `app_engine_routing_override` is used for all

726

# App Engine tasks in the queue, no matter what the

727

# setting is for the

728

# task-level app_engine_routing.

729

#

730

# Defines routing characteristics specific to App Engine - service, version,

731

# and instance.

732

#

733

# For more information about services, versions, and instances see

734

# [An Overview of App

735

# Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),

736

# [Microservices Architecture on Google App

737

# Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine),

738

# [App Engine Standard request

739

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed),

740

# and [App Engine Flex request

741

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

Dan O'Meara

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

[diff] [blame]

742

#

743

# Using AppEngineRouting requires

744

# [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)

745

# Google IAM permission for the project

746

# and the following scope:

747

#

748

# `https://www.googleapis.com/auth/cloud-platform`

Bu Sun Kim

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

[diff] [blame^]

749

"service": "A String", # App service.

Bu Sun Kim

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

[diff] [blame]

750

#

751

# By default, the task is sent to the service which is the default

752

# service when the task is attempted.

753

#

754

# For some queues or tasks which were created using the App Engine

755

# Task Queue API, host is not parsable

756

# into service,

757

# version, and

758

# instance. For example, some tasks

759

# which were created using the App Engine SDK use a custom domain

760

# name; custom domains are not parsed by Cloud Tasks. If

761

# host is not parsable, then

762

# service,

763

# version, and

764

# instance are the empty string.

Bu Sun Kim

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

[diff] [blame^]

765

"instance": "A String", # App instance.

Dan O'Meara

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

[diff] [blame]

766

#

Bu Sun Kim

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

[diff] [blame^]

767

# By default, the task is sent to an instance which is available when

768

# the task is attempted.

Bu Sun Kim

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

[diff] [blame]

769

#

Bu Sun Kim

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

[diff] [blame^]

770

# Requests can only be sent to a specific instance if

771

# [manual scaling is used in App Engine

772

# Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes).

773

# App Engine Flex does not support instances. For more information, see

774

# [App Engine Standard request

775

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)

776

# and [App Engine Flex request

777

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

778

"version": "A String", # App version.

Bu Sun Kim

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

[diff] [blame]

779

#

Bu Sun Kim

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

[diff] [blame^]

780

# By default, the task is sent to the version which is the default

781

# version when the task is attempted.

Bu Sun Kim

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

[diff] [blame]

782

#

Bu Sun Kim

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

[diff] [blame^]

783

# For some queues or tasks which were created using the App Engine

784

# Task Queue API, host is not parsable

785

# into service,

786

# version, and

787

# instance. For example, some tasks

788

# which were created using the App Engine SDK use a custom domain

789

# name; custom domains are not parsed by Cloud Tasks. If

790

# host is not parsable, then

791

# service,

792

# version, and

793

# instance are the empty string.

794

"host": "A String", # Output only. The host that the task is sent to.

Bu Sun Kim

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

[diff] [blame]

795

#

Bu Sun Kim

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

[diff] [blame^]

796

# The host is constructed from the domain name of the app associated with

797

# the queue's project ID (for example <app-id>.appspot.com), and the

798

# service, version,

799

# and instance. Tasks which were created using

800

# the App Engine SDK might have a custom domain name.

Bu Sun Kim

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

[diff] [blame]

801

#

Bu Sun Kim

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

[diff] [blame^]

802

# For more information, see

803

# [How Requests are

804

# Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed).

Bu Sun Kim

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

[diff] [blame]

},

}</pre>

</div>

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

811

<pre>Deletes a queue.

812

813

This command will delete the queue even if it has tasks in it.

814

Bu Sun Kim

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

[diff] [blame^]

815

Note: If you delete a queue, a queue with the same name can't be created

Bu Sun Kim

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

[diff] [blame]

816

for 7 days.

817

818

WARNING: Using this method may have unintended side effects if you are

819

using an App Engine `queue.yaml` or `queue.xml` file to manage your queues.

820

Read

821

[Overview of Queue Management and

822

queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using

823

this method.

824

825

Args:

Dan O'Meara

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

[diff] [blame]

826

Bu Sun Kim

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

[diff] [blame]

827

`projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` (required)

828

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

835

836

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

837

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

838

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

839

#

840

# service Foo {

841

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

842

# }

843

#

844

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

}</pre>

</div>

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

850

<pre>Gets a queue.

851

852

Args:

Dan O'Meara

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

[diff] [blame]

853

Bu Sun Kim

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

[diff] [blame]

854

`projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` (required)

855

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

862

863

{ # A queue is a container of related tasks. Queues are configured to manage

864

# how those tasks are dispatched. Configurable properties include rate limits,

865

# retry options, queue types, and others.

Bu Sun Kim

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

[diff] [blame^]

866

"purgeTime": "A String", # Output only. The last time this queue was purged.

867

#

868

# All tasks that were created before this time

869

# were purged.

870

#

871

# A queue can be purged using PurgeQueue, the

872

# [App Engine Task Queue SDK, or the Cloud

873

# Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue).

874

#

875

# Purge time will be truncated to the nearest microsecond. Purge

876

# time will be unset if the queue has never been purged.

877

"retryConfig": { # Retry config. # Settings that determine the retry behavior.

878

#

879

# * For tasks created using Cloud Tasks: the queue-level retry settings

880

# apply to all tasks in the queue that were created using Cloud Tasks.

881

# Retry settings cannot be set on individual tasks.

882

# * For tasks created using the App Engine SDK: the queue-level retry

883

# settings apply to all tasks in the queue which do not have retry settings

884

# explicitly set on the task and were created by the App Engine SDK. See

885

# [App Engine

886

# documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks).

887

#

888

# These settings determine when a failed task attempt is retried.

889

"minBackoff": "A String", # A task will be scheduled for retry between

890

# min_backoff and

891

# max_backoff duration after it fails,

892

# if the queue's RetryConfig specifies that the task should be

893

# retried.

894

#

895

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `min_backoff` will be truncated to the nearest second.

900

#

901

# This field has the same meaning as

902

# [min_backoff_seconds in

903

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

904

"maxBackoff": "A String", # A task will be scheduled for retry between

905

# min_backoff and

906

# max_backoff duration after it fails,

907

# if the queue's RetryConfig specifies that the task should be

908

# retried.

909

#

910

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_backoff` will be truncated to the nearest second.

915

#

916

# This field has the same meaning as

917

# [max_backoff_seconds in

918

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

919

"maxRetryDuration": "A String", # If positive, `max_retry_duration` specifies the time limit for

920

# retrying a failed task, measured from when the task was first

921

# attempted. Once `max_retry_duration` time has passed *and* the

922

# task has been attempted max_attempts

923

# times, no further attempts will be made and the task will be

924

# deleted.

925

#

926

# If zero, then the task age is unlimited.

927

#

928

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_retry_duration` will be truncated to the nearest second.

933

#

934

# This field has the same meaning as

935

# [task_age_limit in

936

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

937

"maxAttempts": 42, # Number of attempts per task.

938

#

939

# Cloud Tasks will attempt the task `max_attempts` times (that is, if the

940

# first attempt fails, then there will be `max_attempts - 1` retries). Must

941

# be >= -1.

942

#

943

# If unspecified when the queue is created, Cloud Tasks will pick the

944

# default.

945

#

946

# -1 indicates unlimited attempts.

947

#

948

# This field has the same meaning as

949

# [task_retry_limit in

950

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

951

"maxDoublings": 42, # The time between retries will double `max_doublings` times.

952

#

953

# A task's retry interval starts at

954

# min_backoff, then doubles

955

# `max_doublings` times, then increases linearly, and finally

956

# retries at intervals of

957

# max_backoff up to

958

# max_attempts times.

959

#

960

# For example, if min_backoff is 10s,

961

# max_backoff is 300s, and

962

# `max_doublings` is 3, then the a task will first be retried in

963

# 10s. The retry interval will double three times, and then

964

# increase linearly by 2^3 * 10s. Finally, the task will retry at

965

# intervals of max_backoff until the

966

# task has been attempted max_attempts

967

# times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s,

968

# 240s, 300s, 300s, ....

969

#

970

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# This field has the same meaning as

975

# [max_doublings in

976

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

977

},

978

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

979

#

980

# `state` can only be changed by called

981

# PauseQueue,

982

# ResumeQueue, or uploading

983

# [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref).

984

# UpdateQueue cannot be used to change `state`.

985

"name": "A String", # Caller-specified and required in CreateQueue,

Bu Sun Kim

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

[diff] [blame]

986

# after which it becomes output only.

#

# The queue name.

#

# The queue name must have the following format:

991

# `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID`

992

#

993

# * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]),

994

# hyphens (-), colons (:), or periods (.).

995

# For more information, see

996

# [Identifying

997

# projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)

Bu Sun Kim

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

[diff] [blame^]

998

# * `LOCATION_ID` is the canonical ID for the queue's location.

Bu Sun Kim

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

[diff] [blame]

999

# The list of available locations can be obtained by calling

1000

# ListLocations.

1001

# For more information, see https://cloud.google.com/about/locations/.

1002

# * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or

1003

# hyphens (-). The maximum length is 100 characters.

Bu Sun Kim

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

[diff] [blame^]

1004

"rateLimits": { # Rate limits. # Rate limits for task dispatches.

Bu Sun Kim

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

[diff] [blame]

1005

#

1006

# rate_limits and retry_config are

1007

# related because they both control task attempts. However they control task

1008

# attempts in different ways:

1009

#

1010

# * rate_limits controls the total rate of

1011

# dispatches from a queue (i.e. all traffic dispatched from the

1012

# queue, regardless of whether the dispatch is from a first

1013

# attempt or a retry).

1014

# * retry_config controls what happens to

1015

# particular a task after its first attempt fails. That is,

1016

# retry_config controls task retries (the

1017

# second attempt, third attempt, etc).

1018

#

Bu Sun Kim

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

[diff] [blame^]

1019

# The queue's actual dispatch rate is the result of:

Bu Sun Kim

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

[diff] [blame]

1020

#

1021

# * Number of tasks in the queue

1022

# * User-specified throttling: rate_limits,

1023

# retry_config, and the

Bu Sun Kim

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

[diff] [blame^]

1024

# queue's state.

Bu Sun Kim

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

[diff] [blame]

1025

# * System throttling due to `429` (Too Many Requests) or `503` (Service

1026

# Unavailable) responses from the worker, high error rates, or to smooth

1027

# sudden large traffic spikes.

1028

#

1029

# This message determines the maximum rate that tasks can be dispatched by a

1030

# queue, regardless of whether the dispatch is a first task attempt or a retry.

1031

#

1032

# Note: The debugging command, RunTask, will run a task

1033

# even if the queue has reached its RateLimits.

Bu Sun Kim

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

[diff] [blame^]

1034

"maxConcurrentDispatches": 42, # The maximum number of concurrent tasks that Cloud Tasks allows

Bu Sun Kim

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

[diff] [blame]

1035

# to be dispatched for this queue. After this threshold has been

1036

# reached, Cloud Tasks stops dispatching tasks until the number of

1037

# concurrent requests decreases.

1038

#

1039

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# The maximum allowed value is 5,000.

1044

#

1045

#

1046

# This field has the same meaning as

1047

# [max_concurrent_requests in

1048

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests).

Bu Sun Kim

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

[diff] [blame^]

1049

"maxDispatchesPerSecond": 3.14, # The maximum rate at which tasks are dispatched from this queue.

1050

#

1051

# If unspecified when the queue is created, Cloud Tasks will pick the

1052

# default.

1053

#

1054

# * The maximum allowed value is 500.

1055

#

1056

#

1057

# This field has the same meaning as

1058

# [rate in

1059

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate).

1060

"maxBurstSize": 42, # Output only. The max burst size.

Bu Sun Kim

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

[diff] [blame]

1061

#

1062

# Max burst size limits how fast tasks in queue are processed when

1063

# many tasks are in the queue and the rate is high. This field

1064

# allows the queue to have a high rate so processing starts shortly

1065

# after a task is enqueued, but still limits resource usage when

1066

# many tasks are enqueued in a short period of time.

1067

#

1068

# The [token bucket](https://wikipedia.org/wiki/Token_Bucket)

1069

# algorithm is used to control the rate of task dispatches. Each

1070

# queue has a token bucket that holds tokens, up to the maximum

1071

# specified by `max_burst_size`. Each time a task is dispatched, a

1072

# token is removed from the bucket. Tasks will be dispatched until

Bu Sun Kim

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

[diff] [blame^]

1073

# the queue's bucket runs out of tokens. The bucket will be

Bu Sun Kim

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

[diff] [blame]

1074

# continuously refilled with new tokens based on

1075

# max_dispatches_per_second.

1076

#

1077

# Cloud Tasks will pick the value of `max_burst_size` based on the

1078

# value of

1079

# max_dispatches_per_second.

1080

#

Dan O'Meara

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

[diff] [blame]

1081

# For queues that were created or updated using

Bu Sun Kim

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

[diff] [blame]

1082

# `queue.yaml/xml`, `max_burst_size` is equal to

1083

# [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size).

1084

# Since `max_burst_size` is output only, if

1085

# UpdateQueue is called on a queue

1086

# created by `queue.yaml/xml`, `max_burst_size` will be reset based

1087

# on the value of

1088

# max_dispatches_per_second,

1089

# regardless of whether

1090

# max_dispatches_per_second

1091

# is updated.

Bu Sun Kim

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

[diff] [blame]

1092

},

Bu Sun Kim

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

[diff] [blame^]

1093

"stackdriverLoggingConfig": { # Configuration options for writing logs to # Configuration options for writing logs to

1094

# [Stackdriver Logging](https://cloud.google.com/logging/docs/). If this

1095

# field is unset, then no logs are written.

1096

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

1097

"samplingRatio": 3.14, # Specifies the fraction of operations to write to

1098

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

1099

# This field may contain any value between 0.0 and 1.0, inclusive.

1100

# 0.0 is the default and means that no operations are logged.

1101

},

1102

"appEngineRoutingOverride": { # App Engine Routing. # Overrides for

Bu Sun Kim

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

[diff] [blame]

1103

# task-level app_engine_routing.

1104

# These settings apply only to

1105

# App Engine tasks in this queue.

Dan O'Meara

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

[diff] [blame]

1106

# Http tasks are not affected.

Bu Sun Kim

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

[diff] [blame]

1107

#

1108

# If set, `app_engine_routing_override` is used for all

1109

# App Engine tasks in the queue, no matter what the

1110

# setting is for the

1111

# task-level app_engine_routing.

1112

#

1113

# Defines routing characteristics specific to App Engine - service, version,

1114

# and instance.

1115

#

1116

# For more information about services, versions, and instances see

1117

# [An Overview of App

1118

# Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),

1119

# [Microservices Architecture on Google App

1120

# Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine),

1121

# [App Engine Standard request

1122

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed),

1123

# and [App Engine Flex request

1124

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

Dan O'Meara

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

[diff] [blame]

1125

#

1126

# Using AppEngineRouting requires

1127

# [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)

1128

# Google IAM permission for the project

1129

# and the following scope:

1130

#

1131

# `https://www.googleapis.com/auth/cloud-platform`

Bu Sun Kim

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

[diff] [blame^]

1132

"service": "A String", # App service.

Bu Sun Kim

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

[diff] [blame]

1133

#

1134

# By default, the task is sent to the service which is the default

1135

# service when the task is attempted.

1136

#

1137

# For some queues or tasks which were created using the App Engine

1138

# Task Queue API, host is not parsable

1139

# into service,

1140

# version, and

1141

# instance. For example, some tasks

1142

# which were created using the App Engine SDK use a custom domain

1143

# name; custom domains are not parsed by Cloud Tasks. If

1144

# host is not parsable, then

1145

# service,

1146

# version, and

1147

# instance are the empty string.

Bu Sun Kim

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

[diff] [blame^]

1148

"instance": "A String", # App instance.

Dan O'Meara

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

[diff] [blame]

1149

#

Bu Sun Kim

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

[diff] [blame^]

1150

# By default, the task is sent to an instance which is available when

1151

# the task is attempted.

Bu Sun Kim

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

[diff] [blame]

1152

#

Bu Sun Kim

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

[diff] [blame^]

1153

# Requests can only be sent to a specific instance if

1154

# [manual scaling is used in App Engine

1155

# Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes).

1156

# App Engine Flex does not support instances. For more information, see

1157

# [App Engine Standard request

1158

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)

1159

# and [App Engine Flex request

1160

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

1161

"version": "A String", # App version.

Bu Sun Kim

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

[diff] [blame]

1162

#

Bu Sun Kim

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

[diff] [blame^]

1163

# By default, the task is sent to the version which is the default

1164

# version when the task is attempted.

Bu Sun Kim

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

[diff] [blame]

1165

#

Bu Sun Kim

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

[diff] [blame^]

1166

# For some queues or tasks which were created using the App Engine

1167

# Task Queue API, host is not parsable

1168

# into service,

1169

# version, and

1170

# instance. For example, some tasks

1171

# which were created using the App Engine SDK use a custom domain

1172

# name; custom domains are not parsed by Cloud Tasks. If

1173

# host is not parsable, then

1174

# service,

1175

# version, and

1176

# instance are the empty string.

1177

"host": "A String", # Output only. The host that the task is sent to.

Bu Sun Kim

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

[diff] [blame]

1178

#

Bu Sun Kim

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

[diff] [blame^]

1179

# The host is constructed from the domain name of the app associated with

1180

# the queue's project ID (for example <app-id>.appspot.com), and the

1181

# service, version,

1182

# and instance. Tasks which were created using

1183

# the App Engine SDK might have a custom domain name.

Bu Sun Kim

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

[diff] [blame]

1184

#

Bu Sun Kim

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

[diff] [blame^]

1185

# For more information, see

1186

# [How Requests are

1187

# Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed).

Bu Sun Kim

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

[diff] [blame]

},

}</pre>

</div>

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

1194

<pre>Gets the access control policy for a Queue.

1195

Returns an empty policy if the resource exists and does not have a policy

1196

set.

1197

1198

Authorization requires the following

1199

[Google IAM](https://cloud.google.com/iam) permission on the specified

1200

resource parent:

1201

1202

* `cloudtasks.queues.getIamPolicy`

1203

1204

Args:

1205

resource: string, REQUIRED: The resource for which the policy is being requested.

1206

See the operation documentation for the appropriate value for this field. (required)

1207

body: object, The request body.

1208

The object takes the form of:

1209

1210

{ # Request message for `GetIamPolicy` method.

Bu Sun Kim

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

[diff] [blame^]

1211

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

Dan O'Meara

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

[diff] [blame]

1212

# `GetIamPolicy`.

Bu Sun Kim

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

[diff] [blame^]

1213

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

Dan O'Meara

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

[diff] [blame]

1214

#

1215

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

1216

# rejected.

1217

#

1218

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

1219

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

1220

# leave the field unset.

Bu Sun Kim

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

[diff] [blame^]

1221

#

1222

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

1223

# [IAM

1224

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

Dan O'Meara

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

[diff] [blame]

1225

},

Bu Sun Kim

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

[diff] [blame]

1226

}

1227

1228

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1235

Dan O'Meara

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

[diff] [blame]

1236

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

1237

# controls for Google Cloud resources.

Bu Sun Kim

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

[diff] [blame]

1238

#

1239

#

Dan O'Meara

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

[diff] [blame]

1240

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

1241

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

1242

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

1243

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

1244

# custom role.

Bu Sun Kim

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

[diff] [blame]

1245

#

Bu Sun Kim

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

[diff] [blame^]

1246

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

1247

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

1248

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

1249

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

1250

# resources support conditions in their IAM policies, see the

1251

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

Dan O'Meara

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

[diff] [blame]

1252

#

1253

# **JSON example:**

Bu Sun Kim

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

[diff] [blame]

1254

#

1255

# {

Bu Sun Kim

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

[diff] [blame^]

1256

# "bindings": [

Bu Sun Kim

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

[diff] [blame]

1257

# {

Bu Sun Kim

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

[diff] [blame^]

1258

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

1259

# "members": [

1260

# "user:mike@example.com",

1261

# "group:admins@example.com",

1262

# "domain:google.com",

1263

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

Bu Sun Kim

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

[diff] [blame]

1264

# ]

1265

# },

1266

# {

Bu Sun Kim

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

[diff] [blame^]

1267

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

1268

# "members": [

1269

# "user:eve@example.com"

1270

# ],

1271

# "condition": {

1272

# "title": "expirable access",

1273

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

1274

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

Dan O'Meara

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

[diff] [blame]

1275

# }

Bu Sun Kim

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

[diff] [blame]

1276

# }

Dan O'Meara

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

[diff] [blame]

1277

# ],

Bu Sun Kim

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

[diff] [blame^]

1278

# "etag": "BwWWja0YfJA=",

1279

# "version": 3

Bu Sun Kim

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

[diff] [blame]

1280

# }

1281

#

Dan O'Meara

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

[diff] [blame]

1282

# **YAML example:**

Bu Sun Kim

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

[diff] [blame]

#

# bindings:

# - members:

# - user:mike@example.com

1287

# - group:admins@example.com

1288

# - domain:google.com

Dan O'Meara

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

[diff] [blame]

1289

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

1290

# role: roles/resourcemanager.organizationAdmin

Bu Sun Kim

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

[diff] [blame]

1291

# - members:

Dan O'Meara

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

[diff] [blame]

1292

# - user:eve@example.com

1293

# role: roles/resourcemanager.organizationViewer

1294

# condition:

1295

# title: expirable access

1296

# description: Does not grant access after Sep 2020

Bu Sun Kim

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

[diff] [blame^]

1297

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

Dan O'Meara

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

[diff] [blame]

1298

# - etag: BwWWja0YfJA=

1299

# - version: 3

Bu Sun Kim

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

[diff] [blame]

1300

#

1301

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

Dan O'Meara

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

[diff] [blame]

1302

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

Bu Sun Kim

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

[diff] [blame^]

1303

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

1304

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

1305

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

1306

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

1307

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

1308

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

1309

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

1310

#

1311

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

1312

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

1313

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

1314

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

1315

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

1316

#

1317

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

1318

# are rejected.

1319

#

1320

# Any operation that affects conditional role bindings must specify version

1321

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

1322

#

1323

# * Getting a policy that includes a conditional role binding

1324

# * Adding a conditional role binding to a policy

1325

# * Changing a conditional role binding in a policy

1326

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

1327

# that includes conditions

1328

#

1329

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

1330

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

1331

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

1332

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

1333

#

1334

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

1335

# specify any valid version or leave the field unset.

1336

#

1337

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

1338

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

1339

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

1340

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

1341

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

Bu Sun Kim

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

[diff] [blame]

1342

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

Bu Sun Kim

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

[diff] [blame^]

1343

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

Bu Sun Kim

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

[diff] [blame]

1344

# `members` can have the following values:

1345

#

1346

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

1347

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

1348

#

1349

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

1350

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

1351

#

1352

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

Dan O'Meara

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

[diff] [blame]

1353

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

Bu Sun Kim

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

[diff] [blame]

1354

#

1355

#

1356

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

1357

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

1358

#

1359

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

1360

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

1361

#

Dan O'Meara

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

[diff] [blame]

1362

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

1363

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

1364

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

1365

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

1366

# retains the role in the binding.

1367

#

1368

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

1369

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

1370

# deleted. For example,

1371

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

1372

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

1373

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

1374

# role in the binding.

1375

#

1376

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

1377

# identifier) representing a Google group that has been recently

1378

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

1379

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

1380

# recovered group retains the role in the binding.

1381

#

Bu Sun Kim

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

[diff] [blame]

1382

#

1383

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

1384

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

1385

#

Bu Sun Kim

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

[diff] [blame^]

1386

"A String",

Bu Sun Kim

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

[diff] [blame]

1387

],

Bu Sun Kim

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

[diff] [blame^]

1388

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

1389

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

1390

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

1391

#

1392

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

1393

# current request.

1394

#

1395

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

1396

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

1397

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

1398

#

1399

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

1400

# [IAM

1401

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

1402

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

1403

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

1404

#

1405

# Example (Comparison):

1406

#

1407

# title: "Summary size limit"

1408

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

1409

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

1410

#

1411

# Example (Equality):

1412

#

1413

# title: "Requestor is owner"

1414

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

1415

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

#

# Example (Logic):

#

# title: "Public documents"

1420

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

1421

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

1422

#

1423

# Example (Data Manipulation):

1424

#

1425

# title: "Notification string"

1426

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

1427

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

1428

#

1429

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

1430

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

1431

# documentation for additional information.

1432

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

1433

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

1434

# expression.

1435

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

1436

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

1437

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

1438

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

1439

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

1440

# syntax.

1441

},

Bu Sun Kim

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

[diff] [blame]

1442

},

1443

],

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

1448

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

Bu Sun Kim

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

[diff] [blame]

1449

<pre>Lists queues.

1450

1451

Queues are returned in lexicographical order.

1452

1453

Args:

Dan O'Meara

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

[diff] [blame]

1454

parent: string, Required. The location name.

Bu Sun Kim

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

[diff] [blame]

1455

For example: `projects/PROJECT_ID/locations/LOCATION_ID` (required)

Bu Sun Kim

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

[diff] [blame^]

1456

filter: string, `filter` can be used to specify a subset of queues. Any Queue

1457

field can be used as a filter and several operators as supported.

1458

For example: `<=, <, >=, >, !=, =, :`. The filter syntax is the same as

1459

described in

1460

[Stackdriver's Advanced Logs

1461

Filters](https://cloud.google.com/logging/docs/view/advanced_filters).

1462

1463

Sample filter "state: PAUSED".

1464

1465

Note that using filters might cause fewer queues than the

1466

requested page_size to be returned.

Bu Sun Kim

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

[diff] [blame]

1467

pageToken: string, A token identifying the page of results to return.

1468

1469

To request the first page results, page_token must be empty. To

1470

request the next page of results, page_token must be the value of

1471

next_page_token returned

1472

from the previous call to ListQueues

1473

method. It is an error to switch the value of the

1474

filter while iterating through pages.

Dan O'Meara

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

[diff] [blame]

1475

pageSize: integer, Requested page size.

1476

1477

The maximum page size is 9800. If unspecified, the page size will

1478

be the maximum. Fewer queues than requested might be returned,

1479

even if more queues exist; use the

1480

next_page_token in the

1481

response to determine if more queues exist.

Bu Sun Kim

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

[diff] [blame^]

1482

x__xgafv: string, V1 error format.

1483

Allowed values

1484

1 - v1 error format

1485

2 - v2 error format

Bu Sun Kim

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

[diff] [blame]

1486

1487

Returns:

1488

An object of the form:

1489

1490

{ # Response message for ListQueues.

Bu Sun Kim

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

[diff] [blame^]

1491

"queues": [ # The list of queues.

Bu Sun Kim

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

[diff] [blame]

1492

{ # A queue is a container of related tasks. Queues are configured to manage

1493

# how those tasks are dispatched. Configurable properties include rate limits,

1494

# retry options, queue types, and others.

Bu Sun Kim

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

[diff] [blame^]

1495

"purgeTime": "A String", # Output only. The last time this queue was purged.

1496

#

1497

# All tasks that were created before this time

1498

# were purged.

1499

#

1500

# A queue can be purged using PurgeQueue, the

1501

# [App Engine Task Queue SDK, or the Cloud

1502

# Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue).

1503

#

1504

# Purge time will be truncated to the nearest microsecond. Purge

1505

# time will be unset if the queue has never been purged.

1506

"retryConfig": { # Retry config. # Settings that determine the retry behavior.

1507

#

1508

# * For tasks created using Cloud Tasks: the queue-level retry settings

1509

# apply to all tasks in the queue that were created using Cloud Tasks.

1510

# Retry settings cannot be set on individual tasks.

1511

# * For tasks created using the App Engine SDK: the queue-level retry

1512

# settings apply to all tasks in the queue which do not have retry settings

1513

# explicitly set on the task and were created by the App Engine SDK. See

1514

# [App Engine

1515

# documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks).

1516

#

1517

# These settings determine when a failed task attempt is retried.

1518

"minBackoff": "A String", # A task will be scheduled for retry between

1519

# min_backoff and

1520

# max_backoff duration after it fails,

1521

# if the queue's RetryConfig specifies that the task should be

1522

# retried.

1523

#

1524

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `min_backoff` will be truncated to the nearest second.

1529

#

1530

# This field has the same meaning as

1531

# [min_backoff_seconds in

1532

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

1533

"maxBackoff": "A String", # A task will be scheduled for retry between

1534

# min_backoff and

1535

# max_backoff duration after it fails,

1536

# if the queue's RetryConfig specifies that the task should be

1537

# retried.

1538

#

1539

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_backoff` will be truncated to the nearest second.

1544

#

1545

# This field has the same meaning as

1546

# [max_backoff_seconds in

1547

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

1548

"maxRetryDuration": "A String", # If positive, `max_retry_duration` specifies the time limit for

1549

# retrying a failed task, measured from when the task was first

1550

# attempted. Once `max_retry_duration` time has passed *and* the

1551

# task has been attempted max_attempts

1552

# times, no further attempts will be made and the task will be

1553

# deleted.

1554

#

1555

# If zero, then the task age is unlimited.

1556

#

1557

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_retry_duration` will be truncated to the nearest second.

1562

#

1563

# This field has the same meaning as

1564

# [task_age_limit in

1565

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

1566

"maxAttempts": 42, # Number of attempts per task.

1567

#

1568

# Cloud Tasks will attempt the task `max_attempts` times (that is, if the

1569

# first attempt fails, then there will be `max_attempts - 1` retries). Must

1570

# be >= -1.

1571

#

1572

# If unspecified when the queue is created, Cloud Tasks will pick the

1573

# default.

1574

#

1575

# -1 indicates unlimited attempts.

1576

#

1577

# This field has the same meaning as

1578

# [task_retry_limit in

1579

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

1580

"maxDoublings": 42, # The time between retries will double `max_doublings` times.

1581

#

1582

# A task's retry interval starts at

1583

# min_backoff, then doubles

1584

# `max_doublings` times, then increases linearly, and finally

1585

# retries at intervals of

1586

# max_backoff up to

1587

# max_attempts times.

1588

#

1589

# For example, if min_backoff is 10s,

1590

# max_backoff is 300s, and

1591

# `max_doublings` is 3, then the a task will first be retried in

1592

# 10s. The retry interval will double three times, and then

1593

# increase linearly by 2^3 * 10s. Finally, the task will retry at

1594

# intervals of max_backoff until the

1595

# task has been attempted max_attempts

1596

# times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s,

1597

# 240s, 300s, 300s, ....

1598

#

1599

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# This field has the same meaning as

1604

# [max_doublings in

1605

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

1606

},

1607

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

1608

#

1609

# `state` can only be changed by called

1610

# PauseQueue,

1611

# ResumeQueue, or uploading

1612

# [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref).

1613

# UpdateQueue cannot be used to change `state`.

1614

"name": "A String", # Caller-specified and required in CreateQueue,

Bu Sun Kim

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

[diff] [blame]

1615

# after which it becomes output only.

#

# The queue name.

#

# The queue name must have the following format:

1620

# `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID`

1621

#

1622

# * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]),

1623

# hyphens (-), colons (:), or periods (.).

1624

# For more information, see

1625

# [Identifying

1626

# projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)

Bu Sun Kim

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

[diff] [blame^]

1627

# * `LOCATION_ID` is the canonical ID for the queue's location.

Bu Sun Kim

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

[diff] [blame]

1628

# The list of available locations can be obtained by calling

1629

# ListLocations.

1630

# For more information, see https://cloud.google.com/about/locations/.

1631

# * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or

1632

# hyphens (-). The maximum length is 100 characters.

Bu Sun Kim

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

[diff] [blame^]

1633

"rateLimits": { # Rate limits. # Rate limits for task dispatches.

Bu Sun Kim

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

[diff] [blame]

1634

#

1635

# rate_limits and retry_config are

1636

# related because they both control task attempts. However they control task

1637

# attempts in different ways:

1638

#

1639

# * rate_limits controls the total rate of

1640

# dispatches from a queue (i.e. all traffic dispatched from the

1641

# queue, regardless of whether the dispatch is from a first

1642

# attempt or a retry).

1643

# * retry_config controls what happens to

1644

# particular a task after its first attempt fails. That is,

1645

# retry_config controls task retries (the

1646

# second attempt, third attempt, etc).

1647

#

Bu Sun Kim

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

[diff] [blame^]

1648

# The queue's actual dispatch rate is the result of:

Bu Sun Kim

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

[diff] [blame]

1649

#

1650

# * Number of tasks in the queue

1651

# * User-specified throttling: rate_limits,

1652

# retry_config, and the

Bu Sun Kim

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

[diff] [blame^]

1653

# queue's state.

Bu Sun Kim

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

[diff] [blame]

1654

# * System throttling due to `429` (Too Many Requests) or `503` (Service

1655

# Unavailable) responses from the worker, high error rates, or to smooth

1656

# sudden large traffic spikes.

1657

#

1658

# This message determines the maximum rate that tasks can be dispatched by a

1659

# queue, regardless of whether the dispatch is a first task attempt or a retry.

1660

#

1661

# Note: The debugging command, RunTask, will run a task

1662

# even if the queue has reached its RateLimits.

Bu Sun Kim

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

[diff] [blame^]

1663

"maxConcurrentDispatches": 42, # The maximum number of concurrent tasks that Cloud Tasks allows

Bu Sun Kim

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

[diff] [blame]

1664

# to be dispatched for this queue. After this threshold has been

1665

# reached, Cloud Tasks stops dispatching tasks until the number of

1666

# concurrent requests decreases.

1667

#

1668

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# The maximum allowed value is 5,000.

1673

#

1674

#

1675

# This field has the same meaning as

1676

# [max_concurrent_requests in

1677

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests).

Bu Sun Kim

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

[diff] [blame^]

1678

"maxDispatchesPerSecond": 3.14, # The maximum rate at which tasks are dispatched from this queue.

1679

#

1680

# If unspecified when the queue is created, Cloud Tasks will pick the

1681

# default.

1682

#

1683

# * The maximum allowed value is 500.

1684

#

1685

#

1686

# This field has the same meaning as

1687

# [rate in

1688

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate).

1689

"maxBurstSize": 42, # Output only. The max burst size.

Bu Sun Kim

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

[diff] [blame]

1690

#

1691

# Max burst size limits how fast tasks in queue are processed when

1692

# many tasks are in the queue and the rate is high. This field

1693

# allows the queue to have a high rate so processing starts shortly

1694

# after a task is enqueued, but still limits resource usage when

1695

# many tasks are enqueued in a short period of time.

1696

#

1697

# The [token bucket](https://wikipedia.org/wiki/Token_Bucket)

1698

# algorithm is used to control the rate of task dispatches. Each

1699

# queue has a token bucket that holds tokens, up to the maximum

1700

# specified by `max_burst_size`. Each time a task is dispatched, a

1701

# token is removed from the bucket. Tasks will be dispatched until

Bu Sun Kim

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

[diff] [blame^]

1702

# the queue's bucket runs out of tokens. The bucket will be

Bu Sun Kim

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

[diff] [blame]

1703

# continuously refilled with new tokens based on

1704

# max_dispatches_per_second.

1705

#

1706

# Cloud Tasks will pick the value of `max_burst_size` based on the

1707

# value of

1708

# max_dispatches_per_second.

1709

#

Dan O'Meara

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

[diff] [blame]

1710

# For queues that were created or updated using

Bu Sun Kim

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

[diff] [blame]

1711

# `queue.yaml/xml`, `max_burst_size` is equal to

1712

# [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size).

1713

# Since `max_burst_size` is output only, if

1714

# UpdateQueue is called on a queue

1715

# created by `queue.yaml/xml`, `max_burst_size` will be reset based

1716

# on the value of

1717

# max_dispatches_per_second,

1718

# regardless of whether

1719

# max_dispatches_per_second

1720

# is updated.

Bu Sun Kim

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

[diff] [blame]

1721

},

Bu Sun Kim

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

[diff] [blame^]

1722

"stackdriverLoggingConfig": { # Configuration options for writing logs to # Configuration options for writing logs to

1723

# [Stackdriver Logging](https://cloud.google.com/logging/docs/). If this

1724

# field is unset, then no logs are written.

1725

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

1726

"samplingRatio": 3.14, # Specifies the fraction of operations to write to

1727

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

1728

# This field may contain any value between 0.0 and 1.0, inclusive.

1729

# 0.0 is the default and means that no operations are logged.

1730

},

1731

"appEngineRoutingOverride": { # App Engine Routing. # Overrides for

Bu Sun Kim

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

[diff] [blame]

1732

# task-level app_engine_routing.

1733

# These settings apply only to

1734

# App Engine tasks in this queue.

Dan O'Meara

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

[diff] [blame]

1735

# Http tasks are not affected.

Bu Sun Kim

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

[diff] [blame]

1736

#

1737

# If set, `app_engine_routing_override` is used for all

1738

# App Engine tasks in the queue, no matter what the

1739

# setting is for the

1740

# task-level app_engine_routing.

1741

#

1742

# Defines routing characteristics specific to App Engine - service, version,

1743

# and instance.

1744

#

1745

# For more information about services, versions, and instances see

1746

# [An Overview of App

1747

# Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),

1748

# [Microservices Architecture on Google App

1749

# Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine),

1750

# [App Engine Standard request

1751

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed),

1752

# and [App Engine Flex request

1753

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

Dan O'Meara

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

[diff] [blame]

1754

#

1755

# Using AppEngineRouting requires

1756

# [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)

1757

# Google IAM permission for the project

1758

# and the following scope:

1759

#

1760

# `https://www.googleapis.com/auth/cloud-platform`

Bu Sun Kim

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

[diff] [blame^]

1761

"service": "A String", # App service.

Bu Sun Kim

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

[diff] [blame]

1762

#

1763

# By default, the task is sent to the service which is the default

1764

# service when the task is attempted.

1765

#

1766

# For some queues or tasks which were created using the App Engine

1767

# Task Queue API, host is not parsable

1768

# into service,

1769

# version, and

1770

# instance. For example, some tasks

1771

# which were created using the App Engine SDK use a custom domain

1772

# name; custom domains are not parsed by Cloud Tasks. If

1773

# host is not parsable, then

1774

# service,

1775

# version, and

1776

# instance are the empty string.

Bu Sun Kim

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

[diff] [blame^]

1777

"instance": "A String", # App instance.

Dan O'Meara

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

[diff] [blame]

1778

#

Bu Sun Kim

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

[diff] [blame^]

1779

# By default, the task is sent to an instance which is available when

1780

# the task is attempted.

Bu Sun Kim

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

[diff] [blame]

1781

#

Bu Sun Kim

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

[diff] [blame^]

1782

# Requests can only be sent to a specific instance if

1783

# [manual scaling is used in App Engine

1784

# Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes).

1785

# App Engine Flex does not support instances. For more information, see

1786

# [App Engine Standard request

1787

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)

1788

# and [App Engine Flex request

1789

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

1790

"version": "A String", # App version.

Bu Sun Kim

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

[diff] [blame]

1791

#

Bu Sun Kim

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

[diff] [blame^]

1792

# By default, the task is sent to the version which is the default

1793

# version when the task is attempted.

Bu Sun Kim

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

[diff] [blame]

1794

#

Bu Sun Kim

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

[diff] [blame^]

1795

# For some queues or tasks which were created using the App Engine

1796

# Task Queue API, host is not parsable

1797

# into service,

1798

# version, and

1799

# instance. For example, some tasks

1800

# which were created using the App Engine SDK use a custom domain

1801

# name; custom domains are not parsed by Cloud Tasks. If

1802

# host is not parsable, then

1803

# service,

1804

# version, and

1805

# instance are the empty string.

1806

"host": "A String", # Output only. The host that the task is sent to.

Bu Sun Kim

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

[diff] [blame]

1807

#

Bu Sun Kim

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

[diff] [blame^]

1808

# The host is constructed from the domain name of the app associated with

1809

# the queue's project ID (for example <app-id>.appspot.com), and the

1810

# service, version,

1811

# and instance. Tasks which were created using

1812

# the App Engine SDK might have a custom domain name.

Bu Sun Kim

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

[diff] [blame]

1813

#

Bu Sun Kim

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

[diff] [blame^]

1814

# For more information, see

1815

# [How Requests are

1816

# Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed).

Bu Sun Kim

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

[diff] [blame]

1817

},

1818

},

1819

],

Bu Sun Kim

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

[diff] [blame^]

1820

"nextPageToken": "A String", # A token to retrieve next page of results.

1821

#

1822

# To return the next page of results, call

1823

# ListQueues with this value as the

1824

# page_token.

1825

#

1826

# If the next_page_token is empty, there are no more results.

1827

#

1828

# The page token is valid for only 2 hours.

Bu Sun Kim

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

[diff] [blame]

}</pre>

</div>

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

1834

<pre>Retrieves the next page of results.

1835

1836

Args:

1837

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

1838

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

1839

1840

Returns:

Bu Sun Kim

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

[diff] [blame^]

1841

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

Bu Sun Kim

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

[diff] [blame]

1842

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

</pre>

</div>

Dan O'Meara

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

[diff] [blame]

1847

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

1848

<pre>Updates a queue.

1849

1850

This method creates the queue if it does not exist and updates

1851

the queue if it does exist.

1852

1853

Queues created with this method allow tasks to live for a maximum of 31

1854

days. After a task is 31 days old, the task will be deleted regardless of whether

1855

it was dispatched or not.

1856

1857

WARNING: Using this method may have unintended side effects if you are

1858

using an App Engine `queue.yaml` or `queue.xml` file to manage your queues.

1859

Read

1860

[Overview of Queue Management and

1861

queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using

this method.

Args:

after which it becomes output only.

The queue name.

The queue name must have the following format:

1871

`projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID`

1872

1873

* `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]),

1874

hyphens (-), colons (:), or periods (.).

1875

For more information, see

1876

[Identifying

1877

projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)

Bu Sun Kim

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

[diff] [blame^]

1878

* `LOCATION_ID` is the canonical ID for the queue's location.

Bu Sun Kim

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

[diff] [blame]

1879

The list of available locations can be obtained by calling

1880

ListLocations.

1881

For more information, see https://cloud.google.com/about/locations/.

1882

* `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or

1883

hyphens (-). The maximum length is 100 characters. (required)

Dan O'Meara

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

[diff] [blame]

1884

body: object, The request body.

Bu Sun Kim

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

[diff] [blame]

1885

The object takes the form of:

1886

1887

{ # A queue is a container of related tasks. Queues are configured to manage

1888

# how those tasks are dispatched. Configurable properties include rate limits,

1889

# retry options, queue types, and others.

Bu Sun Kim

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

[diff] [blame^]

1890

"purgeTime": "A String", # Output only. The last time this queue was purged.

1891

#

1892

# All tasks that were created before this time

1893

# were purged.

1894

#

1895

# A queue can be purged using PurgeQueue, the

1896

# [App Engine Task Queue SDK, or the Cloud

1897

# Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue).

1898

#

1899

# Purge time will be truncated to the nearest microsecond. Purge

1900

# time will be unset if the queue has never been purged.

1901

"retryConfig": { # Retry config. # Settings that determine the retry behavior.

1902

#

1903

# * For tasks created using Cloud Tasks: the queue-level retry settings

1904

# apply to all tasks in the queue that were created using Cloud Tasks.

1905

# Retry settings cannot be set on individual tasks.

1906

# * For tasks created using the App Engine SDK: the queue-level retry

1907

# settings apply to all tasks in the queue which do not have retry settings

1908

# explicitly set on the task and were created by the App Engine SDK. See

1909

# [App Engine

1910

# documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks).

1911

#

1912

# These settings determine when a failed task attempt is retried.

1913

"minBackoff": "A String", # A task will be scheduled for retry between

1914

# min_backoff and

1915

# max_backoff duration after it fails,

1916

# if the queue's RetryConfig specifies that the task should be

1917

# retried.

1918

#

1919

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `min_backoff` will be truncated to the nearest second.

1924

#

1925

# This field has the same meaning as

1926

# [min_backoff_seconds in

1927

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

1928

"maxBackoff": "A String", # A task will be scheduled for retry between

1929

# min_backoff and

1930

# max_backoff duration after it fails,

1931

# if the queue's RetryConfig specifies that the task should be

1932

# retried.

1933

#

1934

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_backoff` will be truncated to the nearest second.

1939

#

1940

# This field has the same meaning as

1941

# [max_backoff_seconds in

1942

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

1943

"maxRetryDuration": "A String", # If positive, `max_retry_duration` specifies the time limit for

1944

# retrying a failed task, measured from when the task was first

1945

# attempted. Once `max_retry_duration` time has passed *and* the

1946

# task has been attempted max_attempts

1947

# times, no further attempts will be made and the task will be

1948

# deleted.

1949

#

1950

# If zero, then the task age is unlimited.

1951

#

1952

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_retry_duration` will be truncated to the nearest second.

1957

#

1958

# This field has the same meaning as

1959

# [task_age_limit in

1960

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

1961

"maxAttempts": 42, # Number of attempts per task.

1962

#

1963

# Cloud Tasks will attempt the task `max_attempts` times (that is, if the

1964

# first attempt fails, then there will be `max_attempts - 1` retries). Must

1965

# be >= -1.

1966

#

1967

# If unspecified when the queue is created, Cloud Tasks will pick the

1968

# default.

1969

#

1970

# -1 indicates unlimited attempts.

1971

#

1972

# This field has the same meaning as

1973

# [task_retry_limit in

1974

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

1975

"maxDoublings": 42, # The time between retries will double `max_doublings` times.

1976

#

1977

# A task's retry interval starts at

1978

# min_backoff, then doubles

1979

# `max_doublings` times, then increases linearly, and finally

1980

# retries at intervals of

1981

# max_backoff up to

1982

# max_attempts times.

1983

#

1984

# For example, if min_backoff is 10s,

1985

# max_backoff is 300s, and

1986

# `max_doublings` is 3, then the a task will first be retried in

1987

# 10s. The retry interval will double three times, and then

1988

# increase linearly by 2^3 * 10s. Finally, the task will retry at

1989

# intervals of max_backoff until the

1990

# task has been attempted max_attempts

1991

# times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s,

1992

# 240s, 300s, 300s, ....

1993

#

1994

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# This field has the same meaning as

1999

# [max_doublings in

2000

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2001

},

2002

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

2003

#

2004

# `state` can only be changed by called

2005

# PauseQueue,

2006

# ResumeQueue, or uploading

2007

# [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref).

2008

# UpdateQueue cannot be used to change `state`.

2009

"name": "A String", # Caller-specified and required in CreateQueue,

Bu Sun Kim

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

[diff] [blame]

2010

# after which it becomes output only.

#

# The queue name.

#

# The queue name must have the following format:

2015

# `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID`

2016

#

2017

# * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]),

2018

# hyphens (-), colons (:), or periods (.).

2019

# For more information, see

2020

# [Identifying

2021

# projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)

Bu Sun Kim

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

[diff] [blame^]

2022

# * `LOCATION_ID` is the canonical ID for the queue's location.

Bu Sun Kim

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

[diff] [blame]

2023

# The list of available locations can be obtained by calling

2024

# ListLocations.

2025

# For more information, see https://cloud.google.com/about/locations/.

2026

# * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or

2027

# hyphens (-). The maximum length is 100 characters.

Bu Sun Kim

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

[diff] [blame^]

2028

"rateLimits": { # Rate limits. # Rate limits for task dispatches.

Bu Sun Kim

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

[diff] [blame]

2029

#

2030

# rate_limits and retry_config are

2031

# related because they both control task attempts. However they control task

2032

# attempts in different ways:

2033

#

2034

# * rate_limits controls the total rate of

2035

# dispatches from a queue (i.e. all traffic dispatched from the

2036

# queue, regardless of whether the dispatch is from a first

2037

# attempt or a retry).

2038

# * retry_config controls what happens to

2039

# particular a task after its first attempt fails. That is,

2040

# retry_config controls task retries (the

2041

# second attempt, third attempt, etc).

2042

#

Bu Sun Kim

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

[diff] [blame^]

2043

# The queue's actual dispatch rate is the result of:

Bu Sun Kim

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

[diff] [blame]

2044

#

2045

# * Number of tasks in the queue

2046

# * User-specified throttling: rate_limits,

2047

# retry_config, and the

Bu Sun Kim

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

[diff] [blame^]

2048

# queue's state.

Bu Sun Kim

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

[diff] [blame]

2049

# * System throttling due to `429` (Too Many Requests) or `503` (Service

2050

# Unavailable) responses from the worker, high error rates, or to smooth

2051

# sudden large traffic spikes.

2052

#

2053

# This message determines the maximum rate that tasks can be dispatched by a

2054

# queue, regardless of whether the dispatch is a first task attempt or a retry.

2055

#

2056

# Note: The debugging command, RunTask, will run a task

2057

# even if the queue has reached its RateLimits.

Bu Sun Kim

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

[diff] [blame^]

2058

"maxConcurrentDispatches": 42, # The maximum number of concurrent tasks that Cloud Tasks allows

Bu Sun Kim

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

[diff] [blame]

2059

# to be dispatched for this queue. After this threshold has been

2060

# reached, Cloud Tasks stops dispatching tasks until the number of

2061

# concurrent requests decreases.

2062

#

2063

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# The maximum allowed value is 5,000.

2068

#

2069

#

2070

# This field has the same meaning as

2071

# [max_concurrent_requests in

2072

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests).

Bu Sun Kim

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

[diff] [blame^]

2073

"maxDispatchesPerSecond": 3.14, # The maximum rate at which tasks are dispatched from this queue.

2074

#

2075

# If unspecified when the queue is created, Cloud Tasks will pick the

2076

# default.

2077

#

2078

# * The maximum allowed value is 500.

2079

#

2080

#

2081

# This field has the same meaning as

2082

# [rate in

2083

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate).

2084

"maxBurstSize": 42, # Output only. The max burst size.

Bu Sun Kim

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

[diff] [blame]

2085

#

2086

# Max burst size limits how fast tasks in queue are processed when

2087

# many tasks are in the queue and the rate is high. This field

2088

# allows the queue to have a high rate so processing starts shortly

2089

# after a task is enqueued, but still limits resource usage when

2090

# many tasks are enqueued in a short period of time.

2091

#

2092

# The [token bucket](https://wikipedia.org/wiki/Token_Bucket)

2093

# algorithm is used to control the rate of task dispatches. Each

2094

# queue has a token bucket that holds tokens, up to the maximum

2095

# specified by `max_burst_size`. Each time a task is dispatched, a

2096

# token is removed from the bucket. Tasks will be dispatched until

Bu Sun Kim

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

[diff] [blame^]

2097

# the queue's bucket runs out of tokens. The bucket will be

Bu Sun Kim

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

[diff] [blame]

2098

# continuously refilled with new tokens based on

2099

# max_dispatches_per_second.

2100

#

2101

# Cloud Tasks will pick the value of `max_burst_size` based on the

2102

# value of

2103

# max_dispatches_per_second.

2104

#

Dan O'Meara

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

[diff] [blame]

2105

# For queues that were created or updated using

Bu Sun Kim

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

[diff] [blame]

2106

# `queue.yaml/xml`, `max_burst_size` is equal to

2107

# [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size).

2108

# Since `max_burst_size` is output only, if

2109

# UpdateQueue is called on a queue

2110

# created by `queue.yaml/xml`, `max_burst_size` will be reset based

2111

# on the value of

2112

# max_dispatches_per_second,

2113

# regardless of whether

2114

# max_dispatches_per_second

2115

# is updated.

Bu Sun Kim

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

[diff] [blame]

2116

},

Bu Sun Kim

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

[diff] [blame^]

2117

"stackdriverLoggingConfig": { # Configuration options for writing logs to # Configuration options for writing logs to

2118

# [Stackdriver Logging](https://cloud.google.com/logging/docs/). If this

2119

# field is unset, then no logs are written.

2120

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

2121

"samplingRatio": 3.14, # Specifies the fraction of operations to write to

2122

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

2123

# This field may contain any value between 0.0 and 1.0, inclusive.

2124

# 0.0 is the default and means that no operations are logged.

2125

},

2126

"appEngineRoutingOverride": { # App Engine Routing. # Overrides for

Bu Sun Kim

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

[diff] [blame]

2127

# task-level app_engine_routing.

2128

# These settings apply only to

2129

# App Engine tasks in this queue.

Dan O'Meara

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

[diff] [blame]

2130

# Http tasks are not affected.

Bu Sun Kim

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

[diff] [blame]

2131

#

2132

# If set, `app_engine_routing_override` is used for all

2133

# App Engine tasks in the queue, no matter what the

2134

# setting is for the

2135

# task-level app_engine_routing.

2136

#

2137

# Defines routing characteristics specific to App Engine - service, version,

2138

# and instance.

2139

#

2140

# For more information about services, versions, and instances see

2141

# [An Overview of App

2142

# Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),

2143

# [Microservices Architecture on Google App

2144

# Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine),

2145

# [App Engine Standard request

2146

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed),

2147

# and [App Engine Flex request

2148

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

Dan O'Meara

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

[diff] [blame]

2149

#

2150

# Using AppEngineRouting requires

2151

# [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)

2152

# Google IAM permission for the project

2153

# and the following scope:

2154

#

2155

# `https://www.googleapis.com/auth/cloud-platform`

Bu Sun Kim

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

[diff] [blame^]

2156

"service": "A String", # App service.

Bu Sun Kim

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

[diff] [blame]

2157

#

2158

# By default, the task is sent to the service which is the default

2159

# service when the task is attempted.

2160

#

2161

# For some queues or tasks which were created using the App Engine

2162

# Task Queue API, host is not parsable

2163

# into service,

2164

# version, and

2165

# instance. For example, some tasks

2166

# which were created using the App Engine SDK use a custom domain

2167

# name; custom domains are not parsed by Cloud Tasks. If

2168

# host is not parsable, then

2169

# service,

2170

# version, and

2171

# instance are the empty string.

Bu Sun Kim

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

[diff] [blame^]

2172

"instance": "A String", # App instance.

Dan O'Meara

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

[diff] [blame]

2173

#

Bu Sun Kim

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

[diff] [blame^]

2174

# By default, the task is sent to an instance which is available when

2175

# the task is attempted.

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

# Requests can only be sent to a specific instance if

2178

# [manual scaling is used in App Engine

2179

# Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes).

2180

# App Engine Flex does not support instances. For more information, see

2181

# [App Engine Standard request

2182

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)

2183

# and [App Engine Flex request

2184

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

2185

"version": "A String", # App version.

Bu Sun Kim

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

[diff] [blame]

2186

#

Bu Sun Kim

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

[diff] [blame^]

2187

# By default, the task is sent to the version which is the default

2188

# version when the task is attempted.

Bu Sun Kim

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

[diff] [blame]

2189

#

Bu Sun Kim

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

[diff] [blame^]

2190

# For some queues or tasks which were created using the App Engine

2191

# Task Queue API, host is not parsable

2192

# into service,

2193

# version, and

2194

# instance. For example, some tasks

2195

# which were created using the App Engine SDK use a custom domain

2196

# name; custom domains are not parsed by Cloud Tasks. If

2197

# host is not parsable, then

2198

# service,

2199

# version, and

2200

# instance are the empty string.

2201

"host": "A String", # Output only. The host that the task is sent to.

Bu Sun Kim

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

[diff] [blame]

2202

#

Bu Sun Kim

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

[diff] [blame^]

2203

# The host is constructed from the domain name of the app associated with

2204

# the queue's project ID (for example <app-id>.appspot.com), and the

2205

# service, version,

2206

# and instance. Tasks which were created using

2207

# the App Engine SDK might have a custom domain name.

Bu Sun Kim

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

[diff] [blame]

2208

#

Bu Sun Kim

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

[diff] [blame^]

2209

# For more information, see

2210

# [How Requests are

2211

# Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed).

Bu Sun Kim

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

[diff] [blame]

},

}

updateMask: string, A mask used to specify which fields of the queue are being updated.

2216

2217

If empty, then all fields will be updated.

2218

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2225

2226

{ # A queue is a container of related tasks. Queues are configured to manage

2227

# how those tasks are dispatched. Configurable properties include rate limits,

2228

# retry options, queue types, and others.

Bu Sun Kim

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

[diff] [blame^]

2229

"purgeTime": "A String", # Output only. The last time this queue was purged.

2230

#

2231

# All tasks that were created before this time

2232

# were purged.

2233

#

2234

# A queue can be purged using PurgeQueue, the

2235

# [App Engine Task Queue SDK, or the Cloud

2236

# Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue).

2237

#

2238

# Purge time will be truncated to the nearest microsecond. Purge

2239

# time will be unset if the queue has never been purged.

2240

"retryConfig": { # Retry config. # Settings that determine the retry behavior.

2241

#

2242

# * For tasks created using Cloud Tasks: the queue-level retry settings

2243

# apply to all tasks in the queue that were created using Cloud Tasks.

2244

# Retry settings cannot be set on individual tasks.

2245

# * For tasks created using the App Engine SDK: the queue-level retry

2246

# settings apply to all tasks in the queue which do not have retry settings

2247

# explicitly set on the task and were created by the App Engine SDK. See

2248

# [App Engine

2249

# documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks).

2250

#

2251

# These settings determine when a failed task attempt is retried.

2252

"minBackoff": "A String", # A task will be scheduled for retry between

2253

# min_backoff and

2254

# max_backoff duration after it fails,

2255

# if the queue's RetryConfig specifies that the task should be

2256

# retried.

2257

#

2258

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `min_backoff` will be truncated to the nearest second.

2263

#

2264

# This field has the same meaning as

2265

# [min_backoff_seconds in

2266

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2267

"maxBackoff": "A String", # A task will be scheduled for retry between

2268

# min_backoff and

2269

# max_backoff duration after it fails,

2270

# if the queue's RetryConfig specifies that the task should be

2271

# retried.

2272

#

2273

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_backoff` will be truncated to the nearest second.

2278

#

2279

# This field has the same meaning as

2280

# [max_backoff_seconds in

2281

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2282

"maxRetryDuration": "A String", # If positive, `max_retry_duration` specifies the time limit for

2283

# retrying a failed task, measured from when the task was first

2284

# attempted. Once `max_retry_duration` time has passed *and* the

2285

# task has been attempted max_attempts

2286

# times, no further attempts will be made and the task will be

2287

# deleted.

2288

#

2289

# If zero, then the task age is unlimited.

2290

#

2291

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_retry_duration` will be truncated to the nearest second.

2296

#

2297

# This field has the same meaning as

2298

# [task_age_limit in

2299

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2300

"maxAttempts": 42, # Number of attempts per task.

2301

#

2302

# Cloud Tasks will attempt the task `max_attempts` times (that is, if the

2303

# first attempt fails, then there will be `max_attempts - 1` retries). Must

2304

# be >= -1.

2305

#

2306

# If unspecified when the queue is created, Cloud Tasks will pick the

2307

# default.

2308

#

2309

# -1 indicates unlimited attempts.

2310

#

2311

# This field has the same meaning as

2312

# [task_retry_limit in

2313

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2314

"maxDoublings": 42, # The time between retries will double `max_doublings` times.

2315

#

2316

# A task's retry interval starts at

2317

# min_backoff, then doubles

2318

# `max_doublings` times, then increases linearly, and finally

2319

# retries at intervals of

2320

# max_backoff up to

2321

# max_attempts times.

2322

#

2323

# For example, if min_backoff is 10s,

2324

# max_backoff is 300s, and

2325

# `max_doublings` is 3, then the a task will first be retried in

2326

# 10s. The retry interval will double three times, and then

2327

# increase linearly by 2^3 * 10s. Finally, the task will retry at

2328

# intervals of max_backoff until the

2329

# task has been attempted max_attempts

2330

# times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s,

2331

# 240s, 300s, 300s, ....

2332

#

2333

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# This field has the same meaning as

2338

# [max_doublings in

2339

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2340

},

2341

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

2342

#

2343

# `state` can only be changed by called

2344

# PauseQueue,

2345

# ResumeQueue, or uploading

2346

# [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref).

2347

# UpdateQueue cannot be used to change `state`.

2348

"name": "A String", # Caller-specified and required in CreateQueue,

Bu Sun Kim

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

[diff] [blame]

2349

# after which it becomes output only.

#

# The queue name.

#

# The queue name must have the following format:

2354

# `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID`

2355

#

2356

# * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]),

2357

# hyphens (-), colons (:), or periods (.).

2358

# For more information, see

2359

# [Identifying

2360

# projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)

Bu Sun Kim

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

[diff] [blame^]

2361

# * `LOCATION_ID` is the canonical ID for the queue's location.

Bu Sun Kim

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

[diff] [blame]

2362

# The list of available locations can be obtained by calling

2363

# ListLocations.

2364

# For more information, see https://cloud.google.com/about/locations/.

2365

# * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or

2366

# hyphens (-). The maximum length is 100 characters.

Bu Sun Kim

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

[diff] [blame^]

2367

"rateLimits": { # Rate limits. # Rate limits for task dispatches.

Bu Sun Kim

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

[diff] [blame]

2368

#

2369

# rate_limits and retry_config are

2370

# related because they both control task attempts. However they control task

2371

# attempts in different ways:

2372

#

2373

# * rate_limits controls the total rate of

2374

# dispatches from a queue (i.e. all traffic dispatched from the

2375

# queue, regardless of whether the dispatch is from a first

2376

# attempt or a retry).

2377

# * retry_config controls what happens to

2378

# particular a task after its first attempt fails. That is,

2379

# retry_config controls task retries (the

2380

# second attempt, third attempt, etc).

2381

#

Bu Sun Kim

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

[diff] [blame^]

2382

# The queue's actual dispatch rate is the result of:

Bu Sun Kim

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

[diff] [blame]

2383

#

2384

# * Number of tasks in the queue

2385

# * User-specified throttling: rate_limits,

2386

# retry_config, and the

Bu Sun Kim

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

[diff] [blame^]

2387

# queue's state.

Bu Sun Kim

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

[diff] [blame]

2388

# * System throttling due to `429` (Too Many Requests) or `503` (Service

2389

# Unavailable) responses from the worker, high error rates, or to smooth

2390

# sudden large traffic spikes.

2391

#

2392

# This message determines the maximum rate that tasks can be dispatched by a

2393

# queue, regardless of whether the dispatch is a first task attempt or a retry.

2394

#

2395

# Note: The debugging command, RunTask, will run a task

2396

# even if the queue has reached its RateLimits.

Bu Sun Kim

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

[diff] [blame^]

2397

"maxConcurrentDispatches": 42, # The maximum number of concurrent tasks that Cloud Tasks allows

Bu Sun Kim

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

[diff] [blame]

2398

# to be dispatched for this queue. After this threshold has been

2399

# reached, Cloud Tasks stops dispatching tasks until the number of

2400

# concurrent requests decreases.

2401

#

2402

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# The maximum allowed value is 5,000.

2407

#

2408

#

2409

# This field has the same meaning as

2410

# [max_concurrent_requests in

2411

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests).

Bu Sun Kim

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

[diff] [blame^]

2412

"maxDispatchesPerSecond": 3.14, # The maximum rate at which tasks are dispatched from this queue.

2413

#

2414

# If unspecified when the queue is created, Cloud Tasks will pick the

2415

# default.

2416

#

2417

# * The maximum allowed value is 500.

2418

#

2419

#

2420

# This field has the same meaning as

2421

# [rate in

2422

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate).

2423

"maxBurstSize": 42, # Output only. The max burst size.

Bu Sun Kim

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

[diff] [blame]

2424

#

2425

# Max burst size limits how fast tasks in queue are processed when

2426

# many tasks are in the queue and the rate is high. This field

2427

# allows the queue to have a high rate so processing starts shortly

2428

# after a task is enqueued, but still limits resource usage when

2429

# many tasks are enqueued in a short period of time.

2430

#

2431

# The [token bucket](https://wikipedia.org/wiki/Token_Bucket)

2432

# algorithm is used to control the rate of task dispatches. Each

2433

# queue has a token bucket that holds tokens, up to the maximum

2434

# specified by `max_burst_size`. Each time a task is dispatched, a

2435

# token is removed from the bucket. Tasks will be dispatched until

Bu Sun Kim

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

[diff] [blame^]

2436

# the queue's bucket runs out of tokens. The bucket will be

Bu Sun Kim

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

[diff] [blame]

2437

# continuously refilled with new tokens based on

2438

# max_dispatches_per_second.

2439

#

2440

# Cloud Tasks will pick the value of `max_burst_size` based on the

2441

# value of

2442

# max_dispatches_per_second.

2443

#

Dan O'Meara

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

[diff] [blame]

2444

# For queues that were created or updated using

Bu Sun Kim

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

[diff] [blame]

2445

# `queue.yaml/xml`, `max_burst_size` is equal to

2446

# [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size).

2447

# Since `max_burst_size` is output only, if

2448

# UpdateQueue is called on a queue

2449

# created by `queue.yaml/xml`, `max_burst_size` will be reset based

2450

# on the value of

2451

# max_dispatches_per_second,

2452

# regardless of whether

2453

# max_dispatches_per_second

2454

# is updated.

Bu Sun Kim

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

[diff] [blame]

2455

},

Bu Sun Kim

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

[diff] [blame^]

2456

"stackdriverLoggingConfig": { # Configuration options for writing logs to # Configuration options for writing logs to

2457

# [Stackdriver Logging](https://cloud.google.com/logging/docs/). If this

2458

# field is unset, then no logs are written.

2459

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

2460

"samplingRatio": 3.14, # Specifies the fraction of operations to write to

2461

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

2462

# This field may contain any value between 0.0 and 1.0, inclusive.

2463

# 0.0 is the default and means that no operations are logged.

2464

},

2465

"appEngineRoutingOverride": { # App Engine Routing. # Overrides for

Bu Sun Kim

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

[diff] [blame]

2466

# task-level app_engine_routing.

2467

# These settings apply only to

2468

# App Engine tasks in this queue.

Dan O'Meara

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

[diff] [blame]

2469

# Http tasks are not affected.

Bu Sun Kim

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

[diff] [blame]

2470

#

2471

# If set, `app_engine_routing_override` is used for all

2472

# App Engine tasks in the queue, no matter what the

2473

# setting is for the

2474

# task-level app_engine_routing.

2475

#

2476

# Defines routing characteristics specific to App Engine - service, version,

2477

# and instance.

2478

#

2479

# For more information about services, versions, and instances see

2480

# [An Overview of App

2481

# Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),

2482

# [Microservices Architecture on Google App

2483

# Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine),

2484

# [App Engine Standard request

2485

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed),

2486

# and [App Engine Flex request

2487

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

Dan O'Meara

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

[diff] [blame]

2488

#

2489

# Using AppEngineRouting requires

2490

# [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)

2491

# Google IAM permission for the project

2492

# and the following scope:

2493

#

2494

# `https://www.googleapis.com/auth/cloud-platform`

Bu Sun Kim

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

[diff] [blame^]

2495

"service": "A String", # App service.

Bu Sun Kim

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

[diff] [blame]

2496

#

2497

# By default, the task is sent to the service which is the default

2498

# service when the task is attempted.

2499

#

2500

# For some queues or tasks which were created using the App Engine

2501

# Task Queue API, host is not parsable

2502

# into service,

2503

# version, and

2504

# instance. For example, some tasks

2505

# which were created using the App Engine SDK use a custom domain

2506

# name; custom domains are not parsed by Cloud Tasks. If

2507

# host is not parsable, then

2508

# service,

2509

# version, and

2510

# instance are the empty string.

Bu Sun Kim

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

[diff] [blame^]

2511

"instance": "A String", # App instance.

Dan O'Meara

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

[diff] [blame]

2512

#

Bu Sun Kim

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

[diff] [blame^]

2513

# By default, the task is sent to an instance which is available when

2514

# the task is attempted.

Bu Sun Kim

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

[diff] [blame]

2515

#

Bu Sun Kim

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

[diff] [blame^]

2516

# Requests can only be sent to a specific instance if

2517

# [manual scaling is used in App Engine

2518

# Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes).

2519

# App Engine Flex does not support instances. For more information, see

2520

# [App Engine Standard request

2521

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)

2522

# and [App Engine Flex request

2523

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

2524

"version": "A String", # App version.

Bu Sun Kim

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

[diff] [blame]

2525

#

Bu Sun Kim

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

[diff] [blame^]

2526

# By default, the task is sent to the version which is the default

2527

# version when the task is attempted.

Bu Sun Kim

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

[diff] [blame]

2528

#

Bu Sun Kim

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

[diff] [blame^]

2529

# For some queues or tasks which were created using the App Engine

2530

# Task Queue API, host is not parsable

2531

# into service,

2532

# version, and

2533

# instance. For example, some tasks

2534

# which were created using the App Engine SDK use a custom domain

2535

# name; custom domains are not parsed by Cloud Tasks. If

2536

# host is not parsable, then

2537

# service,

2538

# version, and

2539

# instance are the empty string.

2540

"host": "A String", # Output only. The host that the task is sent to.

Bu Sun Kim

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

[diff] [blame]

2541

#

Bu Sun Kim

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

[diff] [blame^]

2542

# The host is constructed from the domain name of the app associated with

2543

# the queue's project ID (for example <app-id>.appspot.com), and the

2544

# service, version,

2545

# and instance. Tasks which were created using

2546

# the App Engine SDK might have a custom domain name.

Bu Sun Kim

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

[diff] [blame]

2547

#

Bu Sun Kim

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

[diff] [blame^]

2548

# For more information, see

2549

# [How Requests are

2550

# Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed).

Bu Sun Kim

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

[diff] [blame]

},

}</pre>

</div>

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

2557

<pre>Pauses the queue.

2558

2559

If a queue is paused then the system will stop dispatching tasks

2560

until the queue is resumed via

2561

ResumeQueue. Tasks can still be added

2562

when the queue is paused. A queue is paused if its

2563

state is PAUSED.

2564

2565

Args:

Dan O'Meara

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

[diff] [blame]

2566

Bu Sun Kim

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

[diff] [blame]

2567

`projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` (required)

2568

body: object, The request body.

2569

The object takes the form of:

2570

2571

{ # Request message for PauseQueue.

2572

}

2573

2574

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2581

2582

{ # A queue is a container of related tasks. Queues are configured to manage

2583

# how those tasks are dispatched. Configurable properties include rate limits,

2584

# retry options, queue types, and others.

Bu Sun Kim

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

[diff] [blame^]

2585

"purgeTime": "A String", # Output only. The last time this queue was purged.

2586

#

2587

# All tasks that were created before this time

2588

# were purged.

2589

#

2590

# A queue can be purged using PurgeQueue, the

2591

# [App Engine Task Queue SDK, or the Cloud

2592

# Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue).

2593

#

2594

# Purge time will be truncated to the nearest microsecond. Purge

2595

# time will be unset if the queue has never been purged.

2596

"retryConfig": { # Retry config. # Settings that determine the retry behavior.

2597

#

2598

# * For tasks created using Cloud Tasks: the queue-level retry settings

2599

# apply to all tasks in the queue that were created using Cloud Tasks.

2600

# Retry settings cannot be set on individual tasks.

2601

# * For tasks created using the App Engine SDK: the queue-level retry

2602

# settings apply to all tasks in the queue which do not have retry settings

2603

# explicitly set on the task and were created by the App Engine SDK. See

2604

# [App Engine

2605

# documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks).

2606

#

2607

# These settings determine when a failed task attempt is retried.

2608

"minBackoff": "A String", # A task will be scheduled for retry between

2609

# min_backoff and

2610

# max_backoff duration after it fails,

2611

# if the queue's RetryConfig specifies that the task should be

2612

# retried.

2613

#

2614

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `min_backoff` will be truncated to the nearest second.

2619

#

2620

# This field has the same meaning as

2621

# [min_backoff_seconds in

2622

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2623

"maxBackoff": "A String", # A task will be scheduled for retry between

2624

# min_backoff and

2625

# max_backoff duration after it fails,

2626

# if the queue's RetryConfig specifies that the task should be

2627

# retried.

2628

#

2629

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_backoff` will be truncated to the nearest second.

2634

#

2635

# This field has the same meaning as

2636

# [max_backoff_seconds in

2637

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2638

"maxRetryDuration": "A String", # If positive, `max_retry_duration` specifies the time limit for

2639

# retrying a failed task, measured from when the task was first

2640

# attempted. Once `max_retry_duration` time has passed *and* the

2641

# task has been attempted max_attempts

2642

# times, no further attempts will be made and the task will be

2643

# deleted.

2644

#

2645

# If zero, then the task age is unlimited.

2646

#

2647

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_retry_duration` will be truncated to the nearest second.

2652

#

2653

# This field has the same meaning as

2654

# [task_age_limit in

2655

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2656

"maxAttempts": 42, # Number of attempts per task.

2657

#

2658

# Cloud Tasks will attempt the task `max_attempts` times (that is, if the

2659

# first attempt fails, then there will be `max_attempts - 1` retries). Must

2660

# be >= -1.

2661

#

2662

# If unspecified when the queue is created, Cloud Tasks will pick the

2663

# default.

2664

#

2665

# -1 indicates unlimited attempts.

2666

#

2667

# This field has the same meaning as

2668

# [task_retry_limit in

2669

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2670

"maxDoublings": 42, # The time between retries will double `max_doublings` times.

2671

#

2672

# A task's retry interval starts at

2673

# min_backoff, then doubles

2674

# `max_doublings` times, then increases linearly, and finally

2675

# retries at intervals of

2676

# max_backoff up to

2677

# max_attempts times.

2678

#

2679

# For example, if min_backoff is 10s,

2680

# max_backoff is 300s, and

2681

# `max_doublings` is 3, then the a task will first be retried in

2682

# 10s. The retry interval will double three times, and then

2683

# increase linearly by 2^3 * 10s. Finally, the task will retry at

2684

# intervals of max_backoff until the

2685

# task has been attempted max_attempts

2686

# times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s,

2687

# 240s, 300s, 300s, ....

2688

#

2689

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# This field has the same meaning as

2694

# [max_doublings in

2695

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2696

},

2697

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

2698

#

2699

# `state` can only be changed by called

2700

# PauseQueue,

2701

# ResumeQueue, or uploading

2702

# [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref).

2703

# UpdateQueue cannot be used to change `state`.

2704

"name": "A String", # Caller-specified and required in CreateQueue,

Bu Sun Kim

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

[diff] [blame]

2705

# after which it becomes output only.

#

# The queue name.

#

# The queue name must have the following format:

2710

# `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID`

2711

#

2712

# * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]),

2713

# hyphens (-), colons (:), or periods (.).

2714

# For more information, see

2715

# [Identifying

2716

# projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)

Bu Sun Kim

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

[diff] [blame^]

2717

# * `LOCATION_ID` is the canonical ID for the queue's location.

Bu Sun Kim

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

[diff] [blame]

2718

# The list of available locations can be obtained by calling

2719

# ListLocations.

2720

# For more information, see https://cloud.google.com/about/locations/.

2721

# * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or

2722

# hyphens (-). The maximum length is 100 characters.

Bu Sun Kim

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

[diff] [blame^]

2723

"rateLimits": { # Rate limits. # Rate limits for task dispatches.

Bu Sun Kim

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

[diff] [blame]

2724

#

2725

# rate_limits and retry_config are

2726

# related because they both control task attempts. However they control task

2727

# attempts in different ways:

2728

#

2729

# * rate_limits controls the total rate of

2730

# dispatches from a queue (i.e. all traffic dispatched from the

2731

# queue, regardless of whether the dispatch is from a first

2732

# attempt or a retry).

2733

# * retry_config controls what happens to

2734

# particular a task after its first attempt fails. That is,

2735

# retry_config controls task retries (the

2736

# second attempt, third attempt, etc).

2737

#

Bu Sun Kim

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

[diff] [blame^]

2738

# The queue's actual dispatch rate is the result of:

Bu Sun Kim

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

[diff] [blame]

2739

#

2740

# * Number of tasks in the queue

2741

# * User-specified throttling: rate_limits,

2742

# retry_config, and the

Bu Sun Kim

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

[diff] [blame^]

2743

# queue's state.

Bu Sun Kim

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

[diff] [blame]

2744

# * System throttling due to `429` (Too Many Requests) or `503` (Service

2745

# Unavailable) responses from the worker, high error rates, or to smooth

2746

# sudden large traffic spikes.

2747

#

2748

# This message determines the maximum rate that tasks can be dispatched by a

2749

# queue, regardless of whether the dispatch is a first task attempt or a retry.

2750

#

2751

# Note: The debugging command, RunTask, will run a task

2752

# even if the queue has reached its RateLimits.

Bu Sun Kim

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

[diff] [blame^]

2753

"maxConcurrentDispatches": 42, # The maximum number of concurrent tasks that Cloud Tasks allows

Bu Sun Kim

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

[diff] [blame]

2754

# to be dispatched for this queue. After this threshold has been

2755

# reached, Cloud Tasks stops dispatching tasks until the number of

2756

# concurrent requests decreases.

2757

#

2758

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# The maximum allowed value is 5,000.

2763

#

2764

#

2765

# This field has the same meaning as

2766

# [max_concurrent_requests in

2767

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests).

Bu Sun Kim

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

[diff] [blame^]

2768

"maxDispatchesPerSecond": 3.14, # The maximum rate at which tasks are dispatched from this queue.

2769

#

2770

# If unspecified when the queue is created, Cloud Tasks will pick the

2771

# default.

2772

#

2773

# * The maximum allowed value is 500.

2774

#

2775

#

2776

# This field has the same meaning as

2777

# [rate in

2778

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate).

2779

"maxBurstSize": 42, # Output only. The max burst size.

Bu Sun Kim

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

[diff] [blame]

2780

#

2781

# Max burst size limits how fast tasks in queue are processed when

2782

# many tasks are in the queue and the rate is high. This field

2783

# allows the queue to have a high rate so processing starts shortly

2784

# after a task is enqueued, but still limits resource usage when

2785

# many tasks are enqueued in a short period of time.

2786

#

2787

# The [token bucket](https://wikipedia.org/wiki/Token_Bucket)

2788

# algorithm is used to control the rate of task dispatches. Each

2789

# queue has a token bucket that holds tokens, up to the maximum

2790

# specified by `max_burst_size`. Each time a task is dispatched, a

2791

# token is removed from the bucket. Tasks will be dispatched until

Bu Sun Kim

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

[diff] [blame^]

2792

# the queue's bucket runs out of tokens. The bucket will be

Bu Sun Kim

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

[diff] [blame]

2793

# continuously refilled with new tokens based on

2794

# max_dispatches_per_second.

2795

#

2796

# Cloud Tasks will pick the value of `max_burst_size` based on the

2797

# value of

2798

# max_dispatches_per_second.

2799

#

Dan O'Meara

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

[diff] [blame]

2800

# For queues that were created or updated using

Bu Sun Kim

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

[diff] [blame]

2801

# `queue.yaml/xml`, `max_burst_size` is equal to

2802

# [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size).

2803

# Since `max_burst_size` is output only, if

2804

# UpdateQueue is called on a queue

2805

# created by `queue.yaml/xml`, `max_burst_size` will be reset based

2806

# on the value of

2807

# max_dispatches_per_second,

2808

# regardless of whether

2809

# max_dispatches_per_second

2810

# is updated.

Bu Sun Kim

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

[diff] [blame]

2811

},

Bu Sun Kim

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

[diff] [blame^]

2812

"stackdriverLoggingConfig": { # Configuration options for writing logs to # Configuration options for writing logs to

2813

# [Stackdriver Logging](https://cloud.google.com/logging/docs/). If this

2814

# field is unset, then no logs are written.

2815

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

2816

"samplingRatio": 3.14, # Specifies the fraction of operations to write to

2817

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

2818

# This field may contain any value between 0.0 and 1.0, inclusive.

2819

# 0.0 is the default and means that no operations are logged.

2820

},

2821

"appEngineRoutingOverride": { # App Engine Routing. # Overrides for

Bu Sun Kim

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

[diff] [blame]

2822

# task-level app_engine_routing.

2823

# These settings apply only to

2824

# App Engine tasks in this queue.

Dan O'Meara

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

[diff] [blame]

2825

# Http tasks are not affected.

Bu Sun Kim

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

[diff] [blame]

2826

#

2827

# If set, `app_engine_routing_override` is used for all

2828

# App Engine tasks in the queue, no matter what the

2829

# setting is for the

2830

# task-level app_engine_routing.

2831

#

2832

# Defines routing characteristics specific to App Engine - service, version,

2833

# and instance.

2834

#

2835

# For more information about services, versions, and instances see

2836

# [An Overview of App

2837

# Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),

2838

# [Microservices Architecture on Google App

2839

# Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine),

2840

# [App Engine Standard request

2841

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed),

2842

# and [App Engine Flex request

2843

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

Dan O'Meara

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

[diff] [blame]

2844

#

2845

# Using AppEngineRouting requires

2846

# [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)

2847

# Google IAM permission for the project

2848

# and the following scope:

2849

#

2850

# `https://www.googleapis.com/auth/cloud-platform`

Bu Sun Kim

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

[diff] [blame^]

2851

"service": "A String", # App service.

Bu Sun Kim

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

[diff] [blame]

2852

#

2853

# By default, the task is sent to the service which is the default

2854

# service when the task is attempted.

2855

#

2856

# For some queues or tasks which were created using the App Engine

2857

# Task Queue API, host is not parsable

2858

# into service,

2859

# version, and

2860

# instance. For example, some tasks

2861

# which were created using the App Engine SDK use a custom domain

2862

# name; custom domains are not parsed by Cloud Tasks. If

2863

# host is not parsable, then

2864

# service,

2865

# version, and

2866

# instance are the empty string.

Bu Sun Kim

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

[diff] [blame^]

2867

"instance": "A String", # App instance.

Dan O'Meara

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

[diff] [blame]

2868

#

Bu Sun Kim

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

[diff] [blame^]

2869

# By default, the task is sent to an instance which is available when

2870

# the task is attempted.

Bu Sun Kim

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

[diff] [blame]

2871

#

Bu Sun Kim

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

[diff] [blame^]

2872

# Requests can only be sent to a specific instance if

2873

# [manual scaling is used in App Engine

2874

# Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes).

2875

# App Engine Flex does not support instances. For more information, see

2876

# [App Engine Standard request

2877

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)

2878

# and [App Engine Flex request

2879

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

2880

"version": "A String", # App version.

Bu Sun Kim

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

[diff] [blame]

2881

#

Bu Sun Kim

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

[diff] [blame^]

2882

# By default, the task is sent to the version which is the default

2883

# version when the task is attempted.

Bu Sun Kim

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

[diff] [blame]

2884

#

Bu Sun Kim

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

[diff] [blame^]

2885

# For some queues or tasks which were created using the App Engine

2886

# Task Queue API, host is not parsable

2887

# into service,

2888

# version, and

2889

# instance. For example, some tasks

2890

# which were created using the App Engine SDK use a custom domain

2891

# name; custom domains are not parsed by Cloud Tasks. If

2892

# host is not parsable, then

2893

# service,

2894

# version, and

2895

# instance are the empty string.

2896

"host": "A String", # Output only. The host that the task is sent to.

Bu Sun Kim

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

[diff] [blame]

2897

#

Bu Sun Kim

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

[diff] [blame^]

2898

# The host is constructed from the domain name of the app associated with

2899

# the queue's project ID (for example <app-id>.appspot.com), and the

2900

# service, version,

2901

# and instance. Tasks which were created using

2902

# the App Engine SDK might have a custom domain name.

Bu Sun Kim

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

[diff] [blame]

2903

#

Bu Sun Kim

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

[diff] [blame^]

2904

# For more information, see

2905

# [How Requests are

2906

# Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed).

Bu Sun Kim

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

[diff] [blame]

},

}</pre>

</div>

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

2913

<pre>Purges a queue by deleting all of its tasks.

2914

2915

All tasks created before this method is called are permanently deleted.

2916

2917

Purge operations can take up to one minute to take effect. Tasks

2918

might be dispatched before the purge takes effect. A purge is irreversible.

2919

2920

Args:

Dan O'Meara

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

[diff] [blame]

2921

Bu Sun Kim

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

[diff] [blame]

2922

`projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` (required)

2923

body: object, The request body.

2924

The object takes the form of:

2925

2926

{ # Request message for PurgeQueue.

2927

}

2928

2929

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2936

2937

{ # A queue is a container of related tasks. Queues are configured to manage

2938

# how those tasks are dispatched. Configurable properties include rate limits,

2939

# retry options, queue types, and others.

Bu Sun Kim

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

[diff] [blame^]

2940

"purgeTime": "A String", # Output only. The last time this queue was purged.

2941

#

2942

# All tasks that were created before this time

2943

# were purged.

2944

#

2945

# A queue can be purged using PurgeQueue, the

2946

# [App Engine Task Queue SDK, or the Cloud

2947

# Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue).

2948

#

2949

# Purge time will be truncated to the nearest microsecond. Purge

2950

# time will be unset if the queue has never been purged.

2951

"retryConfig": { # Retry config. # Settings that determine the retry behavior.

2952

#

2953

# * For tasks created using Cloud Tasks: the queue-level retry settings

2954

# apply to all tasks in the queue that were created using Cloud Tasks.

2955

# Retry settings cannot be set on individual tasks.

2956

# * For tasks created using the App Engine SDK: the queue-level retry

2957

# settings apply to all tasks in the queue which do not have retry settings

2958

# explicitly set on the task and were created by the App Engine SDK. See

2959

# [App Engine

2960

# documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks).

2961

#

2962

# These settings determine when a failed task attempt is retried.

2963

"minBackoff": "A String", # A task will be scheduled for retry between

2964

# min_backoff and

2965

# max_backoff duration after it fails,

2966

# if the queue's RetryConfig specifies that the task should be

2967

# retried.

2968

#

2969

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `min_backoff` will be truncated to the nearest second.

2974

#

2975

# This field has the same meaning as

2976

# [min_backoff_seconds in

2977

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2978

"maxBackoff": "A String", # A task will be scheduled for retry between

2979

# min_backoff and

2980

# max_backoff duration after it fails,

2981

# if the queue's RetryConfig specifies that the task should be

2982

# retried.

2983

#

2984

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_backoff` will be truncated to the nearest second.

2989

#

2990

# This field has the same meaning as

2991

# [max_backoff_seconds in

2992

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

2993

"maxRetryDuration": "A String", # If positive, `max_retry_duration` specifies the time limit for

2994

# retrying a failed task, measured from when the task was first

2995

# attempted. Once `max_retry_duration` time has passed *and* the

2996

# task has been attempted max_attempts

2997

# times, no further attempts will be made and the task will be

2998

# deleted.

2999

#

3000

# If zero, then the task age is unlimited.

3001

#

3002

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_retry_duration` will be truncated to the nearest second.

3007

#

3008

# This field has the same meaning as

3009

# [task_age_limit in

3010

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

3011

"maxAttempts": 42, # Number of attempts per task.

3012

#

3013

# Cloud Tasks will attempt the task `max_attempts` times (that is, if the

3014

# first attempt fails, then there will be `max_attempts - 1` retries). Must

3015

# be >= -1.

3016

#

3017

# If unspecified when the queue is created, Cloud Tasks will pick the

3018

# default.

3019

#

3020

# -1 indicates unlimited attempts.

3021

#

3022

# This field has the same meaning as

3023

# [task_retry_limit in

3024

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

3025

"maxDoublings": 42, # The time between retries will double `max_doublings` times.

3026

#

3027

# A task's retry interval starts at

3028

# min_backoff, then doubles

3029

# `max_doublings` times, then increases linearly, and finally

3030

# retries at intervals of

3031

# max_backoff up to

3032

# max_attempts times.

3033

#

3034

# For example, if min_backoff is 10s,

3035

# max_backoff is 300s, and

3036

# `max_doublings` is 3, then the a task will first be retried in

3037

# 10s. The retry interval will double three times, and then

3038

# increase linearly by 2^3 * 10s. Finally, the task will retry at

3039

# intervals of max_backoff until the

3040

# task has been attempted max_attempts

3041

# times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s,

3042

# 240s, 300s, 300s, ....

3043

#

3044

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# This field has the same meaning as

3049

# [max_doublings in

3050

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

3051

},

3052

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

3053

#

3054

# `state` can only be changed by called

3055

# PauseQueue,

3056

# ResumeQueue, or uploading

3057

# [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref).

3058

# UpdateQueue cannot be used to change `state`.

3059

"name": "A String", # Caller-specified and required in CreateQueue,

Bu Sun Kim

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

[diff] [blame]

3060

# after which it becomes output only.

#

# The queue name.

#

# The queue name must have the following format:

3065

# `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID`

3066

#

3067

# * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]),

3068

# hyphens (-), colons (:), or periods (.).

3069

# For more information, see

3070

# [Identifying

3071

# projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)

Bu Sun Kim

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

[diff] [blame^]

3072

# * `LOCATION_ID` is the canonical ID for the queue's location.

Bu Sun Kim

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

[diff] [blame]

3073

# The list of available locations can be obtained by calling

3074

# ListLocations.

3075

# For more information, see https://cloud.google.com/about/locations/.

3076

# * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or

3077

# hyphens (-). The maximum length is 100 characters.

Bu Sun Kim

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

[diff] [blame^]

3078

"rateLimits": { # Rate limits. # Rate limits for task dispatches.

Bu Sun Kim

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

[diff] [blame]

3079

#

3080

# rate_limits and retry_config are

3081

# related because they both control task attempts. However they control task

3082

# attempts in different ways:

3083

#

3084

# * rate_limits controls the total rate of

3085

# dispatches from a queue (i.e. all traffic dispatched from the

3086

# queue, regardless of whether the dispatch is from a first

3087

# attempt or a retry).

3088

# * retry_config controls what happens to

3089

# particular a task after its first attempt fails. That is,

3090

# retry_config controls task retries (the

3091

# second attempt, third attempt, etc).

3092

#

Bu Sun Kim

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

[diff] [blame^]

3093

# The queue's actual dispatch rate is the result of:

Bu Sun Kim

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

[diff] [blame]

3094

#

3095

# * Number of tasks in the queue

3096

# * User-specified throttling: rate_limits,

3097

# retry_config, and the

Bu Sun Kim

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

[diff] [blame^]

3098

# queue's state.

Bu Sun Kim

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

[diff] [blame]

3099

# * System throttling due to `429` (Too Many Requests) or `503` (Service

3100

# Unavailable) responses from the worker, high error rates, or to smooth

3101

# sudden large traffic spikes.

3102

#

3103

# This message determines the maximum rate that tasks can be dispatched by a

3104

# queue, regardless of whether the dispatch is a first task attempt or a retry.

3105

#

3106

# Note: The debugging command, RunTask, will run a task

3107

# even if the queue has reached its RateLimits.

Bu Sun Kim

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

[diff] [blame^]

3108

"maxConcurrentDispatches": 42, # The maximum number of concurrent tasks that Cloud Tasks allows

Bu Sun Kim

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

[diff] [blame]

3109

# to be dispatched for this queue. After this threshold has been

3110

# reached, Cloud Tasks stops dispatching tasks until the number of

3111

# concurrent requests decreases.

3112

#

3113

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# The maximum allowed value is 5,000.

3118

#

3119

#

3120

# This field has the same meaning as

3121

# [max_concurrent_requests in

3122

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests).

Bu Sun Kim

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

[diff] [blame^]

3123

"maxDispatchesPerSecond": 3.14, # The maximum rate at which tasks are dispatched from this queue.

3124

#

3125

# If unspecified when the queue is created, Cloud Tasks will pick the

3126

# default.

3127

#

3128

# * The maximum allowed value is 500.

3129

#

3130

#

3131

# This field has the same meaning as

3132

# [rate in

3133

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate).

3134

"maxBurstSize": 42, # Output only. The max burst size.

Bu Sun Kim

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

[diff] [blame]

3135

#

3136

# Max burst size limits how fast tasks in queue are processed when

3137

# many tasks are in the queue and the rate is high. This field

3138

# allows the queue to have a high rate so processing starts shortly

3139

# after a task is enqueued, but still limits resource usage when

3140

# many tasks are enqueued in a short period of time.

3141

#

3142

# The [token bucket](https://wikipedia.org/wiki/Token_Bucket)

3143

# algorithm is used to control the rate of task dispatches. Each

3144

# queue has a token bucket that holds tokens, up to the maximum

3145

# specified by `max_burst_size`. Each time a task is dispatched, a

3146

# token is removed from the bucket. Tasks will be dispatched until

Bu Sun Kim

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

[diff] [blame^]

3147

# the queue's bucket runs out of tokens. The bucket will be

Bu Sun Kim

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

[diff] [blame]

3148

# continuously refilled with new tokens based on

3149

# max_dispatches_per_second.

3150

#

3151

# Cloud Tasks will pick the value of `max_burst_size` based on the

3152

# value of

3153

# max_dispatches_per_second.

3154

#

Dan O'Meara

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

[diff] [blame]

3155

# For queues that were created or updated using

Bu Sun Kim

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

[diff] [blame]

3156

# `queue.yaml/xml`, `max_burst_size` is equal to

3157

# [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size).

3158

# Since `max_burst_size` is output only, if

3159

# UpdateQueue is called on a queue

3160

# created by `queue.yaml/xml`, `max_burst_size` will be reset based

3161

# on the value of

3162

# max_dispatches_per_second,

3163

# regardless of whether

3164

# max_dispatches_per_second

3165

# is updated.

Bu Sun Kim

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

[diff] [blame]

3166

},

Bu Sun Kim

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

[diff] [blame^]

3167

"stackdriverLoggingConfig": { # Configuration options for writing logs to # Configuration options for writing logs to

3168

# [Stackdriver Logging](https://cloud.google.com/logging/docs/). If this

3169

# field is unset, then no logs are written.

3170

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

3171

"samplingRatio": 3.14, # Specifies the fraction of operations to write to

3172

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

3173

# This field may contain any value between 0.0 and 1.0, inclusive.

3174

# 0.0 is the default and means that no operations are logged.

3175

},

3176

"appEngineRoutingOverride": { # App Engine Routing. # Overrides for

Bu Sun Kim

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

[diff] [blame]

3177

# task-level app_engine_routing.

3178

# These settings apply only to

3179

# App Engine tasks in this queue.

Dan O'Meara

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

[diff] [blame]

3180

# Http tasks are not affected.

Bu Sun Kim

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

[diff] [blame]

3181

#

3182

# If set, `app_engine_routing_override` is used for all

3183

# App Engine tasks in the queue, no matter what the

3184

# setting is for the

3185

# task-level app_engine_routing.

3186

#

3187

# Defines routing characteristics specific to App Engine - service, version,

3188

# and instance.

3189

#

3190

# For more information about services, versions, and instances see

3191

# [An Overview of App

3192

# Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),

3193

# [Microservices Architecture on Google App

3194

# Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine),

3195

# [App Engine Standard request

3196

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed),

3197

# and [App Engine Flex request

3198

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

Dan O'Meara

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

[diff] [blame]

3199

#

3200

# Using AppEngineRouting requires

3201

# [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)

3202

# Google IAM permission for the project

3203

# and the following scope:

3204

#

3205

# `https://www.googleapis.com/auth/cloud-platform`

Bu Sun Kim

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

[diff] [blame^]

3206

"service": "A String", # App service.

Bu Sun Kim

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

[diff] [blame]

3207

#

3208

# By default, the task is sent to the service which is the default

3209

# service when the task is attempted.

3210

#

3211

# For some queues or tasks which were created using the App Engine

3212

# Task Queue API, host is not parsable

3213

# into service,

3214

# version, and

3215

# instance. For example, some tasks

3216

# which were created using the App Engine SDK use a custom domain

3217

# name; custom domains are not parsed by Cloud Tasks. If

3218

# host is not parsable, then

3219

# service,

3220

# version, and

3221

# instance are the empty string.

Bu Sun Kim

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

[diff] [blame^]

3222

"instance": "A String", # App instance.

Dan O'Meara

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

[diff] [blame]

3223

#

Bu Sun Kim

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

[diff] [blame^]

3224

# By default, the task is sent to an instance which is available when

3225

# the task is attempted.

Bu Sun Kim

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

[diff] [blame]

3226

#

Bu Sun Kim

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

[diff] [blame^]

3227

# Requests can only be sent to a specific instance if

3228

# [manual scaling is used in App Engine

3229

# Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes).

3230

# App Engine Flex does not support instances. For more information, see

3231

# [App Engine Standard request

3232

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)

3233

# and [App Engine Flex request

3234

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

3235

"version": "A String", # App version.

Bu Sun Kim

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

[diff] [blame]

3236

#

Bu Sun Kim

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

[diff] [blame^]

3237

# By default, the task is sent to the version which is the default

3238

# version when the task is attempted.

Bu Sun Kim

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

[diff] [blame]

3239

#

Bu Sun Kim

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

[diff] [blame^]

3240

# For some queues or tasks which were created using the App Engine

3241

# Task Queue API, host is not parsable

3242

# into service,

3243

# version, and

3244

# instance. For example, some tasks

3245

# which were created using the App Engine SDK use a custom domain

3246

# name; custom domains are not parsed by Cloud Tasks. If

3247

# host is not parsable, then

3248

# service,

3249

# version, and

3250

# instance are the empty string.

3251

"host": "A String", # Output only. The host that the task is sent to.

Bu Sun Kim

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

[diff] [blame]

3252

#

Bu Sun Kim

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

[diff] [blame^]

3253

# The host is constructed from the domain name of the app associated with

3254

# the queue's project ID (for example <app-id>.appspot.com), and the

3255

# service, version,

3256

# and instance. Tasks which were created using

3257

# the App Engine SDK might have a custom domain name.

Bu Sun Kim

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

[diff] [blame]

3258

#

Bu Sun Kim

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

[diff] [blame^]

3259

# For more information, see

3260

# [How Requests are

3261

# Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed).

Bu Sun Kim

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

[diff] [blame]

},

}</pre>

</div>

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

3268

<pre>Resume a queue.

3269

3270

This method resumes a queue after it has been

3271

PAUSED or

3272

DISABLED. The state of a queue is stored

Bu Sun Kim

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

[diff] [blame^]

3273

in the queue's state; after calling this method it

Bu Sun Kim

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

[diff] [blame]

3274

will be set to RUNNING.

3275

3276

WARNING: Resuming many high-QPS queues at the same time can

3277

lead to target overloading. If you are resuming high-QPS

3278

queues, follow the 500/50/5 pattern described in

3279

[Managing Cloud Tasks Scaling

3280

Risks](https://cloud.google.com/tasks/docs/manage-cloud-task-scaling).

3281

3282

Args:

Dan O'Meara

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

[diff] [blame]

3283

Bu Sun Kim

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

[diff] [blame]

3284

`projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` (required)

3285

body: object, The request body.

3286

The object takes the form of:

3287

3288

{ # Request message for ResumeQueue.

3289

}

3290

3291

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

3298

3299

{ # A queue is a container of related tasks. Queues are configured to manage

3300

# how those tasks are dispatched. Configurable properties include rate limits,

3301

# retry options, queue types, and others.

Bu Sun Kim

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

[diff] [blame^]

3302

"purgeTime": "A String", # Output only. The last time this queue was purged.

3303

#

3304

# All tasks that were created before this time

3305

# were purged.

3306

#

3307

# A queue can be purged using PurgeQueue, the

3308

# [App Engine Task Queue SDK, or the Cloud

3309

# Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue).

3310

#

3311

# Purge time will be truncated to the nearest microsecond. Purge

3312

# time will be unset if the queue has never been purged.

3313

"retryConfig": { # Retry config. # Settings that determine the retry behavior.

3314

#

3315

# * For tasks created using Cloud Tasks: the queue-level retry settings

3316

# apply to all tasks in the queue that were created using Cloud Tasks.

3317

# Retry settings cannot be set on individual tasks.

3318

# * For tasks created using the App Engine SDK: the queue-level retry

3319

# settings apply to all tasks in the queue which do not have retry settings

3320

# explicitly set on the task and were created by the App Engine SDK. See

3321

# [App Engine

3322

# documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks).

3323

#

3324

# These settings determine when a failed task attempt is retried.

3325

"minBackoff": "A String", # A task will be scheduled for retry between

3326

# min_backoff and

3327

# max_backoff duration after it fails,

3328

# if the queue's RetryConfig specifies that the task should be

3329

# retried.

3330

#

3331

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `min_backoff` will be truncated to the nearest second.

3336

#

3337

# This field has the same meaning as

3338

# [min_backoff_seconds in

3339

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

3340

"maxBackoff": "A String", # A task will be scheduled for retry between

3341

# min_backoff and

3342

# max_backoff duration after it fails,

3343

# if the queue's RetryConfig specifies that the task should be

3344

# retried.

3345

#

3346

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_backoff` will be truncated to the nearest second.

3351

#

3352

# This field has the same meaning as

3353

# [max_backoff_seconds in

3354

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

3355

"maxRetryDuration": "A String", # If positive, `max_retry_duration` specifies the time limit for

3356

# retrying a failed task, measured from when the task was first

3357

# attempted. Once `max_retry_duration` time has passed *and* the

3358

# task has been attempted max_attempts

3359

# times, no further attempts will be made and the task will be

3360

# deleted.

3361

#

3362

# If zero, then the task age is unlimited.

3363

#

3364

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# `max_retry_duration` will be truncated to the nearest second.

3369

#

3370

# This field has the same meaning as

3371

# [task_age_limit in

3372

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

3373

"maxAttempts": 42, # Number of attempts per task.

3374

#

3375

# Cloud Tasks will attempt the task `max_attempts` times (that is, if the

3376

# first attempt fails, then there will be `max_attempts - 1` retries). Must

3377

# be >= -1.

3378

#

3379

# If unspecified when the queue is created, Cloud Tasks will pick the

3380

# default.

3381

#

3382

# -1 indicates unlimited attempts.

3383

#

3384

# This field has the same meaning as

3385

# [task_retry_limit in

3386

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

3387

"maxDoublings": 42, # The time between retries will double `max_doublings` times.

3388

#

3389

# A task's retry interval starts at

3390

# min_backoff, then doubles

3391

# `max_doublings` times, then increases linearly, and finally

3392

# retries at intervals of

3393

# max_backoff up to

3394

# max_attempts times.

3395

#

3396

# For example, if min_backoff is 10s,

3397

# max_backoff is 300s, and

3398

# `max_doublings` is 3, then the a task will first be retried in

3399

# 10s. The retry interval will double three times, and then

3400

# increase linearly by 2^3 * 10s. Finally, the task will retry at

3401

# intervals of max_backoff until the

3402

# task has been attempted max_attempts

3403

# times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s,

3404

# 240s, 300s, 300s, ....

3405

#

3406

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# This field has the same meaning as

3411

# [max_doublings in

3412

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).

3413

},

3414

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

3415

#

3416

# `state` can only be changed by called

3417

# PauseQueue,

3418

# ResumeQueue, or uploading

3419

# [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref).

3420

# UpdateQueue cannot be used to change `state`.

3421

"name": "A String", # Caller-specified and required in CreateQueue,

Bu Sun Kim

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

[diff] [blame]

3422

# after which it becomes output only.

#

# The queue name.

#

# The queue name must have the following format:

3427

# `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID`

3428

#

3429

# * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]),

3430

# hyphens (-), colons (:), or periods (.).

3431

# For more information, see

3432

# [Identifying

3433

# projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)

Bu Sun Kim

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

[diff] [blame^]

3434

# * `LOCATION_ID` is the canonical ID for the queue's location.

Bu Sun Kim

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

[diff] [blame]

3435

# The list of available locations can be obtained by calling

3436

# ListLocations.

3437

# For more information, see https://cloud.google.com/about/locations/.

3438

# * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or

3439

# hyphens (-). The maximum length is 100 characters.

Bu Sun Kim

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

[diff] [blame^]

3440

"rateLimits": { # Rate limits. # Rate limits for task dispatches.

Bu Sun Kim

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

[diff] [blame]

3441

#

3442

# rate_limits and retry_config are

3443

# related because they both control task attempts. However they control task

3444

# attempts in different ways:

3445

#

3446

# * rate_limits controls the total rate of

3447

# dispatches from a queue (i.e. all traffic dispatched from the

3448

# queue, regardless of whether the dispatch is from a first

3449

# attempt or a retry).

3450

# * retry_config controls what happens to

3451

# particular a task after its first attempt fails. That is,

3452

# retry_config controls task retries (the

3453

# second attempt, third attempt, etc).

3454

#

Bu Sun Kim

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

[diff] [blame^]

3455

# The queue's actual dispatch rate is the result of:

Bu Sun Kim

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

[diff] [blame]

3456

#

3457

# * Number of tasks in the queue

3458

# * User-specified throttling: rate_limits,

3459

# retry_config, and the

Bu Sun Kim

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

[diff] [blame^]

3460

# queue's state.

Bu Sun Kim

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

[diff] [blame]

3461

# * System throttling due to `429` (Too Many Requests) or `503` (Service

3462

# Unavailable) responses from the worker, high error rates, or to smooth

3463

# sudden large traffic spikes.

3464

#

3465

# This message determines the maximum rate that tasks can be dispatched by a

3466

# queue, regardless of whether the dispatch is a first task attempt or a retry.

3467

#

3468

# Note: The debugging command, RunTask, will run a task

3469

# even if the queue has reached its RateLimits.

Bu Sun Kim

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

[diff] [blame^]

3470

"maxConcurrentDispatches": 42, # The maximum number of concurrent tasks that Cloud Tasks allows

Bu Sun Kim

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

[diff] [blame]

3471

# to be dispatched for this queue. After this threshold has been

3472

# reached, Cloud Tasks stops dispatching tasks until the number of

3473

# concurrent requests decreases.

3474

#

3475

# If unspecified when the queue is created, Cloud Tasks will pick the

# default.

#

#

# The maximum allowed value is 5,000.

3480

#

3481

#

3482

# This field has the same meaning as

3483

# [max_concurrent_requests in

3484

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests).

Bu Sun Kim

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

[diff] [blame^]

3485

"maxDispatchesPerSecond": 3.14, # The maximum rate at which tasks are dispatched from this queue.

3486

#

3487

# If unspecified when the queue is created, Cloud Tasks will pick the

3488

# default.

3489

#

3490

# * The maximum allowed value is 500.

3491

#

3492

#

3493

# This field has the same meaning as

3494

# [rate in

3495

# queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate).

3496

"maxBurstSize": 42, # Output only. The max burst size.

Bu Sun Kim

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

[diff] [blame]

3497

#

3498

# Max burst size limits how fast tasks in queue are processed when

3499

# many tasks are in the queue and the rate is high. This field

3500

# allows the queue to have a high rate so processing starts shortly

3501

# after a task is enqueued, but still limits resource usage when

3502

# many tasks are enqueued in a short period of time.

3503

#

3504

# The [token bucket](https://wikipedia.org/wiki/Token_Bucket)

3505

# algorithm is used to control the rate of task dispatches. Each

3506

# queue has a token bucket that holds tokens, up to the maximum

3507

# specified by `max_burst_size`. Each time a task is dispatched, a

3508

# token is removed from the bucket. Tasks will be dispatched until

Bu Sun Kim

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

[diff] [blame^]

3509

# the queue's bucket runs out of tokens. The bucket will be

Bu Sun Kim

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

[diff] [blame]

3510

# continuously refilled with new tokens based on

3511

# max_dispatches_per_second.

3512

#

3513

# Cloud Tasks will pick the value of `max_burst_size` based on the

3514

# value of

3515

# max_dispatches_per_second.

3516

#

Dan O'Meara

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

[diff] [blame]

3517

# For queues that were created or updated using

Bu Sun Kim

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

[diff] [blame]

3518

# `queue.yaml/xml`, `max_burst_size` is equal to

3519

# [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size).

3520

# Since `max_burst_size` is output only, if

3521

# UpdateQueue is called on a queue

3522

# created by `queue.yaml/xml`, `max_burst_size` will be reset based

3523

# on the value of

3524

# max_dispatches_per_second,

3525

# regardless of whether

3526

# max_dispatches_per_second

3527

# is updated.

Bu Sun Kim

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

[diff] [blame]

3528

},

Bu Sun Kim

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

[diff] [blame^]

3529

"stackdriverLoggingConfig": { # Configuration options for writing logs to # Configuration options for writing logs to

3530

# [Stackdriver Logging](https://cloud.google.com/logging/docs/). If this

3531

# field is unset, then no logs are written.

3532

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

3533

"samplingRatio": 3.14, # Specifies the fraction of operations to write to

3534

# [Stackdriver Logging](https://cloud.google.com/logging/docs/).

3535

# This field may contain any value between 0.0 and 1.0, inclusive.

3536

# 0.0 is the default and means that no operations are logged.

3537

},

3538

"appEngineRoutingOverride": { # App Engine Routing. # Overrides for

Bu Sun Kim

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

[diff] [blame]

3539

# task-level app_engine_routing.

3540

# These settings apply only to

3541

# App Engine tasks in this queue.

Dan O'Meara

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

[diff] [blame]

3542

# Http tasks are not affected.

Bu Sun Kim

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

[diff] [blame]

3543

#

3544

# If set, `app_engine_routing_override` is used for all

3545

# App Engine tasks in the queue, no matter what the

3546

# setting is for the

3547

# task-level app_engine_routing.

3548

#

3549

# Defines routing characteristics specific to App Engine - service, version,

3550

# and instance.

3551

#

3552

# For more information about services, versions, and instances see

3553

# [An Overview of App

3554

# Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),

3555

# [Microservices Architecture on Google App

3556

# Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine),

3557

# [App Engine Standard request

3558

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed),

3559

# and [App Engine Flex request

3560

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

Dan O'Meara

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

[diff] [blame]

3561

#

3562

# Using AppEngineRouting requires

3563

# [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)

3564

# Google IAM permission for the project

3565

# and the following scope:

3566

#

3567

# `https://www.googleapis.com/auth/cloud-platform`

Bu Sun Kim

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

[diff] [blame^]

3568

"service": "A String", # App service.

Bu Sun Kim

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

[diff] [blame]

3569

#

3570

# By default, the task is sent to the service which is the default

3571

# service when the task is attempted.

3572

#

3573

# For some queues or tasks which were created using the App Engine

3574

# Task Queue API, host is not parsable

3575

# into service,

3576

# version, and

3577

# instance. For example, some tasks

3578

# which were created using the App Engine SDK use a custom domain

3579

# name; custom domains are not parsed by Cloud Tasks. If

3580

# host is not parsable, then

3581

# service,

3582

# version, and

3583

# instance are the empty string.

Bu Sun Kim

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

[diff] [blame^]

3584

"instance": "A String", # App instance.

Dan O'Meara

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

[diff] [blame]

3585

#

Bu Sun Kim

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

[diff] [blame^]

3586

# By default, the task is sent to an instance which is available when

3587

# the task is attempted.

Bu Sun Kim

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

[diff] [blame]

3588

#

Bu Sun Kim

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

[diff] [blame^]

3589

# Requests can only be sent to a specific instance if

3590

# [manual scaling is used in App Engine

3591

# Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes).

3592

# App Engine Flex does not support instances. For more information, see

3593

# [App Engine Standard request

3594

# routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)

3595

# and [App Engine Flex request

3596

# routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).

3597

"version": "A String", # App version.

Bu Sun Kim

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

[diff] [blame]

3598

#

Bu Sun Kim

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

[diff] [blame^]

3599

# By default, the task is sent to the version which is the default

3600

# version when the task is attempted.

Bu Sun Kim

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

[diff] [blame]

3601

#

Bu Sun Kim

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

[diff] [blame^]

3602

# For some queues or tasks which were created using the App Engine

3603

# Task Queue API, host is not parsable

3604

# into service,

3605

# version, and

3606

# instance. For example, some tasks

3607

# which were created using the App Engine SDK use a custom domain

3608

# name; custom domains are not parsed by Cloud Tasks. If

3609

# host is not parsable, then

3610

# service,

3611

# version, and

3612

# instance are the empty string.

3613

"host": "A String", # Output only. The host that the task is sent to.

Bu Sun Kim

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

[diff] [blame]

3614

#

Bu Sun Kim

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

[diff] [blame^]

3615

# The host is constructed from the domain name of the app associated with

3616

# the queue's project ID (for example <app-id>.appspot.com), and the

3617

# service, version,

3618

# and instance. Tasks which were created using

3619

# the App Engine SDK might have a custom domain name.

Bu Sun Kim

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

[diff] [blame]

3620

#

Bu Sun Kim

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

[diff] [blame^]

3621

# For more information, see

3622

# [How Requests are

3623

# Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed).

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]

3629

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

3630

<pre>Sets the access control policy for a Queue. Replaces any existing

3631

policy.

3632

3633

Note: The Cloud Console does not check queue-level IAM permissions yet.

3634

Project-level permissions are required to use the Cloud Console.

3635

3636

Authorization requires the following

3637

[Google IAM](https://cloud.google.com/iam) permission on the specified

3638

resource parent:

3639

3640

* `cloudtasks.queues.setIamPolicy`

3641

3642

Args:

3643

resource: string, REQUIRED: The resource for which the policy is being specified.

3644

See the operation documentation for the appropriate value for this field. (required)

Dan O'Meara

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

[diff] [blame]

3645

body: object, The request body.

Bu Sun Kim

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

[diff] [blame]

3646

The object takes the form of:

3647

3648

{ # Request message for `SetIamPolicy` method.

Bu Sun Kim

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

[diff] [blame^]

3649

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

3650

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

3651

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

3652

# might reject them.

Dan O'Meara

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

[diff] [blame]

3653

# controls for Google Cloud resources.

Bu Sun Kim

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

[diff] [blame]

3654

#

3655

#

Dan O'Meara

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

[diff] [blame]

3656

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

3657

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

3658

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

3659

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

3660

# custom role.

Bu Sun Kim

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

[diff] [blame]

3661

#

Bu Sun Kim

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

[diff] [blame^]

3662

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

3663

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

3664

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

3665

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

3666

# resources support conditions in their IAM policies, see the

3667

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

Dan O'Meara

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

[diff] [blame]

3668

#

3669

# **JSON example:**

Bu Sun Kim

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

[diff] [blame]

3670

#

3671

# {

Bu Sun Kim

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

[diff] [blame^]

3672

# "bindings": [

Bu Sun Kim

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

[diff] [blame]

3673

# {

Bu Sun Kim

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

[diff] [blame^]

3674

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

3675

# "members": [

3676

# "user:mike@example.com",

3677

# "group:admins@example.com",

3678

# "domain:google.com",

3679

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

Bu Sun Kim

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

[diff] [blame]

3680

# ]

3681

# },

3682

# {

Bu Sun Kim

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

[diff] [blame^]

3683

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

3684

# "members": [

3685

# "user:eve@example.com"

3686

# ],

3687

# "condition": {

3688

# "title": "expirable access",

3689

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

3690

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

Dan O'Meara

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

[diff] [blame]

3691

# }

Bu Sun Kim

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

[diff] [blame]

3692

# }

Dan O'Meara

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

[diff] [blame]

3693

# ],

Bu Sun Kim

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

[diff] [blame^]

3694

# "etag": "BwWWja0YfJA=",

3695

# "version": 3

Bu Sun Kim

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

[diff] [blame]

3696

# }

3697

#

Dan O'Meara

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

[diff] [blame]

3698

# **YAML example:**

Bu Sun Kim

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

[diff] [blame]

#

# bindings:

# - members:

# - user:mike@example.com

3703

# - group:admins@example.com

3704

# - domain:google.com

Dan O'Meara

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

[diff] [blame]

3705

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

3706

# role: roles/resourcemanager.organizationAdmin

Bu Sun Kim

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

[diff] [blame]

3707

# - members:

Dan O'Meara

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

[diff] [blame]

3708

# - user:eve@example.com

3709

# role: roles/resourcemanager.organizationViewer

3710

# condition:

3711

# title: expirable access

3712

# description: Does not grant access after Sep 2020

Bu Sun Kim

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

[diff] [blame^]

3713

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

Dan O'Meara

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

[diff] [blame]

3714

# - etag: BwWWja0YfJA=

3715

# - version: 3

Bu Sun Kim

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

[diff] [blame]

3716

#

3717

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

Dan O'Meara

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

[diff] [blame]

3718

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

Bu Sun Kim

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

[diff] [blame^]

3719

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

3720

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

3721

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

3722

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

3723

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

3724

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

3725

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

3726

#

3727

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

3728

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

3729

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

3730

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

3731

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

3732

#

3733

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

3734

# are rejected.

3735

#

3736

# Any operation that affects conditional role bindings must specify version

3737

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

3738

#

3739

# * Getting a policy that includes a conditional role binding

3740

# * Adding a conditional role binding to a policy

3741

# * Changing a conditional role binding in a policy

3742

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

3743

# that includes conditions

3744

#

3745

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

3746

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

3747

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

3748

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

3749

#

3750

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

3751

# specify any valid version or leave the field unset.

3752

#

3753

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

3754

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

3755

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

3756

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

3757

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

Bu Sun Kim

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

[diff] [blame]

3758

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

Bu Sun Kim

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

[diff] [blame^]

3759

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

Bu Sun Kim

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

[diff] [blame]

3760

# `members` can have the following values:

3761

#

3762

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

3763

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

3764

#

3765

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

3766

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

3767

#

3768

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

Dan O'Meara

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

[diff] [blame]

3769

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

Bu Sun Kim

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

[diff] [blame]

3770

#

3771

#

3772

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

3773

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

3774

#

3775

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

3776

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

3777

#

Dan O'Meara

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

[diff] [blame]

3778

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

3779

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

3780

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

3781

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

3782

# retains the role in the binding.

3783

#

3784

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

3785

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

3786

# deleted. For example,

3787

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

3788

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

3789

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

3790

# role in the binding.

3791

#

3792

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

3793

# identifier) representing a Google group that has been recently

3794

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

3795

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

3796

# recovered group retains the role in the binding.

3797

#

Bu Sun Kim

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

[diff] [blame]

3798

#

3799

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

3800

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

3801

#

Bu Sun Kim

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

[diff] [blame^]

3802

"A String",

Bu Sun Kim

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

[diff] [blame]

3803

],

Bu Sun Kim

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

[diff] [blame^]

3804

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

3805

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

3806

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

3807

#

3808

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

3809

# current request.

3810

#

3811

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

3812

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

3813

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

3814

#

3815

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

3816

# [IAM

3817

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

3818

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

3819

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

3820

#

3821

# Example (Comparison):

3822

#

3823

# title: "Summary size limit"

3824

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

3825

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

3826

#

3827

# Example (Equality):

3828

#

3829

# title: "Requestor is owner"

3830

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

3831

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

#

# Example (Logic):

#

# title: "Public documents"

3836

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

3837

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

3838

#

3839

# Example (Data Manipulation):

3840

#

3841

# title: "Notification string"

3842

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

3843

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

3844

#

3845

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

3846

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

3847

# documentation for additional information.

3848

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

3849

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

3850

# expression.

3851

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

3852

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

3853

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

3854

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

3855

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

3856

# syntax.

3857

},

Bu Sun Kim

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

[diff] [blame]

3858

},

3859

],

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:

3870

Dan O'Meara

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

[diff] [blame]

3871

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

3872

# controls for Google Cloud resources.

Bu Sun Kim

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

[diff] [blame]

3873

#

3874

#

Dan O'Meara

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

[diff] [blame]

3875

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

3876

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

3877

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

3878

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

3879

# custom role.

Bu Sun Kim

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

[diff] [blame]

3880

#

Bu Sun Kim

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

[diff] [blame^]

3881

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

3882

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

3883

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

3884

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

3885

# resources support conditions in their IAM policies, see the

3886

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

Dan O'Meara

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

[diff] [blame]

3887

#

3888

# **JSON example:**

Bu Sun Kim

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

[diff] [blame]

3889

#

3890

# {

Bu Sun Kim

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

[diff] [blame^]

3891

# "bindings": [

Bu Sun Kim

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

[diff] [blame]

3892

# {

Bu Sun Kim

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

[diff] [blame^]

3893

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

3894

# "members": [

3895

# "user:mike@example.com",

3896

# "group:admins@example.com",

3897

# "domain:google.com",

3898

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

Bu Sun Kim

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

[diff] [blame]

3899

# ]

3900

# },

3901

# {

Bu Sun Kim

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

[diff] [blame^]

3902

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

3903

# "members": [

3904

# "user:eve@example.com"

3905

# ],

3906

# "condition": {

3907

# "title": "expirable access",

3908

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

3909

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

Dan O'Meara

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

[diff] [blame]

3910

# }

Bu Sun Kim

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

[diff] [blame]

3911

# }

Dan O'Meara

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

[diff] [blame]

3912

# ],

Bu Sun Kim

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

[diff] [blame^]

3913

# "etag": "BwWWja0YfJA=",

3914

# "version": 3

Bu Sun Kim

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

[diff] [blame]

3915

# }

3916

#

Dan O'Meara

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

[diff] [blame]

3917

# **YAML example:**

Bu Sun Kim

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

[diff] [blame]

#

# bindings:

# - members:

# - user:mike@example.com

3922

# - group:admins@example.com

3923

# - domain:google.com

Dan O'Meara

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

[diff] [blame]

3924

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

3925

# role: roles/resourcemanager.organizationAdmin

Bu Sun Kim

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

[diff] [blame]

3926

# - members:

Dan O'Meara

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

[diff] [blame]

3927

# - user:eve@example.com

3928

# role: roles/resourcemanager.organizationViewer

3929

# condition:

3930

# title: expirable access

3931

# description: Does not grant access after Sep 2020

Bu Sun Kim

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

[diff] [blame^]

3932

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

Dan O'Meara

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

[diff] [blame]

3933

# - etag: BwWWja0YfJA=

3934

# - version: 3

Bu Sun Kim

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

[diff] [blame]

3935

#

3936

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

Dan O'Meara

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

[diff] [blame]

3937

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

Bu Sun Kim

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

[diff] [blame^]

3938

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

3939

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

3940

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

3941

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

3942

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

3943

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

3944

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

3945

#

3946

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

3947

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

3948

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

3949

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

3950

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

3951

#

3952

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

3953

# are rejected.

3954

#

3955

# Any operation that affects conditional role bindings must specify version

3956

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

3957

#

3958

# * Getting a policy that includes a conditional role binding

3959

# * Adding a conditional role binding to a policy

3960

# * Changing a conditional role binding in a policy

3961

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

3962

# that includes conditions

3963

#

3964

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

3965

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

3966

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

3967

# the conditions in the version `3` policy are lost.

3968

#

3969

# If a policy does not include any conditions, operations on that policy may

3970

# specify any valid version or leave the field unset.

3971

#

3972

# To learn which resources support conditions in their IAM policies, see the

3973

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

3974

"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]

3975

# `condition` that determines how and when the `bindings` are applied. Each

3976

# of the `bindings` must contain at least one member.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3977

{ # Associates `members` with a `role`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame^]

3978

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3979

# `members` can have the following values:

3980

#

3981

# * `allUsers`: A special identifier that represents anyone who is

3982

# on the internet; with or without a Google account.

3983

#

3984

# * `allAuthenticatedUsers`: A special identifier that represents anyone

3985

# who is authenticated with a Google account or a service account.

3986

#

3987

# * `user:{emailid}`: An email address that represents a specific Google

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3988

# account. For example, `alice@example.com` .

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3989

#

3990

#

3991

# * `serviceAccount:{emailid}`: An email address that represents a service

3992

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

3993

#

3994

# * `group:{emailid}`: An email address that represents a Google group.

3995

# For example, `admins@example.com`.

3996

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3997

# * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique

3998

# identifier) representing a user that has been recently deleted. For

3999

# example, `alice@example.com?uid=123456789012345678901`. If the user is

4000

# recovered, this value reverts to `user:{emailid}` and the recovered user

4001

# retains the role in the binding.

4002

#

4003

# * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus

4004

# unique identifier) representing a service account that has been recently

4005

# deleted. For example,

4006

# `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.

4007

# If the service account is undeleted, this value reverts to

4008

# `serviceAccount:{emailid}` and the undeleted service account retains the

4009

# role in the binding.

4010

#

4011

# * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique

4012

# identifier) representing a Google group that has been recently

4013

# deleted. For example, `admins@example.com?uid=123456789012345678901`. If

4014

# the group is recovered, this value reverts to `group:{emailid}` and the

4015

# recovered group retains the role in the binding.

4016

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4017

#

4018

# * `domain:{domain}`: The G Suite domain (primary) that represents all the

4019

# users of that domain. For example, `google.com` or `example.com`.

4020

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame^]

4021

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4022

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame^]

4023

"role": "A String", # Role that is assigned to `members`.

4024

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

4025

"condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.

4026

#

4027

# If the condition evaluates to `true`, then this binding applies to the

4028

# current request.

4029

#

4030

# If the condition evaluates to `false`, then this binding does not apply to

4031

# the current request. However, a different role binding might grant the same

4032

# role to one or more of the members in this binding.

4033

#

4034

# To learn which resources support conditions in their IAM policies, see the

4035

# [IAM

4036

# documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

4037

# syntax. CEL is a C-like expression language. The syntax and semantics of CEL

4038

# are documented at https://github.com/google/cel-spec.

4039

#

4040

# Example (Comparison):

4041

#

4042

# title: "Summary size limit"

4043

# description: "Determines if a summary is less than 100 chars"

4044

# expression: "document.summary.size() < 100"

4045

#

4046

# Example (Equality):

4047

#

4048

# title: "Requestor is owner"

4049

# description: "Determines if requestor is the document owner"

4050

# expression: "document.owner == request.auth.claims.email"

#

# Example (Logic):

#

# title: "Public documents"

4055

# description: "Determine whether the document should be publicly visible"

4056

# expression: "document.type != 'private' && document.type != 'internal'"

4057

#

4058

# Example (Data Manipulation):

4059

#

4060

# title: "Notification string"

4061

# description: "Create a notification string with a timestamp."

4062

# expression: "'New message received at ' + string(document.create_time)"

4063

#

4064

# The exact variables and functions that may be referenced within an expression

4065

# are determined by the service that evaluates it. See the service

4066

# documentation for additional information.

4067

"title": "A String", # Optional. Title for the expression, i.e. a short string describing

4068

# its purpose. This can be used e.g. in UIs which allow to enter the

4069

# expression.

4070

"location": "A String", # Optional. String indicating the location of the expression for error

4071

# reporting, e.g. a file name and a position in the file.

4072

"description": "A String", # Optional. Description of the expression. This is a longer text which

4073

# describes the expression, e.g. when hovered over it in a UI.

4074

"expression": "A String", # Textual representation of an expression in Common Expression Language

4075

# syntax.

4076

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4077

},

4078

],

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]

4083

<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]

4084

<pre>Returns permissions that a caller has on a Queue.

4085

If the resource does not exist, this will return an empty set of

4086

permissions, not a NOT_FOUND error.

4087

4088

Note: This operation is designed to be used for building permission-aware

4089

UIs and command-line tools, not for authorization checking. This operation

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame^]

4090

may "fail open" without warning.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4091

4092

Args:

4093

resource: string, REQUIRED: The resource for which the policy detail is being requested.

4094

See the operation documentation for the appropriate value for this field. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4095

body: object, The request body.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4096

The object takes the form of:

4097

4098

{ # Request message for `TestIamPermissions` method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame^]

4099

"permissions": [ # The set of permissions to check for the `resource`. Permissions with

4100

# wildcards (such as '*' or 'storage.*') are not allowed. For more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4101

# information see

4102

# [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame^]

4103

"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:

4114

4115

{ # Response message for `TestIamPermissions` method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame^]

4116

"permissions": [ # A subset of `TestPermissionsRequest.permissions` that the caller is

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4117

# allowed.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame^]

4118

"A String",

Bu Sun Kim