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 [queue's
79 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. But
90 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 created
97 or idle and if large numbers of tasks suddenly become available to
98 dispatch (due to spikes in create task rates, the queue being
99 unpaused, or many tasks that are scheduled at the same time).
101 This message has `oneof`_ fields (mutually exclusive fields).
102 For each oneof, at most one member field can be set at the same time.
103 Setting any member of the oneof automatically clears all other
104 members.
106 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
108 Attributes:
109 url (str):
110 Required. The full url path that the request will be sent
111 to.
113 This string must begin with either "http://" or "https://".
114 Some examples are: ``http://acme.com`` and
115 ``https://acme.com/sales:8080``. Cloud Tasks will encode
116 some characters for safety and compatibility. The maximum
117 allowed URL length is 2083 characters after encoding.
119 The ``Location`` header response from a redirect response
120 [``300`` - ``399``] may be followed. The redirect is not
121 counted as a separate attempt.
122 http_method (google.cloud.tasks_v2.types.HttpMethod):
123 The HTTP method to use for the request. The
124 default is POST.
125 headers (MutableMapping[str, str]):
126 HTTP request headers.
128 This map contains the header field names and values. Headers
129 can be set when the [task is
130 created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask].
132 These headers represent a subset of the headers that will
133 accompany the task's HTTP request. Some HTTP request headers
134 will be ignored or replaced.
136 A partial list of headers that will be ignored or replaced
137 is:
139 - Host: This will be computed by Cloud Tasks and derived
140 from
141 [HttpRequest.url][google.cloud.tasks.v2.HttpRequest.url].
142 - Content-Length: This will be computed by Cloud Tasks.
143 - User-Agent: This will be set to ``"Google-Cloud-Tasks"``.
144 - ``X-Google-*``: Google use only.
145 - ``X-AppEngine-*``: Google use only.
147 ``Content-Type`` won't be set by Cloud Tasks. You can
148 explicitly set ``Content-Type`` to a media type when the
149 [task is
150 created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask].
151 For example, ``Content-Type`` can be set to
152 ``"application/octet-stream"`` or ``"application/json"``.
154 Headers which can have multiple values (according to
155 RFC2616) can be specified using comma-separated values.
157 The size of the headers must be less than 80KB.
158 body (bytes):
159 HTTP request body.
161 A request body is allowed only if the [HTTP
162 method][google.cloud.tasks.v2.HttpRequest.http_method] is
163 POST, PUT, or PATCH. It is an error to set body on a task
164 with an incompatible
165 [HttpMethod][google.cloud.tasks.v2.HttpMethod].
166 oauth_token (google.cloud.tasks_v2.types.OAuthToken):
167 If specified, an `OAuth
168 token <https://developers.google.com/identity/protocols/OAuth2>`__
169 will be generated and attached as an ``Authorization``
170 header in the HTTP request.
172 This type of authorization should generally only be used
173 when calling Google APIs hosted on \*.googleapis.com.
175 This field is a member of `oneof`_ ``authorization_header``.
176 oidc_token (google.cloud.tasks_v2.types.OidcToken):
177 If specified, an
178 `OIDC <https://developers.google.com/identity/protocols/OpenIDConnect>`__
179 token will be generated and attached as an ``Authorization``
180 header in the HTTP request.
182 This type of authorization can be used for many scenarios,
183 including calling Cloud Run, or endpoints where you intend
184 to validate the token yourself.
186 This field is a member of `oneof`_ ``authorization_header``.
187 """
189 url: str = proto.Field(
190 proto.STRING,
191 number=1,
192 )
193 http_method: "HttpMethod" = proto.Field(
194 proto.ENUM,
195 number=2,
196 enum="HttpMethod",
197 )
198 headers: MutableMapping[str, str] = proto.MapField(
199 proto.STRING,
200 proto.STRING,
201 number=3,
202 )
203 body: bytes = proto.Field(
204 proto.BYTES,
205 number=4,
206 )
207 oauth_token: "OAuthToken" = proto.Field(
208 proto.MESSAGE,
209 number=5,
210 oneof="authorization_header",
211 message="OAuthToken",
212 )
213 oidc_token: "OidcToken" = proto.Field(
214 proto.MESSAGE,
215 number=6,
216 oneof="authorization_header",
217 message="OidcToken",
218 )
221class AppEngineHttpRequest(proto.Message):
222 r"""App Engine HTTP request.
224 The message defines the HTTP request that is sent to an App Engine
225 app when the task is dispatched.
227 Using
228 [AppEngineHttpRequest][google.cloud.tasks.v2.AppEngineHttpRequest]
229 requires
230 ```appengine.applications.get`` <https://cloud.google.com/appengine/docs/admin-api/access-control>`__
231 Google IAM permission for the project and the following scope:
233 ``https://www.googleapis.com/auth/cloud-platform``
235 The task will be delivered to the App Engine app which belongs to
236 the same project as the queue. For more information, see `How
237 Requests are
238 Routed <https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed>`__
239 and how routing is affected by `dispatch
240 files <https://cloud.google.com/appengine/docs/python/config/dispatchref>`__.
241 Traffic is encrypted during transport and never leaves Google
242 datacenters. Because this traffic is carried over a communication
243 mechanism internal to Google, you cannot explicitly set the protocol
244 (for example, HTTP or HTTPS). The request to the handler, however,
245 will appear to have used the HTTP protocol.
247 The [AppEngineRouting][google.cloud.tasks.v2.AppEngineRouting] used
248 to construct the URL that the task is delivered to can be set at the
249 queue-level or task-level:
251 - If [app_engine_routing_override is set on the
252 queue][google.cloud.tasks.v2.Queue.app_engine_routing_override],
253 this value is used for all tasks in the queue, no matter what the
254 setting is for the [task-level
255 app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing].
257 The ``url`` that the task will be sent to is:
259 - ``url =`` [host][google.cloud.tasks.v2.AppEngineRouting.host]
260 ``+``
261 [relative_uri][google.cloud.tasks.v2.AppEngineHttpRequest.relative_uri]
263 Tasks can be dispatched to secure app handlers, unsecure app
264 handlers, and URIs restricted with
265 ```login: admin`` <https://cloud.google.com/appengine/docs/standard/python/config/appref>`__.
266 Because tasks are not run as any user, they cannot be dispatched to
267 URIs restricted with
268 ```login: required`` <https://cloud.google.com/appengine/docs/standard/python/config/appref>`__
269 Task dispatches also do not follow redirects.
271 The task attempt has succeeded if the app's request handler returns
272 an HTTP response code in the range [``200`` - ``299``]. The task
273 attempt has failed if the app's handler returns a non-2xx response
274 code or Cloud Tasks does not receive response before the
275 [deadline][google.cloud.tasks.v2.Task.dispatch_deadline]. Failed
276 tasks will be retried according to the [retry
277 configuration][google.cloud.tasks.v2.Queue.retry_config]. ``503``
278 (Service Unavailable) is considered an App Engine system error
279 instead of an application error and will cause Cloud Tasks' traffic
280 congestion control to temporarily throttle the queue's dispatches.
281 Unlike other types of task targets, a ``429`` (Too Many Requests)
282 response from an app handler does not cause traffic congestion
283 control to throttle the queue.
285 Attributes:
286 http_method (google.cloud.tasks_v2.types.HttpMethod):
287 The HTTP method to use for the request. The default is POST.
289 The app's request handler for the task's target URL must be
290 able to handle HTTP requests with this http_method,
291 otherwise the task attempt fails with error code 405 (Method
292 Not Allowed). See `Writing a push task request
293 handler <https://cloud.google.com/appengine/docs/java/taskqueue/push/creating-handlers#writing_a_push_task_request_handler>`__
294 and the App Engine documentation for your runtime on `How
295 Requests are
296 Handled <https://cloud.google.com/appengine/docs/standard/python3/how-requests-are-handled>`__.
297 app_engine_routing (google.cloud.tasks_v2.types.AppEngineRouting):
298 Task-level setting for App Engine routing.
300 - If [app_engine_routing_override is set on the
301 queue][google.cloud.tasks.v2.Queue.app_engine_routing_override],
302 this value is used for all tasks in the queue, no matter
303 what the setting is for the [task-level
304 app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing].
305 relative_uri (str):
306 The relative URI.
308 The relative URI must begin with "/" and must be
309 a valid HTTP relative URI. It can contain a path
310 and query string arguments. If the relative URI
311 is empty, then the root path "/" will be used.
312 No spaces are allowed, and the maximum length
313 allowed is 2083 characters.
314 headers (MutableMapping[str, str]):
315 HTTP request headers.
317 This map contains the header field names and values. Headers
318 can be set when the [task is
319 created][google.cloud.tasks.v2.CloudTasks.CreateTask].
320 Repeated headers are not supported but a header value can
321 contain commas.
323 Cloud Tasks sets some headers to default values:
325 - ``User-Agent``: By default, this header is
326 ``"AppEngine-Google; (+http://code.google.com/appengine)"``.
327 This header can be modified, but Cloud Tasks will append
328 ``"AppEngine-Google; (+http://code.google.com/appengine)"``
329 to the modified ``User-Agent``.
331 If the task has a
332 [body][google.cloud.tasks.v2.AppEngineHttpRequest.body],
333 Cloud Tasks sets the following headers:
335 - ``Content-Type``: By default, the ``Content-Type`` header
336 is set to ``"application/octet-stream"``. The default can
337 be overridden by explicitly setting ``Content-Type`` to a
338 particular media type when the [task is
339 created][google.cloud.tasks.v2.CloudTasks.CreateTask]. For
340 example, ``Content-Type`` can be set to
341 ``"application/json"``.
342 - ``Content-Length``: This is computed by Cloud Tasks. This
343 value is output only. It cannot be changed.
345 The headers below cannot be set or overridden:
347 - ``Host``
348 - ``X-Google-*``
349 - ``X-AppEngine-*``
351 In addition, Cloud Tasks sets some headers when the task is
352 dispatched, such as headers containing information about the
353 task; see `request
354 headers <https://cloud.google.com/tasks/docs/creating-appengine-handlers#reading_request_headers>`__.
355 These headers are set only when the task is dispatched, so
356 they are not visible when the task is returned in a Cloud
357 Tasks response.
359 Although there is no specific limit for the maximum number
360 of headers or the size, there is a limit on the maximum size
361 of the [Task][google.cloud.tasks.v2.Task]. For more
362 information, see the
363 [CreateTask][google.cloud.tasks.v2.CloudTasks.CreateTask]
364 documentation.
365 body (bytes):
366 HTTP request body.
368 A request body is allowed only if the HTTP method is POST or
369 PUT. It is an error to set a body on a task with an
370 incompatible [HttpMethod][google.cloud.tasks.v2.HttpMethod].
371 """
373 http_method: "HttpMethod" = proto.Field(
374 proto.ENUM,
375 number=1,
376 enum="HttpMethod",
377 )
378 app_engine_routing: "AppEngineRouting" = proto.Field(
379 proto.MESSAGE,
380 number=2,
381 message="AppEngineRouting",
382 )
383 relative_uri: str = proto.Field(
384 proto.STRING,
385 number=3,
386 )
387 headers: MutableMapping[str, str] = proto.MapField(
388 proto.STRING,
389 proto.STRING,
390 number=4,
391 )
392 body: bytes = proto.Field(
393 proto.BYTES,
394 number=5,
395 )
398class AppEngineRouting(proto.Message):
399 r"""App Engine Routing.
401 Defines routing characteristics specific to App Engine - service,
402 version, and instance.
404 For more information about services, versions, and instances see `An
405 Overview of App
406 Engine <https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine>`__,
407 `Microservices Architecture on Google App
408 Engine <https://cloud.google.com/appengine/docs/python/microservices-on-app-engine>`__,
409 `App Engine Standard request
410 routing <https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed>`__,
411 and `App Engine Flex request
412 routing <https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed>`__.
414 Using [AppEngineRouting][google.cloud.tasks.v2.AppEngineRouting]
415 requires
416 ```appengine.applications.get`` <https://cloud.google.com/appengine/docs/admin-api/access-control>`__
417 Google IAM permission for the project and the following scope:
419 ``https://www.googleapis.com/auth/cloud-platform``
421 Attributes:
422 service (str):
423 App service.
425 By default, the task is sent to the service which is the
426 default service when the task is attempted.
428 For some queues or tasks which were created using the App
429 Engine Task Queue API,
430 [host][google.cloud.tasks.v2.AppEngineRouting.host] is not
431 parsable into
432 [service][google.cloud.tasks.v2.AppEngineRouting.service],
433 [version][google.cloud.tasks.v2.AppEngineRouting.version],
434 and
435 [instance][google.cloud.tasks.v2.AppEngineRouting.instance].
436 For example, some tasks which were created using the App
437 Engine SDK use a custom domain name; custom domains are not
438 parsed by Cloud Tasks. If
439 [host][google.cloud.tasks.v2.AppEngineRouting.host] is not
440 parsable, then
441 [service][google.cloud.tasks.v2.AppEngineRouting.service],
442 [version][google.cloud.tasks.v2.AppEngineRouting.version],
443 and
444 [instance][google.cloud.tasks.v2.AppEngineRouting.instance]
445 are the empty string.
446 version (str):
447 App version.
449 By default, the task is sent to the version which is the
450 default version when the task is attempted.
452 For some queues or tasks which were created using the App
453 Engine Task Queue API,
454 [host][google.cloud.tasks.v2.AppEngineRouting.host] is not
455 parsable into
456 [service][google.cloud.tasks.v2.AppEngineRouting.service],
457 [version][google.cloud.tasks.v2.AppEngineRouting.version],
458 and
459 [instance][google.cloud.tasks.v2.AppEngineRouting.instance].
460 For example, some tasks which were created using the App
461 Engine SDK use a custom domain name; custom domains are not
462 parsed by Cloud Tasks. If
463 [host][google.cloud.tasks.v2.AppEngineRouting.host] is not
464 parsable, then
465 [service][google.cloud.tasks.v2.AppEngineRouting.service],
466 [version][google.cloud.tasks.v2.AppEngineRouting.version],
467 and
468 [instance][google.cloud.tasks.v2.AppEngineRouting.instance]
469 are the empty string.
470 instance (str):
471 App instance.
473 By default, the task is sent to an instance which is
474 available when the task is attempted.
476 Requests can only be sent to a specific instance if `manual
477 scaling is used in App Engine
478 Standard <https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes>`__.
479 App Engine Flex does not support instances. For more
480 information, see `App Engine Standard request
481 routing <https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed>`__
482 and `App Engine Flex request
483 routing <https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed>`__.
484 host (str):
485 Output only. The host that the task is sent to.
487 The host is constructed from the domain name of the app
488 associated with the queue's project ID (for example
489 .appspot.com), and the
490 [service][google.cloud.tasks.v2.AppEngineRouting.service],
491 [version][google.cloud.tasks.v2.AppEngineRouting.version],
492 and
493 [instance][google.cloud.tasks.v2.AppEngineRouting.instance].
494 Tasks which were created using the App Engine SDK might have
495 a custom domain name.
497 For more information, see `How Requests are
498 Routed <https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed>`__.
499 """
501 service: str = proto.Field(
502 proto.STRING,
503 number=1,
504 )
505 version: str = proto.Field(
506 proto.STRING,
507 number=2,
508 )
509 instance: str = proto.Field(
510 proto.STRING,
511 number=3,
512 )
513 host: str = proto.Field(
514 proto.STRING,
515 number=4,
516 )
519class OAuthToken(proto.Message):
520 r"""Contains information needed for generating an `OAuth
521 token <https://developers.google.com/identity/protocols/OAuth2>`__.
522 This type of authorization should generally only be used when
523 calling Google APIs hosted on \*.googleapis.com.
525 Attributes:
526 service_account_email (str):
527 `Service account
528 email <https://cloud.google.com/iam/docs/service-accounts>`__
529 to be used for generating OAuth token. The service account
530 must be within the same project as the queue. The caller
531 must have iam.serviceAccounts.actAs permission for the
532 service account.
533 scope (str):
534 OAuth scope to be used for generating OAuth
535 access token. If not specified,
536 "https://www.googleapis.com/auth/cloud-platform"
537 will be used.
538 """
540 service_account_email: str = proto.Field(
541 proto.STRING,
542 number=1,
543 )
544 scope: str = proto.Field(
545 proto.STRING,
546 number=2,
547 )
550class OidcToken(proto.Message):
551 r"""Contains information needed for generating an `OpenID Connect
552 token <https://developers.google.com/identity/protocols/OpenIDConnect>`__.
553 This type of authorization can be used for many scenarios, including
554 calling Cloud Run, or endpoints where you intend to validate the
555 token yourself.
557 Attributes:
558 service_account_email (str):
559 `Service account
560 email <https://cloud.google.com/iam/docs/service-accounts>`__
561 to be used for generating OIDC token. The service account
562 must be within the same project as the queue. The caller
563 must have iam.serviceAccounts.actAs permission for the
564 service account.
565 audience (str):
566 Audience to be used when generating OIDC
567 token. If not specified, the URI specified in
568 target will be used.
569 """
571 service_account_email: str = proto.Field(
572 proto.STRING,
573 number=1,
574 )
575 audience: str = proto.Field(
576 proto.STRING,
577 number=2,
578 )
581__all__ = tuple(sorted(__protobuf__.manifest))