1 // Copyright 2019 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.
18 package google.cloud.tasks.v2beta3;
20 import "google/api/annotations.proto";
22 option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta3;tasks";
23 option java_multiple_files = true;
24 option java_outer_classname = "TargetProto";
25 option java_package = "com.google.cloud.tasks.v2beta3";
29 // Warning: This is an [alpha](https://cloud.google.com/terms/launch-stages)
30 // feature. If you haven't already joined, you can [use this form to sign
31 // up](https://docs.google.com/forms/d/e/1FAIpQLSfc4uEy9CBHKYUSdnY1hdhKDCX7julVZHy3imOiR-XrU7bUNQ/viewform?usp=sf_link).
33 // The task will be pushed to the worker as an HTTP request. If the worker
34 // or the redirected worker acknowledges the task by returning a successful HTTP
35 // response code ([`200` - `299`]), the task will removed from the queue. If
36 // any other HTTP response code is returned or no response is received, the
37 // task will be retried according to the following:
39 // * User-specified throttling: [retry configuration][Queue.RetryConfig],
40 // [rate limits][Queue.RateLimits], and the [queue's
41 // state][google.cloud.tasks.v2beta3.Queue.state].
43 // * System throttling: To prevent the worker from overloading, Cloud Tasks may
44 // temporarily reduce the queue's effective rate. User-specified settings
45 // will not be changed.
47 // System throttling happens because:
49 // * Cloud Tasks backoffs on all errors. Normally the backoff specified in
50 // [rate limits][Queue.RateLimits] will be used. But if the worker returns
51 // `429` (Too Many Requests), `503` (Service Unavailable), or the rate of
52 // errors is high, Cloud Tasks will use a higher backoff rate. The retry
53 // specified in the `Retry-After` HTTP response header is considered.
55 // * To prevent traffic spikes and to smooth sudden large traffic spikes,
56 // dispatches ramp up slowly when the queue is newly created or idle and
57 // if large numbers of tasks suddenly become available to dispatch (due to
58 // spikes in create task rates, the queue being unpaused, or many tasks
59 // that are scheduled at the same time).
61 // Required. The full url path that the request will be sent to.
63 // This string must begin with either "http://" or "https://". Some examples
64 // are: `http://acme.com` and `https://acme.com/sales:8080`. Cloud Tasks will
65 // encode some characters for safety and compatibility. The maximum allowed
66 // URL length is 2083 characters after encoding.
68 // The `Location` header response from a redirect response [`300` - `399`]
69 // may be followed. The redirect is not counted as a separate attempt.
72 // The HTTP method to use for the request. The default is POST.
73 HttpMethod http_method = 2;
75 // HTTP request headers.
77 // This map contains the header field names and values.
78 // Headers can be set when the
79 // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask].
81 // These headers represent a subset of the headers that will accompany the
82 // task's HTTP request. Some HTTP request headers will be ignored or replaced.
84 // A partial list of headers that will be ignored or replaced is:
86 // * Host: This will be computed by Cloud Tasks and derived from
87 // [HttpRequest.url][google.cloud.tasks.v2beta3.HttpRequest.url].
88 // * Content-Length: This will be computed by Cloud Tasks.
89 // * User-Agent: This will be set to `"Google-Cloud-Tasks"`.
90 // * X-Google-*: Google use only.
91 // * X-AppEngine-*: Google use only.
93 // `Content-Type` won't be set by Cloud Tasks. You can explicitly set
94 // `Content-Type` to a media type when the
95 // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask].
96 // For example, `Content-Type` can be set to `"application/octet-stream"` or
97 // `"application/json"`.
99 // Headers which can have multiple values (according to RFC2616) can be
100 // specified using comma-separated values.
102 // The size of the headers must be less than 80KB.
103 map<string, string> headers = 3;
105 // HTTP request body.
107 // A request body is allowed only if the
108 // [HTTP method][google.cloud.tasks.v2beta3.HttpRequest.http_method] is POST,
109 // PUT, or PATCH. It is an error to set body on a task with an incompatible
110 // [HttpMethod][google.cloud.tasks.v2beta3.HttpMethod].
114 // App Engine HTTP queue.
116 // The task will be delivered to the App Engine application hostname
118 // [AppEngineHttpQueue][google.cloud.tasks.v2beta3.AppEngineHttpQueue] and
119 // [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest]. The
121 // [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest]
122 // explains how the task's host URL is constructed.
124 // Using [AppEngineHttpQueue][google.cloud.tasks.v2beta3.AppEngineHttpQueue]
126 // [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)
127 // Google IAM permission for the project
128 // and the following scope:
130 // `https://www.googleapis.com/auth/cloud-platform`
131 message AppEngineHttpQueue {
134 // app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing].
136 // If set, `app_engine_routing_override` is used for all tasks in
137 // the queue, no matter what the setting is for the
139 // app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing].
140 AppEngineRouting app_engine_routing_override = 1;
143 // App Engine HTTP request.
145 // The message defines the HTTP request that is sent to an App Engine app when
146 // the task is dispatched.
148 // This proto can only be used for tasks in a queue which has
149 // [app_engine_http_queue][google.cloud.tasks.v2beta3.Queue.app_engine_http_queue]
152 // Using [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest]
154 // [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)
155 // Google IAM permission for the project
156 // and the following scope:
158 // `https://www.googleapis.com/auth/cloud-platform`
160 // The task will be delivered to the App Engine app which belongs to the same
161 // project as the queue. For more information, see
163 // Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)
164 // and how routing is affected by
166 // files](https://cloud.google.com/appengine/docs/python/config/dispatchref).
167 // Traffic is encrypted during transport and never leaves Google datacenters.
168 // Because this traffic is carried over a communication mechanism internal to
169 // Google, you cannot explicitly set the protocol (for example, HTTP or HTTPS).
170 // The request to the handler, however, will appear to have used the HTTP
173 // The [AppEngineRouting][google.cloud.tasks.v2beta3.AppEngineRouting] used to
174 // construct the URL that the task is delivered to can be set at the queue-level
178 // [app_engine_routing_override][google.cloud.tasks.v2beta3.AppEngineHttpQueue.app_engine_routing_override]
179 // is used for all tasks in the queue, no matter what the setting
182 // app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing].
185 // The `url` that the task will be sent to is:
187 // * `url =` [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] `+`
188 // [relative_uri][google.cloud.tasks.v2beta3.AppEngineHttpRequest.relative_uri]
190 // Tasks can be dispatched to secure app handlers, unsecure app handlers, and
191 // URIs restricted with
193 // admin`](https://cloud.google.com/appengine/docs/standard/python/config/appref).
194 // Because tasks are not run as any user, they cannot be dispatched to URIs
197 // required`](https://cloud.google.com/appengine/docs/standard/python/config/appref)
198 // Task dispatches also do not follow redirects.
200 // The task attempt has succeeded if the app's request handler returns
201 // an HTTP response code in the range [`200` - `299`]. `503` is
202 // considered an App Engine system error instead of an application
203 // error. Requests returning error `503` will be retried regardless of
204 // retry configuration and not counted against retry counts.
205 // Any other response code or a failure to receive a response before the
206 // deadline is a failed attempt.
207 message AppEngineHttpRequest {
208 // The HTTP method to use for the request. The default is POST.
210 // The app's request handler for the task's target URL must be able to handle
211 // HTTP requests with this http_method, otherwise the task attempt will fail
212 // with error code 405 (Method Not Allowed). See
213 // [Writing a push task request
214 // handler](https://cloud.google.com/appengine/docs/java/taskqueue/push/creating-handlers#writing_a_push_task_request_handler)
215 // and the documentation for the request handlers in the language your app is
218 // Handler](https://cloud.google.com/appengine/docs/python/tools/webapp/requesthandlerclass).
219 HttpMethod http_method = 1;
221 // Task-level setting for App Engine routing.
224 // [app_engine_routing_override][google.cloud.tasks.v2beta3.AppEngineHttpQueue.app_engine_routing_override]
225 // is used for all tasks in the queue, no matter what the setting is for the
227 // app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing].
228 AppEngineRouting app_engine_routing = 2;
232 // The relative URI must begin with "/" and must be a valid HTTP relative URI.
233 // It can contain a path and query string arguments.
234 // If the relative URI is empty, then the root path "/" will be used.
235 // No spaces are allowed, and the maximum length allowed is 2083 characters.
236 string relative_uri = 3;
238 // HTTP request headers.
240 // This map contains the header field names and values.
241 // Headers can be set when the
242 // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask].
243 // Repeated headers are not supported but a header value can contain commas.
245 // Cloud Tasks sets some headers to default values:
247 // * `User-Agent`: By default, this header is
248 // `"AppEngine-Google; (+http://code.google.com/appengine)"`.
249 // This header can be modified, but Cloud Tasks will append
250 // `"AppEngine-Google; (+http://code.google.com/appengine)"` to the
251 // modified `User-Agent`.
254 // [body][google.cloud.tasks.v2beta3.AppEngineHttpRequest.body], Cloud Tasks
255 // sets the following headers:
257 // * `Content-Type`: By default, the `Content-Type` header is set to
258 // `"application/octet-stream"`. The default can be overridden by explicitly
259 // setting `Content-Type` to a particular media type when the
260 // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask].
261 // For example, `Content-Type` can be set to `"application/json"`.
262 // * `Content-Length`: This is computed by Cloud Tasks. This value is
263 // output only. It cannot be changed.
265 // The headers below cannot be set or overridden:
271 // In addition, Cloud Tasks sets some headers when the task is dispatched,
272 // such as headers containing information about the task; see
274 // headers](https://cloud.google.com/appengine/docs/python/taskqueue/push/creating-handlers#reading_request_headers).
275 // These headers are set only when the task is dispatched, so they are not
276 // visible when the task is returned in a Cloud Tasks response.
278 // Although there is no specific limit for the maximum number of headers or
279 // the size, there is a limit on the maximum size of the
280 // [Task][google.cloud.tasks.v2beta3.Task]. For more information, see the
281 // [CreateTask][google.cloud.tasks.v2beta3.CloudTasks.CreateTask]
283 map<string, string> headers = 4;
285 // HTTP request body.
287 // A request body is allowed only if the HTTP method is POST or PUT. It is
288 // an error to set a body on a task with an incompatible
289 // [HttpMethod][google.cloud.tasks.v2beta3.HttpMethod].
293 // App Engine Routing.
295 // Defines routing characteristics specific to App Engine - service, version,
298 // For more information about services, versions, and instances see
299 // [An Overview of App
300 // Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),
301 // [Microservices Architecture on Google App
302 // Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine),
303 // [App Engine Standard request
304 // routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed),
305 // and [App Engine Flex request
306 // routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).
307 message AppEngineRouting {
310 // By default, the task is sent to the service which is the default
311 // service when the task is attempted.
313 // For some queues or tasks which were created using the App Engine
314 // Task Queue API, [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is
316 // [service][google.cloud.tasks.v2beta3.AppEngineRouting.service],
317 // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and
318 // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance]. For
319 // example, some tasks which were created using the App Engine SDK use a
320 // custom domain name; custom domains are not parsed by Cloud Tasks. If
321 // [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is not parsable,
322 // then [service][google.cloud.tasks.v2beta3.AppEngineRouting.service],
323 // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and
324 // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance] are the
330 // By default, the task is sent to the version which is the default
331 // version when the task is attempted.
333 // For some queues or tasks which were created using the App Engine
334 // Task Queue API, [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is
336 // [service][google.cloud.tasks.v2beta3.AppEngineRouting.service],
337 // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and
338 // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance]. For
339 // example, some tasks which were created using the App Engine SDK use a
340 // custom domain name; custom domains are not parsed by Cloud Tasks. If
341 // [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is not parsable,
342 // then [service][google.cloud.tasks.v2beta3.AppEngineRouting.service],
343 // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and
344 // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance] are the
350 // By default, the task is sent to an instance which is available when
351 // the task is attempted.
353 // Requests can only be sent to a specific instance if
354 // [manual scaling is used in App Engine
355 // Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes).
356 // App Engine Flex does not support instances. For more information, see
357 // [App Engine Standard request
358 // routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)
359 // and [App Engine Flex request
360 // routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed).
363 // Output only. The host that the task is sent to.
365 // The host is constructed from the domain name of the app associated with
366 // the queue's project ID (for example <app-id>.appspot.com), and the
367 // [service][google.cloud.tasks.v2beta3.AppEngineRouting.service],
368 // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and
369 // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance]. Tasks
370 // which were created using the App Engine SDK might have a custom domain
373 // For more information, see
375 // Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed).
379 // The HTTP method used to execute the task.
381 // HTTP method unspecified
382 HTTP_METHOD_UNSPECIFIED = 0;