1// Copyright 2020 Google LLC 2// 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 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 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. 14 15syntax = "proto3"; 16 17package google.cloud.tasks.v2beta2; 18 19option go_package = "cloud.google.com/go/cloudtasks/apiv2beta2/cloudtaskspb;cloudtaskspb"; 20option java_multiple_files = true; 21option java_outer_classname = "TargetProto"; 22option java_package = "com.google.cloud.tasks.v2beta2"; 23 24// Pull target. 25message PullTarget {} 26 27// The pull message contains data that can be used by the caller of 28// [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] to process the 29// task. 30// 31// This proto can only be used for tasks in a queue which has 32// [pull_target][google.cloud.tasks.v2beta2.Queue.pull_target] set. 33message PullMessage { 34 // A data payload consumed by the worker to execute the task. 35 bytes payload = 1; 36 37 // The task's tag. 38 // 39 // Tags allow similar tasks to be processed in a batch. If you label 40 // tasks with a tag, your worker can 41 // [lease tasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] with the 42 // same tag using 43 // [filter][google.cloud.tasks.v2beta2.LeaseTasksRequest.filter]. For example, 44 // if you want to aggregate the events associated with a specific user once a 45 // day, you could tag tasks with the user ID. 46 // 47 // The task's tag can only be set when the 48 // [task is created][google.cloud.tasks.v2beta2.CloudTasks.CreateTask]. 49 // 50 // The tag must be less than 500 characters. 51 // 52 // SDK compatibility: Although the SDK allows tags to be either 53 // string or 54 // [bytes](https://cloud.google.com/appengine/docs/standard/java/javadoc/com/google/appengine/api/taskqueue/TaskOptions.html#tag-byte:A-), 55 // only UTF-8 encoded tags can be used in Cloud Tasks. If a tag isn't UTF-8 56 // encoded, the tag will be empty when the task is returned by Cloud Tasks. 57 string tag = 2; 58} 59 60// App Engine HTTP target. 61// 62// The task will be delivered to the App Engine application hostname 63// specified by its 64// [AppEngineHttpTarget][google.cloud.tasks.v2beta2.AppEngineHttpTarget] and 65// [AppEngineHttpRequest][google.cloud.tasks.v2beta2.AppEngineHttpRequest]. The 66// documentation for 67// [AppEngineHttpRequest][google.cloud.tasks.v2beta2.AppEngineHttpRequest] 68// explains how the task's host URL is constructed. 69// 70// Using [AppEngineHttpTarget][google.cloud.tasks.v2beta2.AppEngineHttpTarget] 71// requires 72// [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control) 73// Google IAM permission for the project 74// and the following scope: 75// 76// `https://www.googleapis.com/auth/cloud-platform` 77message AppEngineHttpTarget { 78 // Overrides for the 79 // [task-level 80 // app_engine_routing][google.cloud.tasks.v2beta2.AppEngineHttpRequest.app_engine_routing]. 81 // 82 // If set, `app_engine_routing_override` is used for all tasks in 83 // the queue, no matter what the setting is for the 84 // [task-level 85 // app_engine_routing][google.cloud.tasks.v2beta2.AppEngineHttpRequest.app_engine_routing]. 86 AppEngineRouting app_engine_routing_override = 1; 87} 88 89// App Engine HTTP request. 90// 91// The message defines the HTTP request that is sent to an App Engine app when 92// the task is dispatched. 93// 94// This proto can only be used for tasks in a queue which has 95// [app_engine_http_target][google.cloud.tasks.v2beta2.Queue.app_engine_http_target] 96// set. 97// 98// Using [AppEngineHttpRequest][google.cloud.tasks.v2beta2.AppEngineHttpRequest] 99// requires 100// [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control) 101// Google IAM permission for the project 102// and the following scope: 103// 104// `https://www.googleapis.com/auth/cloud-platform` 105// 106// The task will be delivered to the App Engine app which belongs to the same 107// project as the queue. For more information, see 108// [How Requests are 109// Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) 110// and how routing is affected by 111// [dispatch 112// files](https://cloud.google.com/appengine/docs/python/config/dispatchref). 113// Traffic is encrypted during transport and never leaves Google datacenters. 114// Because this traffic is carried over a communication mechanism internal to 115// Google, you cannot explicitly set the protocol (for example, HTTP or HTTPS). 116// The request to the handler, however, will appear to have used the HTTP 117// protocol. 118// 119// The [AppEngineRouting][google.cloud.tasks.v2beta2.AppEngineRouting] used to 120// construct the URL that the task is delivered to can be set at the queue-level 121// or task-level: 122// 123// * If set, 124// [app_engine_routing_override][google.cloud.tasks.v2beta2.AppEngineHttpTarget.app_engine_routing_override] 125// is used for all tasks in the queue, no matter what the setting 126// is for the 127// [task-level 128// app_engine_routing][google.cloud.tasks.v2beta2.AppEngineHttpRequest.app_engine_routing]. 129// 130// 131// The `url` that the task will be sent to is: 132// 133// * `url =` [host][google.cloud.tasks.v2beta2.AppEngineRouting.host] `+` 134// [relative_url][google.cloud.tasks.v2beta2.AppEngineHttpRequest.relative_url] 135// 136// Tasks can be dispatched to secure app handlers, unsecure app handlers, and 137// URIs restricted with 138// [`login: 139// admin`](https://cloud.google.com/appengine/docs/standard/python/config/appref). 140// Because tasks are not run as any user, they cannot be dispatched to URIs 141// restricted with 142// [`login: 143// required`](https://cloud.google.com/appengine/docs/standard/python/config/appref) 144// Task dispatches also do not follow redirects. 145// 146// The task attempt has succeeded if the app's request handler returns an HTTP 147// response code in the range [`200` - `299`]. The task attempt has failed if 148// the app's handler returns a non-2xx response code or Cloud Tasks does 149// not receive response before the [deadline][Task.dispatch_deadline]. Failed 150// tasks will be retried according to the 151// [retry configuration][google.cloud.tasks.v2beta2.Queue.retry_config]. `503` 152// (Service Unavailable) is considered an App Engine system error instead of an 153// application error and will cause Cloud Tasks' traffic congestion control to 154// temporarily throttle the queue's dispatches. Unlike other types of task 155// targets, a `429` (Too Many Requests) response from an app handler does not 156// cause traffic congestion control to throttle the queue. 157message AppEngineHttpRequest { 158 // The HTTP method to use for the request. The default is POST. 159 // 160 // The app's request handler for the task's target URL must be able to handle 161 // HTTP requests with this http_method, otherwise the task attempt fails with 162 // error code 405 (Method Not Allowed). See [Writing a push task request 163 // handler](https://cloud.google.com/appengine/docs/java/taskqueue/push/creating-handlers#writing_a_push_task_request_handler) 164 // and the App Engine documentation for your runtime on [How Requests are 165 // Handled](https://cloud.google.com/appengine/docs/standard/python3/how-requests-are-handled). 166 HttpMethod http_method = 1; 167 168 // Task-level setting for App Engine routing. 169 // 170 // If set, 171 // [app_engine_routing_override][google.cloud.tasks.v2beta2.AppEngineHttpTarget.app_engine_routing_override] 172 // is used for all tasks in the queue, no matter what the setting is for the 173 // [task-level 174 // app_engine_routing][google.cloud.tasks.v2beta2.AppEngineHttpRequest.app_engine_routing]. 175 AppEngineRouting app_engine_routing = 2; 176 177 // The relative URL. 178 // 179 // The relative URL must begin with "/" and must be a valid HTTP relative URL. 180 // It can contain a path and query string arguments. 181 // If the relative URL is empty, then the root path "/" will be used. 182 // No spaces are allowed, and the maximum length allowed is 2083 characters. 183 string relative_url = 3; 184 185 // HTTP request headers. 186 // 187 // This map contains the header field names and values. 188 // Headers can be set when the 189 // [task is created][google.cloud.tasks.v2beta2.CloudTasks.CreateTask]. 190 // Repeated headers are not supported but a header value can contain commas. 191 // 192 // Cloud Tasks sets some headers to default values: 193 // 194 // * `User-Agent`: By default, this header is 195 // `"AppEngine-Google; (+http://code.google.com/appengine)"`. 196 // This header can be modified, but Cloud Tasks will append 197 // `"AppEngine-Google; (+http://code.google.com/appengine)"` to the 198 // modified `User-Agent`. 199 // 200 // If the task has a 201 // [payload][google.cloud.tasks.v2beta2.AppEngineHttpRequest.payload], Cloud 202 // Tasks sets the following headers: 203 // 204 // * `Content-Type`: By default, the `Content-Type` header is set to 205 // `"application/octet-stream"`. The default can be overridden by explicitly 206 // setting `Content-Type` to a particular media type when the 207 // [task is created][google.cloud.tasks.v2beta2.CloudTasks.CreateTask]. 208 // For example, `Content-Type` can be set to `"application/json"`. 209 // * `Content-Length`: This is computed by Cloud Tasks. This value is 210 // output only. It cannot be changed. 211 // 212 // The headers below cannot be set or overridden: 213 // 214 // * `Host` 215 // * `X-Google-*` 216 // * `X-AppEngine-*` 217 // 218 // In addition, Cloud Tasks sets some headers when the task is dispatched, 219 // such as headers containing information about the task; see 220 // [request 221 // headers](https://cloud.google.com/appengine/docs/python/taskqueue/push/creating-handlers#reading_request_headers). 222 // These headers are set only when the task is dispatched, so they are not 223 // visible when the task is returned in a Cloud Tasks response. 224 // 225 // Although there is no specific limit for the maximum number of headers or 226 // the size, there is a limit on the maximum size of the 227 // [Task][google.cloud.tasks.v2beta2.Task]. For more information, see the 228 // [CreateTask][google.cloud.tasks.v2beta2.CloudTasks.CreateTask] 229 // documentation. 230 map<string, string> headers = 4; 231 232 // Payload. 233 // 234 // The payload will be sent as the HTTP message body. A message 235 // body, and thus a payload, is allowed only if the HTTP method is 236 // POST or PUT. It is an error to set a data payload on a task with 237 // an incompatible [HttpMethod][google.cloud.tasks.v2beta2.HttpMethod]. 238 bytes payload = 5; 239} 240 241// App Engine Routing. 242// 243// Defines routing characteristics specific to App Engine - service, version, 244// and instance. 245// 246// For more information about services, versions, and instances see 247// [An Overview of App 248// Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine), 249// [Microservices Architecture on Google App 250// Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine), 251// [App Engine Standard request 252// routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed), 253// and [App Engine Flex request 254// routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). 255message AppEngineRouting { 256 // App service. 257 // 258 // By default, the task is sent to the service which is the default 259 // service when the task is attempted. 260 // 261 // For some queues or tasks which were created using the App Engine 262 // Task Queue API, [host][google.cloud.tasks.v2beta2.AppEngineRouting.host] is 263 // not parsable into 264 // [service][google.cloud.tasks.v2beta2.AppEngineRouting.service], 265 // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version], and 266 // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance]. For 267 // example, some tasks which were created using the App Engine SDK use a 268 // custom domain name; custom domains are not parsed by Cloud Tasks. If 269 // [host][google.cloud.tasks.v2beta2.AppEngineRouting.host] is not parsable, 270 // then [service][google.cloud.tasks.v2beta2.AppEngineRouting.service], 271 // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version], and 272 // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] are the 273 // empty string. 274 string service = 1; 275 276 // App version. 277 // 278 // By default, the task is sent to the version which is the default 279 // version when the task is attempted. 280 // 281 // For some queues or tasks which were created using the App Engine 282 // Task Queue API, [host][google.cloud.tasks.v2beta2.AppEngineRouting.host] is 283 // not parsable into 284 // [service][google.cloud.tasks.v2beta2.AppEngineRouting.service], 285 // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version], and 286 // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance]. For 287 // example, some tasks which were created using the App Engine SDK use a 288 // custom domain name; custom domains are not parsed by Cloud Tasks. If 289 // [host][google.cloud.tasks.v2beta2.AppEngineRouting.host] is not parsable, 290 // then [service][google.cloud.tasks.v2beta2.AppEngineRouting.service], 291 // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version], and 292 // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] are the 293 // empty string. 294 string version = 2; 295 296 // App instance. 297 // 298 // By default, the task is sent to an instance which is available when 299 // the task is attempted. 300 // 301 // Requests can only be sent to a specific instance if 302 // [manual scaling is used in App Engine 303 // Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes). 304 // App Engine Flex does not support instances. For more information, see 305 // [App Engine Standard request 306 // routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) 307 // and [App Engine Flex request 308 // routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). 309 string instance = 3; 310 311 // Output only. The host that the task is sent to. 312 // 313 // For more information, see 314 // [How Requests are 315 // Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed). 316 // 317 // The host is constructed as: 318 // 319 // 320 // * `host = [application_domain_name]`</br> 321 // `| [service] + '.' + [application_domain_name]`</br> 322 // `| [version] + '.' + [application_domain_name]`</br> 323 // `| [version_dot_service]+ '.' + [application_domain_name]`</br> 324 // `| [instance] + '.' + [application_domain_name]`</br> 325 // `| [instance_dot_service] + '.' + [application_domain_name]`</br> 326 // `| [instance_dot_version] + '.' + [application_domain_name]`</br> 327 // `| [instance_dot_version_dot_service] + '.' + [application_domain_name]` 328 // 329 // * `application_domain_name` = The domain name of the app, for 330 // example <app-id>.appspot.com, which is associated with the 331 // queue's project ID. Some tasks which were created using the App Engine 332 // SDK use a custom domain name. 333 // 334 // * `service =` 335 // [service][google.cloud.tasks.v2beta2.AppEngineRouting.service] 336 // 337 // * `version =` 338 // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version] 339 // 340 // * `version_dot_service =` 341 // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version] `+ '.' +` 342 // [service][google.cloud.tasks.v2beta2.AppEngineRouting.service] 343 // 344 // * `instance =` 345 // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] 346 // 347 // * `instance_dot_service =` 348 // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] `+ '.' 349 // +` [service][google.cloud.tasks.v2beta2.AppEngineRouting.service] 350 // 351 // * `instance_dot_version =` 352 // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] `+ '.' 353 // +` [version][google.cloud.tasks.v2beta2.AppEngineRouting.version] 354 // 355 // * `instance_dot_version_dot_service =` 356 // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] `+ '.' 357 // +` [version][google.cloud.tasks.v2beta2.AppEngineRouting.version] `+ '.' 358 // +` [service][google.cloud.tasks.v2beta2.AppEngineRouting.service] 359 // 360 // If [service][google.cloud.tasks.v2beta2.AppEngineRouting.service] is empty, 361 // then the task will be sent to the service which is the default service when 362 // the task is attempted. 363 // 364 // If [version][google.cloud.tasks.v2beta2.AppEngineRouting.version] is empty, 365 // then the task will be sent to the version which is the default version when 366 // the task is attempted. 367 // 368 // If [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] is 369 // empty, then the task will be sent to an instance which is available when 370 // the task is attempted. 371 // 372 // If [service][google.cloud.tasks.v2beta2.AppEngineRouting.service], 373 // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version], or 374 // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] is 375 // invalid, then the task will be sent to the default version of the default 376 // service when the task is attempted. 377 string host = 4; 378} 379 380// The HTTP method used to execute the task. 381enum HttpMethod { 382 // HTTP method unspecified 383 HTTP_METHOD_UNSPECIFIED = 0; 384 385 // HTTP POST 386 POST = 1; 387 388 // HTTP GET 389 GET = 2; 390 391 // HTTP HEAD 392 HEAD = 3; 393 394 // HTTP PUT 395 PUT = 4; 396 397 // HTTP DELETE 398 DELETE = 5; 399} 400