1 // Copyright 2018 Google LLC
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
7 // http://www.apache.org/licenses/LICENSE-2.0
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
17 package google.cloud.tasks.v2beta2;
19 import "google/api/annotations.proto";
20 import "google/cloud/tasks/v2beta2/target.proto";
21 import "google/protobuf/duration.proto";
22 import "google/protobuf/timestamp.proto";
24 option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta2;tasks";
25 option java_multiple_files = true;
26 option java_outer_classname = "QueueProto";
27 option java_package = "com.google.cloud.tasks.v2beta2";
29 // A queue is a container of related tasks. Queues are configured to manage
30 // how those tasks are dispatched. Configurable properties include rate limits,
31 // retry options, target types, and others.
33 // State of the queue.
36 STATE_UNSPECIFIED = 0;
38 // The queue is running. Tasks can be dispatched.
40 // If the queue was created using Cloud Tasks and the queue has
41 // had no activity (method calls or task dispatches) for 30 days,
42 // the queue may take a few minutes to re-activate. Some method
43 // calls may return [NOT_FOUND][google.rpc.Code.NOT_FOUND] and
44 // tasks may not be dispatched for a few minutes until the queue
45 // has been re-activated.
48 // Tasks are paused by the user. If the queue is paused then Cloud
49 // Tasks will stop delivering tasks from it, but more tasks can
50 // still be added to it by the user. When a pull queue is paused,
51 // all [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] calls
52 // will return a [FAILED_PRECONDITION][google.rpc.Code.FAILED_PRECONDITION].
55 // The queue is disabled.
57 // A queue becomes `DISABLED` when
58 // [queue.yaml](https://cloud.google.com/appengine/docs/python/config/queueref)
60 // [queue.xml](https://cloud.google.com/appengine/docs/standard/java/config/queueref)
61 // is uploaded which does not contain the queue. You cannot directly disable
64 // When a queue is disabled, tasks can still be added to a queue
65 // but the tasks are not dispatched and
66 // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] calls
67 // return a `FAILED_PRECONDITION` error.
69 // To permanently delete this queue and all of its tasks, call
70 // [DeleteQueue][google.cloud.tasks.v2beta2.CloudTasks.DeleteQueue].
74 // Caller-specified and required in
75 // [CreateQueue][google.cloud.tasks.v2beta2.CloudTasks.CreateQueue], after
76 // which it becomes output only.
80 // The queue name must have the following format:
81 // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID`
83 // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]),
84 // hyphens (-), colons (:), or periods (.).
85 // For more information, see
87 // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)
88 // * `LOCATION_ID` is the canonical ID for the queue's location.
89 // The list of available locations can be obtained by calling
90 // [ListLocations][google.cloud.location.Locations.ListLocations].
91 // For more information, see https://cloud.google.com/about/locations/.
92 // * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or
93 // hyphens (-). The maximum length is 100 characters.
96 // Caller-specified and required in
97 // [CreateQueue][google.cloud.tasks.v2beta2.CloudTasks.CreateQueue][], after
98 // which the queue config type becomes output only, though fields within the
99 // config are mutable.
101 // The queue's target.
103 // The target applies to all tasks in the queue.
105 // App Engine HTTP target.
107 // An App Engine queue is a queue that has an
108 // [AppEngineHttpTarget][google.cloud.tasks.v2beta2.AppEngineHttpTarget].
109 AppEngineHttpTarget app_engine_http_target = 3;
113 // A pull queue is a queue that has a
114 // [PullTarget][google.cloud.tasks.v2beta2.PullTarget].
115 PullTarget pull_target = 4;
118 // Rate limits for task dispatches.
120 // [rate_limits][google.cloud.tasks.v2beta2.Queue.rate_limits] and
121 // [retry_config][google.cloud.tasks.v2beta2.Queue.retry_config] are related
122 // because they both control task attempts however they control how tasks are
123 // attempted in different ways:
125 // * [rate_limits][google.cloud.tasks.v2beta2.Queue.rate_limits] controls the
127 // dispatches from a queue (i.e. all traffic dispatched from the
128 // queue, regardless of whether the dispatch is from a first
129 // attempt or a retry).
130 // * [retry_config][google.cloud.tasks.v2beta2.Queue.retry_config] controls
132 // particular a task after its first attempt fails. That is,
133 // [retry_config][google.cloud.tasks.v2beta2.Queue.retry_config] controls
134 // task retries (the second attempt, third attempt, etc).
135 RateLimits rate_limits = 5;
137 // Settings that determine the retry behavior.
139 // * For tasks created using Cloud Tasks: the queue-level retry settings
140 // apply to all tasks in the queue that were created using Cloud Tasks.
141 // Retry settings cannot be set on individual tasks.
142 // * For tasks created using the App Engine SDK: the queue-level retry
143 // settings apply to all tasks in the queue which do not have retry settings
144 // explicitly set on the task and were created by the App Engine SDK. See
146 // documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks).
147 RetryConfig retry_config = 6;
149 // Output only. The state of the queue.
151 // `state` can only be changed by called
152 // [PauseQueue][google.cloud.tasks.v2beta2.CloudTasks.PauseQueue],
153 // [ResumeQueue][google.cloud.tasks.v2beta2.CloudTasks.ResumeQueue], or
155 // [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref).
156 // [UpdateQueue][google.cloud.tasks.v2beta2.CloudTasks.UpdateQueue] cannot be
157 // used to change `state`.
160 // Output only. The last time this queue was purged.
162 // All tasks that were [created][google.cloud.tasks.v2beta2.Task.create_time]
163 // before this time were purged.
165 // A queue can be purged using
166 // [PurgeQueue][google.cloud.tasks.v2beta2.CloudTasks.PurgeQueue], the [App
167 // Engine Task Queue SDK, or the Cloud
168 // Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue).
170 // Purge time will be truncated to the nearest microsecond. Purge
171 // time will be unset if the queue has never been purged.
172 google.protobuf.Timestamp purge_time = 8;
177 // This message determines the maximum rate that tasks can be dispatched by a
178 // queue, regardless of whether the dispatch is a first task attempt or a retry.
180 // Note: The debugging command,
181 // [RunTask][google.cloud.tasks.v2beta2.CloudTasks.RunTask], will run a task
182 // even if the queue has reached its
183 // [RateLimits][google.cloud.tasks.v2beta2.RateLimits].
185 // The maximum rate at which tasks are dispatched from this queue.
187 // If unspecified when the queue is created, Cloud Tasks will pick the
190 // * For [App Engine queues][google.cloud.tasks.v2beta2.AppEngineHttpTarget],
191 // the maximum allowed value
193 // * This field is output only for [pull
194 // queues][google.cloud.tasks.v2beta2.PullTarget]. In addition to the
195 // `max_tasks_dispatched_per_second` limit, a maximum of 10 QPS of
196 // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] requests
197 // are allowed per pull queue.
200 // This field has the same meaning as
202 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate).
203 double max_tasks_dispatched_per_second = 1;
205 // Output only. The max burst size.
207 // Max burst size limits how fast tasks in queue are processed when
208 // many tasks are in the queue and the rate is high. This field
209 // allows the queue to have a high rate so processing starts shortly
210 // after a task is enqueued, but still limits resource usage when
211 // many tasks are enqueued in a short period of time.
213 // The [token bucket](https://wikipedia.org/wiki/Token_Bucket)
214 // algorithm is used to control the rate of task dispatches. Each
215 // queue has a token bucket that holds tokens, up to the maximum
216 // specified by `max_burst_size`. Each time a task is dispatched, a
217 // token is removed from the bucket. Tasks will be dispatched until
218 // the queue's bucket runs out of tokens. The bucket will be
219 // continuously refilled with new tokens based on
220 // [max_tasks_dispatched_per_second][google.cloud.tasks.v2beta2.RateLimits.max_tasks_dispatched_per_second].
222 // Cloud Tasks will pick the value of `max_burst_size` based on the
224 // [max_tasks_dispatched_per_second][google.cloud.tasks.v2beta2.RateLimits.max_tasks_dispatched_per_second].
226 // For App Engine queues that were created or updated using
227 // `queue.yaml/xml`, `max_burst_size` is equal to
228 // [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size).
229 // Since `max_burst_size` is output only, if
230 // [UpdateQueue][google.cloud.tasks.v2beta2.CloudTasks.UpdateQueue] is called
231 // on a queue created by `queue.yaml/xml`, `max_burst_size` will be reset
232 // based on the value of
233 // [max_tasks_dispatched_per_second][google.cloud.tasks.v2beta2.RateLimits.max_tasks_dispatched_per_second],
234 // regardless of whether
235 // [max_tasks_dispatched_per_second][google.cloud.tasks.v2beta2.RateLimits.max_tasks_dispatched_per_second]
238 int32 max_burst_size = 2;
240 // The maximum number of concurrent tasks that Cloud Tasks allows
241 // to be dispatched for this queue. After this threshold has been
242 // reached, Cloud Tasks stops dispatching tasks until the number of
243 // concurrent requests decreases.
245 // If unspecified when the queue is created, Cloud Tasks will pick the
249 // The maximum allowed value is 5,000.
251 // This field is output only for
252 // [pull queues][google.cloud.tasks.v2beta2.PullTarget] and always -1, which
253 // indicates no limit. No other queue types can have `max_concurrent_tasks`
257 // This field has the same meaning as
258 // [max_concurrent_requests in
259 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests).
260 int32 max_concurrent_tasks = 3;
265 // These settings determine how a failed task attempt is retried.
266 message RetryConfig {
267 // Number of attempts per task.
269 // If unspecified when the queue is created, Cloud Tasks will pick the
274 // This field has the same meaning as
275 // [task_retry_limit in
276 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).
278 // The maximum number of attempts for a task.
280 // Cloud Tasks will attempt the task `max_attempts` times (that
281 // is, if the first attempt fails, then there will be
282 // `max_attempts - 1` retries). Must be > 0.
283 int32 max_attempts = 1;
285 // If true, then the number of attempts is unlimited.
286 bool unlimited_attempts = 2;
289 // If positive, `max_retry_duration` specifies the time limit for
290 // retrying a failed task, measured from when the task was first
291 // attempted. Once `max_retry_duration` time has passed *and* the
292 // task has been attempted
293 // [max_attempts][google.cloud.tasks.v2beta2.RetryConfig.max_attempts] times,
294 // no further attempts will be made and the task will be deleted.
296 // If zero, then the task age is unlimited.
298 // If unspecified when the queue is created, Cloud Tasks will pick the
301 // This field is output only for [pull
302 // queues][google.cloud.tasks.v2beta2.PullTarget].
305 // `max_retry_duration` will be truncated to the nearest second.
307 // This field has the same meaning as
308 // [task_age_limit in
309 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).
310 google.protobuf.Duration max_retry_duration = 3;
312 // A task will be [scheduled][google.cloud.tasks.v2beta2.Task.schedule_time]
314 // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff] and
315 // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] duration
316 // after it fails, if the queue's
317 // [RetryConfig][google.cloud.tasks.v2beta2.RetryConfig] specifies that the
318 // task should be retried.
320 // If unspecified when the queue is created, Cloud Tasks will pick the
323 // This field is output only for [pull
324 // queues][google.cloud.tasks.v2beta2.PullTarget].
327 // `min_backoff` will be truncated to the nearest second.
329 // This field has the same meaning as
330 // [min_backoff_seconds in
331 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).
332 google.protobuf.Duration min_backoff = 4;
334 // A task will be [scheduled][google.cloud.tasks.v2beta2.Task.schedule_time]
336 // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff] and
337 // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] duration
338 // after it fails, if the queue's
339 // [RetryConfig][google.cloud.tasks.v2beta2.RetryConfig] specifies that the
340 // task should be retried.
342 // If unspecified when the queue is created, Cloud Tasks will pick the
345 // This field is output only for [pull
346 // queues][google.cloud.tasks.v2beta2.PullTarget].
349 // `max_backoff` will be truncated to the nearest second.
351 // This field has the same meaning as
352 // [max_backoff_seconds in
353 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).
354 google.protobuf.Duration max_backoff = 5;
356 // The time between retries will double `max_doublings` times.
358 // A task's retry interval starts at
359 // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff], then
360 // doubles `max_doublings` times, then increases linearly, and finally retries
361 // retries at intervals of
362 // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] up to
363 // [max_attempts][google.cloud.tasks.v2beta2.RetryConfig.max_attempts] times.
366 // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff] is 10s,
367 // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] is 300s,
368 // and `max_doublings` is 3, then the a task will first be retried in 10s. The
369 // retry interval will double three times, and then increase linearly by 2^3 *
370 // 10s. Finally, the task will retry at intervals of
371 // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] until the
372 // task has been attempted
373 // [max_attempts][google.cloud.tasks.v2beta2.RetryConfig.max_attempts] times.
374 // Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s, 240s, 300s,
377 // If unspecified when the queue is created, Cloud Tasks will pick the
380 // This field is output only for [pull
381 // queues][google.cloud.tasks.v2beta2.PullTarget].
384 // This field has the same meaning as
386 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).
387 int32 max_doublings = 6;