Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/cloud/tasks_v2/types/target.py: 100%
38 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-07 07:07 +0000
1# -*- coding: utf-8 -*-
2# Copyright 2022 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][Queue.app_engine_routing_override], this value is used for
254 all tasks in the queue, no matter what the setting is for the
255 [task-level
256 app_engine_routing][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 will fail with error code 405
293 (Method 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 documentation for the request handlers in the
296 language your app is written in e.g. `Python Request
297 Handler <https://cloud.google.com/appengine/docs/python/tools/webapp/requesthandlerclass>`__.
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][Queue.app_engine_routing_override], this value is
303 used for all tasks in the queue, no matter what the
304 setting is for the [task-level
305 app_engine_routing][AppEngineHttpRequest.app_engine_routing].
306 relative_uri (str):
307 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].
340 For 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))