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
20import proto # type: ignore
22__protobuf__ = proto.module(
23 package="google.cloud.tasks.v2",
24 manifest={
25 "HttpMethod",
26 "HttpRequest",
27 "AppEngineHttpRequest",
28 "AppEngineRouting",
29 "OAuthToken",
30 "OidcToken",
31 },
32)
35class HttpMethod(proto.Enum):
36 r"""The HTTP method used to deliver the task.
38 Values:
39 HTTP_METHOD_UNSPECIFIED (0):
40 HTTP method unspecified
41 POST (1):
42 HTTP POST
43 GET (2):
44 HTTP GET
45 HEAD (3):
46 HTTP HEAD
47 PUT (4):
48 HTTP PUT
49 DELETE (5):
50 HTTP DELETE
51 PATCH (6):
52 HTTP PATCH
53 OPTIONS (7):
54 HTTP OPTIONS
55 """
56 HTTP_METHOD_UNSPECIFIED = 0
57 POST = 1
58 GET = 2
59 HEAD = 3
60 PUT = 4
61 DELETE = 5
62 PATCH = 6
63 OPTIONS = 7
66class HttpRequest(proto.Message):
67 r"""HTTP request.
69 The task will be pushed to the worker as an HTTP request. If the
70 worker or the redirected worker acknowledges the task by returning a
71 successful HTTP response code ([``200`` - ``299``]), the task will
72 be removed from the queue. If any other HTTP response code is
73 returned or no response is received, the task will be retried
74 according to the following:
76 - User-specified throttling: [retry
77 configuration][google.cloud.tasks.v2.Queue.retry_config], [rate
78 limits][google.cloud.tasks.v2.Queue.rate_limits], and the
79 [queue's state][google.cloud.tasks.v2.Queue.state].
81 - System throttling: To prevent the worker from overloading, Cloud
82 Tasks may temporarily reduce the queue's effective rate.
83 User-specified settings will not be changed.
85 System throttling happens because:
87 - Cloud Tasks backs off on all errors. Normally the backoff
88 specified in [rate
89 limits][google.cloud.tasks.v2.Queue.rate_limits] will be used.
90 But if the worker returns ``429`` (Too Many Requests), ``503``
91 (Service Unavailable), or the rate of errors is high, Cloud Tasks
92 will use a higher backoff rate. The retry specified in the
93 ``Retry-After`` HTTP response header is considered.
95 - To prevent traffic spikes and to smooth sudden increases in
96 traffic, dispatches ramp up slowly when the queue is newly
97 created or idle and if large numbers of tasks suddenly become
98 available to dispatch (due to spikes in create task rates, the
99 queue being unpaused, or many tasks that are scheduled at the
100 same time).
102 This message has `oneof`_ fields (mutually exclusive fields).
103 For each oneof, at most one member field can be set at the same time.
104 Setting any member of the oneof automatically clears all other
105 members.
107 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
109 Attributes:
110 url (str):
111 Required. The full url path that the request will be sent
112 to.
114 This string must begin with either "http://" or "https://".
115 Some examples are: ``http://acme.com`` and
116 ``https://acme.com/sales:8080``. Cloud Tasks will encode
117 some characters for safety and compatibility. The maximum
118 allowed URL length is 2083 characters after encoding.
120 The ``Location`` header response from a redirect response
121 [``300`` - ``399``] may be followed. The redirect is not
122 counted as a separate attempt.
123 http_method (google.cloud.tasks_v2.types.HttpMethod):
124 The HTTP method to use for the request. The
125 default is POST.
126 headers (MutableMapping[str, str]):
127 HTTP request headers.
129 This map contains the header field names and values. Headers
130 can be set when the [task is
131 created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask].
133 These headers represent a subset of the headers that will
134 accompany the task's HTTP request. Some HTTP request headers
135 will be ignored or replaced.
137 A partial list of headers that will be ignored or replaced
138 is:
140 - Host: This will be computed by Cloud Tasks and derived
141 from
142 [HttpRequest.url][google.cloud.tasks.v2.HttpRequest.url].
143 - Content-Length: This will be computed by Cloud Tasks.
144 - User-Agent: This will be set to ``"Google-Cloud-Tasks"``.
145 - ``X-Google-*``: Google use only.
146 - ``X-AppEngine-*``: Google use only.
148 ``Content-Type`` won't be set by Cloud Tasks. You can
149 explicitly set ``Content-Type`` to a media type when the
150 [task is
151 created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask].
152 For example, ``Content-Type`` can be set to
153 ``"application/octet-stream"`` or ``"application/json"``.
155 Headers which can have multiple values (according to
156 RFC2616) can be specified using comma-separated values.
158 The size of the headers must be less than 80KB.
159 body (bytes):
160 HTTP request body.
162 A request body is allowed only if the [HTTP
163 method][google.cloud.tasks.v2.HttpRequest.http_method] is
164 POST, PUT, or PATCH. It is an error to set body on a task
165 with an incompatible
166 [HttpMethod][google.cloud.tasks.v2.HttpMethod].
167 oauth_token (google.cloud.tasks_v2.types.OAuthToken):
168 If specified, an `OAuth
169 token <https://developers.google.com/identity/protocols/OAuth2>`__
170 will be generated and attached as an ``Authorization``
171 header in the HTTP request.
173 This type of authorization should generally only be used
174 when calling Google APIs hosted on \*.googleapis.com.
176 This field is a member of `oneof`_ ``authorization_header``.
177 oidc_token (google.cloud.tasks_v2.types.OidcToken):
178 If specified, an
179 `OIDC <https://developers.google.com/identity/protocols/OpenIDConnect>`__
180 token will be generated and attached as an ``Authorization``
181 header in the HTTP request.
183 This type of authorization can be used for many scenarios,
184 including calling Cloud Run, or endpoints where you intend
185 to validate the token yourself.
187 This field is a member of `oneof`_ ``authorization_header``.
188 """
190 url: str = proto.Field(
191 proto.STRING,
192 number=1,
193 )
194 http_method: "HttpMethod" = proto.Field(
195 proto.ENUM,
196 number=2,
197 enum="HttpMethod",
198 )
199 headers: MutableMapping[str, str] = proto.MapField(
200 proto.STRING,
201 proto.STRING,
202 number=3,
203 )
204 body: bytes = proto.Field(
205 proto.BYTES,
206 number=4,
207 )
208 oauth_token: "OAuthToken" = proto.Field(
209 proto.MESSAGE,
210 number=5,
211 oneof="authorization_header",
212 message="OAuthToken",
213 )
214 oidc_token: "OidcToken" = proto.Field(
215 proto.MESSAGE,
216 number=6,
217 oneof="authorization_header",
218 message="OidcToken",
219 )
222class AppEngineHttpRequest(proto.Message):
223 r"""App Engine HTTP request.
225 The message defines the HTTP request that is sent to an App Engine
226 app when the task is dispatched.
228 Using
229 [AppEngineHttpRequest][google.cloud.tasks.v2.AppEngineHttpRequest]
230 requires
231 ```appengine.applications.get`` <https://cloud.google.com/appengine/docs/admin-api/access-control>`__
232 Google IAM permission for the project and the following scope:
234 ``https://www.googleapis.com/auth/cloud-platform``
236 The task will be delivered to the App Engine app which belongs to
237 the same project as the queue. For more information, see `How
238 Requests are
239 Routed <https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed>`__
240 and how routing is affected by `dispatch
241 files <https://cloud.google.com/appengine/docs/python/config/dispatchref>`__.
242 Traffic is encrypted during transport and never leaves Google
243 datacenters. Because this traffic is carried over a communication
244 mechanism internal to Google, you cannot explicitly set the protocol
245 (for example, HTTP or HTTPS). The request to the handler, however,
246 will appear to have used the HTTP protocol.
248 The [AppEngineRouting][google.cloud.tasks.v2.AppEngineRouting] used
249 to construct the URL that the task is delivered to can be set at the
250 queue-level or task-level:
252 - If [app_engine_routing_override is set on the
253 queue][google.cloud.tasks.v2.Queue.app_engine_routing_override],
254 this value is used for all tasks in the queue, no matter what the
255 setting is for the [task-level
256 app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing].
258 The ``url`` that the task will be sent to is:
260 - ``url =`` [host][google.cloud.tasks.v2.AppEngineRouting.host]
261 ``+``
262 [relative_uri][google.cloud.tasks.v2.AppEngineHttpRequest.relative_uri]
264 Tasks can be dispatched to secure app handlers, unsecure app
265 handlers, and URIs restricted with
266 ```login: admin`` <https://cloud.google.com/appengine/docs/standard/python/config/appref>`__.
267 Because tasks are not run as any user, they cannot be dispatched to
268 URIs restricted with
269 ```login: required`` <https://cloud.google.com/appengine/docs/standard/python/config/appref>`__
270 Task dispatches also do not follow redirects.
272 The task attempt has succeeded if the app's request handler returns
273 an HTTP response code in the range [``200`` - ``299``]. The task
274 attempt has failed if the app's handler returns a non-2xx response
275 code or Cloud Tasks does not receive response before the
276 [deadline][google.cloud.tasks.v2.Task.dispatch_deadline]. Failed
277 tasks will be retried according to the [retry
278 configuration][google.cloud.tasks.v2.Queue.retry_config]. ``503``
279 (Service Unavailable) is considered an App Engine system error
280 instead of an application error and will cause Cloud Tasks' traffic
281 congestion control to temporarily throttle the queue's dispatches.
282 Unlike other types of task targets, a ``429`` (Too Many Requests)
283 response from an app handler does not cause traffic congestion
284 control to throttle the queue.
286 Attributes:
287 http_method (google.cloud.tasks_v2.types.HttpMethod):
288 The HTTP method to use for the request. The default is POST.
290 The app's request handler for the task's target URL must be
291 able to handle HTTP requests with this http_method,
292 otherwise the task attempt fails with error code 405 (Method
293 Not Allowed). See `Writing a push task request
294 handler <https://cloud.google.com/appengine/docs/java/taskqueue/push/creating-handlers#writing_a_push_task_request_handler>`__
295 and the App Engine documentation for your runtime on `How
296 Requests are
297 Handled <https://cloud.google.com/appengine/docs/standard/python3/how-requests-are-handled>`__.
298 app_engine_routing (google.cloud.tasks_v2.types.AppEngineRouting):
299 Task-level setting for App Engine routing.
301 - If [app_engine_routing_override is set on the
302 queue][google.cloud.tasks.v2.Queue.app_engine_routing_override],
303 this value is used for all tasks in the queue, no matter
304 what the setting is for the [task-level
305 app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing].
306 relative_uri (str):
307 The relative URI.
309 The relative URI must begin with "/" and must be
310 a valid HTTP relative URI. It can contain a path
311 and query string arguments. If the relative URI
312 is empty, then the root path "/" will be used.
313 No spaces are allowed, and the maximum length
314 allowed is 2083 characters.
315 headers (MutableMapping[str, str]):
316 HTTP request headers.
318 This map contains the header field names and values. Headers
319 can be set when the [task is
320 created][google.cloud.tasks.v2.CloudTasks.CreateTask].
321 Repeated headers are not supported but a header value can
322 contain commas.
324 Cloud Tasks sets some headers to default values:
326 - ``User-Agent``: By default, this header is
327 ``"AppEngine-Google; (+http://code.google.com/appengine)"``.
328 This header can be modified, but Cloud Tasks will append
329 ``"AppEngine-Google; (+http://code.google.com/appengine)"``
330 to the modified ``User-Agent``.
332 If the task has a
333 [body][google.cloud.tasks.v2.AppEngineHttpRequest.body],
334 Cloud Tasks sets the following headers:
336 - ``Content-Type``: By default, the ``Content-Type`` header
337 is set to ``"application/octet-stream"``. The default can
338 be overridden by explicitly setting ``Content-Type`` to a
339 particular media type when the [task is
340 created][google.cloud.tasks.v2.CloudTasks.CreateTask].
341 For example, ``Content-Type`` can be set to
342 ``"application/json"``.
343 - ``Content-Length``: This is computed by Cloud Tasks. This
344 value is output only. It cannot be changed.
346 The headers below cannot be set or overridden:
348 - ``Host``
349 - ``X-Google-*``
350 - ``X-AppEngine-*``
352 In addition, Cloud Tasks sets some headers when the task is
353 dispatched, such as headers containing information about the
354 task; see `request
355 headers <https://cloud.google.com/tasks/docs/creating-appengine-handlers#reading_request_headers>`__.
356 These headers are set only when the task is dispatched, so
357 they are not visible when the task is returned in a Cloud
358 Tasks response.
360 Although there is no specific limit for the maximum number
361 of headers or the size, there is a limit on the maximum size
362 of the [Task][google.cloud.tasks.v2.Task]. For more
363 information, see the
364 [CreateTask][google.cloud.tasks.v2.CloudTasks.CreateTask]
365 documentation.
366 body (bytes):
367 HTTP request body.
369 A request body is allowed only if the HTTP method is POST or
370 PUT. It is an error to set a body on a task with an
371 incompatible [HttpMethod][google.cloud.tasks.v2.HttpMethod].
372 """
374 http_method: "HttpMethod" = proto.Field(
375 proto.ENUM,
376 number=1,
377 enum="HttpMethod",
378 )
379 app_engine_routing: "AppEngineRouting" = proto.Field(
380 proto.MESSAGE,
381 number=2,
382 message="AppEngineRouting",
383 )
384 relative_uri: str = proto.Field(
385 proto.STRING,
386 number=3,
387 )
388 headers: MutableMapping[str, str] = proto.MapField(
389 proto.STRING,
390 proto.STRING,
391 number=4,
392 )
393 body: bytes = proto.Field(
394 proto.BYTES,
395 number=5,
396 )
399class AppEngineRouting(proto.Message):
400 r"""App Engine Routing.
402 Defines routing characteristics specific to App Engine - service,
403 version, and instance.
405 For more information about services, versions, and instances see `An
406 Overview of App
407 Engine <https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine>`__,
408 `Microservices Architecture on Google App
409 Engine <https://cloud.google.com/appengine/docs/python/microservices-on-app-engine>`__,
410 `App Engine Standard request
411 routing <https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed>`__,
412 and `App Engine Flex request
413 routing <https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed>`__.
415 Using [AppEngineRouting][google.cloud.tasks.v2.AppEngineRouting]
416 requires
417 ```appengine.applications.get`` <https://cloud.google.com/appengine/docs/admin-api/access-control>`__
418 Google IAM permission for the project and the following scope:
420 ``https://www.googleapis.com/auth/cloud-platform``
422 Attributes:
423 service (str):
424 App service.
426 By default, the task is sent to the service which is the
427 default service when the task is attempted.
429 For some queues or tasks which were created using the App
430 Engine Task Queue API,
431 [host][google.cloud.tasks.v2.AppEngineRouting.host] is not
432 parsable into
433 [service][google.cloud.tasks.v2.AppEngineRouting.service],
434 [version][google.cloud.tasks.v2.AppEngineRouting.version],
435 and
436 [instance][google.cloud.tasks.v2.AppEngineRouting.instance].
437 For example, some tasks which were created using the App
438 Engine SDK use a custom domain name; custom domains are not
439 parsed by Cloud Tasks. If
440 [host][google.cloud.tasks.v2.AppEngineRouting.host] is not
441 parsable, then
442 [service][google.cloud.tasks.v2.AppEngineRouting.service],
443 [version][google.cloud.tasks.v2.AppEngineRouting.version],
444 and
445 [instance][google.cloud.tasks.v2.AppEngineRouting.instance]
446 are the empty string.
447 version (str):
448 App version.
450 By default, the task is sent to the version which is the
451 default version when the task is attempted.
453 For some queues or tasks which were created using the App
454 Engine Task Queue API,
455 [host][google.cloud.tasks.v2.AppEngineRouting.host] is not
456 parsable into
457 [service][google.cloud.tasks.v2.AppEngineRouting.service],
458 [version][google.cloud.tasks.v2.AppEngineRouting.version],
459 and
460 [instance][google.cloud.tasks.v2.AppEngineRouting.instance].
461 For example, some tasks which were created using the App
462 Engine SDK use a custom domain name; custom domains are not
463 parsed by Cloud Tasks. If
464 [host][google.cloud.tasks.v2.AppEngineRouting.host] is not
465 parsable, then
466 [service][google.cloud.tasks.v2.AppEngineRouting.service],
467 [version][google.cloud.tasks.v2.AppEngineRouting.version],
468 and
469 [instance][google.cloud.tasks.v2.AppEngineRouting.instance]
470 are the empty string.
471 instance (str):
472 App instance.
474 By default, the task is sent to an instance which is
475 available when the task is attempted.
477 Requests can only be sent to a specific instance if `manual
478 scaling is used in App Engine
479 Standard <https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes>`__.
480 App Engine Flex does not support instances. For more
481 information, see `App Engine Standard request
482 routing <https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed>`__
483 and `App Engine Flex request
484 routing <https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed>`__.
485 host (str):
486 Output only. The host that the task is sent to.
488 The host is constructed from the domain name of the app
489 associated with the queue's project ID (for example
490 .appspot.com), and the
491 [service][google.cloud.tasks.v2.AppEngineRouting.service],
492 [version][google.cloud.tasks.v2.AppEngineRouting.version],
493 and
494 [instance][google.cloud.tasks.v2.AppEngineRouting.instance].
495 Tasks which were created using the App Engine SDK might have
496 a custom domain name.
498 For more information, see `How Requests are
499 Routed <https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed>`__.
500 """
502 service: str = proto.Field(
503 proto.STRING,
504 number=1,
505 )
506 version: str = proto.Field(
507 proto.STRING,
508 number=2,
509 )
510 instance: str = proto.Field(
511 proto.STRING,
512 number=3,
513 )
514 host: str = proto.Field(
515 proto.STRING,
516 number=4,
517 )
520class OAuthToken(proto.Message):
521 r"""Contains information needed for generating an `OAuth
522 token <https://developers.google.com/identity/protocols/OAuth2>`__.
523 This type of authorization should generally only be used when
524 calling Google APIs hosted on \*.googleapis.com.
526 Attributes:
527 service_account_email (str):
528 `Service account
529 email <https://cloud.google.com/iam/docs/service-accounts>`__
530 to be used for generating OAuth token. The service account
531 must be within the same project as the queue. The caller
532 must have iam.serviceAccounts.actAs permission for the
533 service account.
534 scope (str):
535 OAuth scope to be used for generating OAuth
536 access token. If not specified,
537 "https://www.googleapis.com/auth/cloud-platform"
538 will be used.
539 """
541 service_account_email: str = proto.Field(
542 proto.STRING,
543 number=1,
544 )
545 scope: str = proto.Field(
546 proto.STRING,
547 number=2,
548 )
551class OidcToken(proto.Message):
552 r"""Contains information needed for generating an `OpenID Connect
553 token <https://developers.google.com/identity/protocols/OpenIDConnect>`__.
554 This type of authorization can be used for many scenarios, including
555 calling Cloud Run, or endpoints where you intend to validate the
556 token yourself.
558 Attributes:
559 service_account_email (str):
560 `Service account
561 email <https://cloud.google.com/iam/docs/service-accounts>`__
562 to be used for generating OIDC token. The service account
563 must be within the same project as the queue. The caller
564 must have iam.serviceAccounts.actAs permission for the
565 service account.
566 audience (str):
567 Audience to be used when generating OIDC
568 token. If not specified, the URI specified in
569 target will be used.
570 """
572 service_account_email: str = proto.Field(
573 proto.STRING,
574 number=1,
575 )
576 audience: str = proto.Field(
577 proto.STRING,
578 number=2,
579 )
582__all__ = tuple(sorted(__protobuf__.manifest))