Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# -*- coding: utf-8 -*-
2# Copyright 2025 Google LLC
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15#
16from __future__ import annotations
18from typing import MutableMapping, MutableSequence
20from google.protobuf import duration_pb2 # type: ignore
21from google.protobuf import timestamp_pb2 # type: ignore
22import proto # type: ignore
24from google.cloud.tasks_v2.types import target
26__protobuf__ = proto.module(
27 package="google.cloud.tasks.v2",
28 manifest={
29 "Queue",
30 "RateLimits",
31 "RetryConfig",
32 "StackdriverLoggingConfig",
33 },
34)
37class Queue(proto.Message):
38 r"""A queue is a container of related tasks. Queues are
39 configured to manage how those tasks are dispatched.
40 Configurable properties include rate limits, retry options,
41 queue types, and others.
43 Attributes:
44 name (str):
45 Caller-specified and required in
46 [CreateQueue][google.cloud.tasks.v2.CloudTasks.CreateQueue],
47 after which it becomes output only.
49 The queue name.
51 The queue name must have the following format:
52 ``projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID``
54 - ``PROJECT_ID`` can contain letters ([A-Za-z]), numbers
55 ([0-9]), hyphens (-), colons (:), or periods (.). For
56 more information, see `Identifying
57 projects <https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects>`__
58 - ``LOCATION_ID`` is the canonical ID for the queue's
59 location. The list of available locations can be obtained
60 by calling
61 [ListLocations][google.cloud.location.Locations.ListLocations].
62 For more information, see
63 https://cloud.google.com/about/locations/.
64 - ``QUEUE_ID`` can contain letters ([A-Za-z]), numbers
65 ([0-9]), or hyphens (-). The maximum length is 100
66 characters.
67 app_engine_routing_override (google.cloud.tasks_v2.types.AppEngineRouting):
68 Overrides for [task-level
69 app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing].
70 These settings apply only to [App Engine
71 tasks][google.cloud.tasks.v2.AppEngineHttpRequest] in this
72 queue. [Http tasks][google.cloud.tasks.v2.HttpRequest] are
73 not affected.
75 If set, ``app_engine_routing_override`` is used for all [App
76 Engine tasks][google.cloud.tasks.v2.AppEngineHttpRequest] in
77 the queue, no matter what the setting is for the [task-level
78 app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing].
79 rate_limits (google.cloud.tasks_v2.types.RateLimits):
80 Rate limits for task dispatches.
82 [rate_limits][google.cloud.tasks.v2.Queue.rate_limits] and
83 [retry_config][google.cloud.tasks.v2.Queue.retry_config] are
84 related because they both control task attempts. However
85 they control task attempts in different ways:
87 - [rate_limits][google.cloud.tasks.v2.Queue.rate_limits]
88 controls the total rate of dispatches from a queue (i.e.
89 all traffic dispatched from the queue, regardless of
90 whether the dispatch is from a first attempt or a retry).
91 - [retry_config][google.cloud.tasks.v2.Queue.retry_config]
92 controls what happens to particular a task after its
93 first attempt fails. That is,
94 [retry_config][google.cloud.tasks.v2.Queue.retry_config]
95 controls task retries (the second attempt, third attempt,
96 etc).
98 The queue's actual dispatch rate is the result of:
100 - Number of tasks in the queue
101 - User-specified throttling:
102 [rate_limits][google.cloud.tasks.v2.Queue.rate_limits],
103 [retry_config][google.cloud.tasks.v2.Queue.retry_config],
104 and the [queue's
105 state][google.cloud.tasks.v2.Queue.state].
106 - System throttling due to ``429`` (Too Many Requests) or
107 ``503`` (Service Unavailable) responses from the worker,
108 high error rates, or to smooth sudden large traffic
109 spikes.
110 retry_config (google.cloud.tasks_v2.types.RetryConfig):
111 Settings that determine the retry behavior.
113 - For tasks created using Cloud Tasks: the queue-level
114 retry settings apply to all tasks in the queue that were
115 created using Cloud Tasks. Retry settings cannot be set
116 on individual tasks.
117 - For tasks created using the App Engine SDK: the
118 queue-level retry settings apply to all tasks in the
119 queue which do not have retry settings explicitly set on
120 the task and were created by the App Engine SDK. See `App
121 Engine
122 documentation <https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks>`__.
123 state (google.cloud.tasks_v2.types.Queue.State):
124 Output only. The state of the queue.
126 ``state`` can only be changed by calling
127 [PauseQueue][google.cloud.tasks.v2.CloudTasks.PauseQueue],
128 [ResumeQueue][google.cloud.tasks.v2.CloudTasks.ResumeQueue],
129 or uploading
130 `queue.yaml/xml <https://cloud.google.com/appengine/docs/python/config/queueref>`__.
131 [UpdateQueue][google.cloud.tasks.v2.CloudTasks.UpdateQueue]
132 cannot be used to change ``state``.
133 purge_time (google.protobuf.timestamp_pb2.Timestamp):
134 Output only. The last time this queue was purged.
136 All tasks that were
137 [created][google.cloud.tasks.v2.Task.create_time] before
138 this time were purged.
140 A queue can be purged using
141 [PurgeQueue][google.cloud.tasks.v2.CloudTasks.PurgeQueue],
142 the `App Engine Task Queue SDK, or the Cloud
143 Console <https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue>`__.
145 Purge time will be truncated to the nearest microsecond.
146 Purge time will be unset if the queue has never been purged.
147 stackdriver_logging_config (google.cloud.tasks_v2.types.StackdriverLoggingConfig):
148 Configuration options for writing logs to `Stackdriver
149 Logging <https://cloud.google.com/logging/docs/>`__. If this
150 field is unset, then no logs are written.
151 """
153 class State(proto.Enum):
154 r"""State of the queue.
156 Values:
157 STATE_UNSPECIFIED (0):
158 Unspecified state.
159 RUNNING (1):
160 The queue is running. Tasks can be dispatched.
162 If the queue was created using Cloud Tasks and the queue has
163 had no activity (method calls or task dispatches) for 30
164 days, the queue may take a few minutes to re-activate. Some
165 method calls may return
166 [NOT_FOUND][google.rpc.Code.NOT_FOUND] and tasks may not be
167 dispatched for a few minutes until the queue has been
168 re-activated.
169 PAUSED (2):
170 Tasks are paused by the user. If the queue is
171 paused then Cloud Tasks will stop delivering
172 tasks from it, but more tasks can still be added
173 to it by the user.
174 DISABLED (3):
175 The queue is disabled.
177 A queue becomes ``DISABLED`` when
178 `queue.yaml <https://cloud.google.com/appengine/docs/python/config/queueref>`__
179 or
180 `queue.xml <https://cloud.google.com/appengine/docs/standard/java/config/queueref>`__
181 is uploaded which does not contain the queue. You cannot
182 directly disable a queue.
184 When a queue is disabled, tasks can still be added to a
185 queue but the tasks are not dispatched.
187 To permanently delete this queue and all of its tasks, call
188 [DeleteQueue][google.cloud.tasks.v2.CloudTasks.DeleteQueue].
189 """
190 STATE_UNSPECIFIED = 0
191 RUNNING = 1
192 PAUSED = 2
193 DISABLED = 3
195 name: str = proto.Field(
196 proto.STRING,
197 number=1,
198 )
199 app_engine_routing_override: target.AppEngineRouting = proto.Field(
200 proto.MESSAGE,
201 number=2,
202 message=target.AppEngineRouting,
203 )
204 rate_limits: "RateLimits" = proto.Field(
205 proto.MESSAGE,
206 number=3,
207 message="RateLimits",
208 )
209 retry_config: "RetryConfig" = proto.Field(
210 proto.MESSAGE,
211 number=4,
212 message="RetryConfig",
213 )
214 state: State = proto.Field(
215 proto.ENUM,
216 number=5,
217 enum=State,
218 )
219 purge_time: timestamp_pb2.Timestamp = proto.Field(
220 proto.MESSAGE,
221 number=6,
222 message=timestamp_pb2.Timestamp,
223 )
224 stackdriver_logging_config: "StackdriverLoggingConfig" = proto.Field(
225 proto.MESSAGE,
226 number=9,
227 message="StackdriverLoggingConfig",
228 )
231class RateLimits(proto.Message):
232 r"""Rate limits.
234 This message determines the maximum rate that tasks can be
235 dispatched by a queue, regardless of whether the dispatch is a first
236 task attempt or a retry.
238 Note: The debugging command,
239 [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask], will run a task
240 even if the queue has reached its
241 [RateLimits][google.cloud.tasks.v2.RateLimits].
243 Attributes:
244 max_dispatches_per_second (float):
245 The maximum rate at which tasks are dispatched from this
246 queue.
248 If unspecified when the queue is created, Cloud Tasks will
249 pick the default.
251 - The maximum allowed value is 500.
253 This field has the same meaning as `rate in
254 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate>`__.
255 max_burst_size (int):
256 Output only. The max burst size.
258 Max burst size limits how fast tasks in queue are processed
259 when many tasks are in the queue and the rate is high. This
260 field allows the queue to have a high rate so processing
261 starts shortly after a task is enqueued, but still limits
262 resource usage when many tasks are enqueued in a short
263 period of time.
265 The `token
266 bucket <https://wikipedia.org/wiki/Token_Bucket>`__
267 algorithm is used to control the rate of task dispatches.
268 Each queue has a token bucket that holds tokens, up to the
269 maximum specified by ``max_burst_size``. Each time a task is
270 dispatched, a token is removed from the bucket. Tasks will
271 be dispatched until the queue's bucket runs out of tokens.
272 The bucket will be continuously refilled with new tokens
273 based on
274 [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second].
276 Cloud Tasks will pick the value of ``max_burst_size`` based
277 on the value of
278 [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second].
280 For queues that were created or updated using
281 ``queue.yaml/xml``, ``max_burst_size`` is equal to
282 `bucket_size <https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size>`__.
283 Since ``max_burst_size`` is output only, if
284 [UpdateQueue][google.cloud.tasks.v2.CloudTasks.UpdateQueue]
285 is called on a queue created by ``queue.yaml/xml``,
286 ``max_burst_size`` will be reset based on the value of
287 [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second],
288 regardless of whether
289 [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second]
290 is updated.
291 max_concurrent_dispatches (int):
292 The maximum number of concurrent tasks that Cloud Tasks
293 allows to be dispatched for this queue. After this threshold
294 has been reached, Cloud Tasks stops dispatching tasks until
295 the number of concurrent requests decreases.
297 If unspecified when the queue is created, Cloud Tasks will
298 pick the default.
300 The maximum allowed value is 5,000.
302 This field has the same meaning as `max_concurrent_requests
303 in
304 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests>`__.
305 """
307 max_dispatches_per_second: float = proto.Field(
308 proto.DOUBLE,
309 number=1,
310 )
311 max_burst_size: int = proto.Field(
312 proto.INT32,
313 number=2,
314 )
315 max_concurrent_dispatches: int = proto.Field(
316 proto.INT32,
317 number=3,
318 )
321class RetryConfig(proto.Message):
322 r"""Retry config.
324 These settings determine when a failed task attempt is retried.
326 Attributes:
327 max_attempts (int):
328 Number of attempts per task.
330 Cloud Tasks will attempt the task ``max_attempts`` times
331 (that is, if the first attempt fails, then there will be
332 ``max_attempts - 1`` retries). Must be >= -1.
334 If unspecified when the queue is created, Cloud Tasks will
335 pick the default.
337 -1 indicates unlimited attempts.
339 This field has the same meaning as `task_retry_limit in
340 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters>`__.
341 max_retry_duration (google.protobuf.duration_pb2.Duration):
342 If positive, ``max_retry_duration`` specifies the time limit
343 for retrying a failed task, measured from when the task was
344 first attempted. Once ``max_retry_duration`` time has passed
345 *and* the task has been attempted
346 [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts]
347 times, no further attempts will be made and the task will be
348 deleted.
350 If zero, then the task age is unlimited.
352 If unspecified when the queue is created, Cloud Tasks will
353 pick the default.
355 ``max_retry_duration`` will be truncated to the nearest
356 second.
358 This field has the same meaning as `task_age_limit in
359 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters>`__.
360 min_backoff (google.protobuf.duration_pb2.Duration):
361 A task will be
362 [scheduled][google.cloud.tasks.v2.Task.schedule_time] for
363 retry between
364 [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff]
365 and
366 [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff]
367 duration after it fails, if the queue's
368 [RetryConfig][google.cloud.tasks.v2.RetryConfig] specifies
369 that the task should be retried.
371 If unspecified when the queue is created, Cloud Tasks will
372 pick the default.
374 ``min_backoff`` will be truncated to the nearest second.
376 This field has the same meaning as `min_backoff_seconds in
377 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters>`__.
378 max_backoff (google.protobuf.duration_pb2.Duration):
379 A task will be
380 [scheduled][google.cloud.tasks.v2.Task.schedule_time] for
381 retry between
382 [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff]
383 and
384 [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff]
385 duration after it fails, if the queue's
386 [RetryConfig][google.cloud.tasks.v2.RetryConfig] specifies
387 that the task should be retried.
389 If unspecified when the queue is created, Cloud Tasks will
390 pick the default.
392 ``max_backoff`` will be truncated to the nearest second.
394 This field has the same meaning as `max_backoff_seconds in
395 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters>`__.
396 max_doublings (int):
397 The time between retries will double ``max_doublings``
398 times.
400 A task's retry interval starts at
401 [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff],
402 then doubles ``max_doublings`` times, then increases
403 linearly, and finally retries at intervals of
404 [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff]
405 up to
406 [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts]
407 times.
409 For example, if
410 [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff]
411 is 10s,
412 [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff]
413 is 300s, and ``max_doublings`` is 3, then the a task will
414 first be retried in 10s. The retry interval will double
415 three times, and then increase linearly by 2^3 \* 10s.
416 Finally, the task will retry at intervals of
417 [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff]
418 until the task has been attempted
419 [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts]
420 times. Thus, the requests will retry at 10s, 20s, 40s, 80s,
421 160s, 240s, 300s, 300s, ....
423 If unspecified when the queue is created, Cloud Tasks will
424 pick the default.
426 This field has the same meaning as `max_doublings in
427 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters>`__.
428 """
430 max_attempts: int = proto.Field(
431 proto.INT32,
432 number=1,
433 )
434 max_retry_duration: duration_pb2.Duration = proto.Field(
435 proto.MESSAGE,
436 number=2,
437 message=duration_pb2.Duration,
438 )
439 min_backoff: duration_pb2.Duration = proto.Field(
440 proto.MESSAGE,
441 number=3,
442 message=duration_pb2.Duration,
443 )
444 max_backoff: duration_pb2.Duration = proto.Field(
445 proto.MESSAGE,
446 number=4,
447 message=duration_pb2.Duration,
448 )
449 max_doublings: int = proto.Field(
450 proto.INT32,
451 number=5,
452 )
455class StackdriverLoggingConfig(proto.Message):
456 r"""Configuration options for writing logs to `Stackdriver
457 Logging <https://cloud.google.com/logging/docs/>`__.
459 Attributes:
460 sampling_ratio (float):
461 Specifies the fraction of operations to write to
462 `Stackdriver
463 Logging <https://cloud.google.com/logging/docs/>`__. This
464 field may contain any value between 0.0 and 1.0, inclusive.
465 0.0 is the default and means that no operations are logged.
466 """
468 sampling_ratio: float = proto.Field(
469 proto.DOUBLE,
470 number=1,
471 )
474__all__ = tuple(sorted(__protobuf__.manifest))