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.v2beta3; 18 19option go_package = "cloud.google.com/go/cloudtasks/apiv2beta3/cloudtaskspb;cloudtaskspb"; 20option java_multiple_files = true; 21option java_outer_classname = "TargetProto"; 22option java_package = "com.google.cloud.tasks.v2beta3"; 23 24// Pull Message. 25// 26// This proto can only be used for tasks in a queue which has 27// [PULL][google.cloud.tasks.v2beta3.Queue.type] type. It currently exists for 28// backwards compatibility with the App Engine Task Queue SDK. This message type 29// maybe returned with methods 30// [list][google.cloud.tasks.v2beta3.CloudTask.ListTasks] and 31// [get][google.cloud.tasks.v2beta3.CloudTask.ListTasks], when the response view 32// is [FULL][google.cloud.tasks.v2beta3.Task.View.Full]. 33message PullMessage { 34 // A data payload consumed by the worker to execute the task. 35 bytes payload = 1; 36 37 // The tasks's tag. 38 // 39 // The tag is less than 500 characters. 40 // 41 // SDK compatibility: Although the SDK allows tags to be either 42 // string or 43 // [bytes](https://cloud.google.com/appengine/docs/standard/java/javadoc/com/google/appengine/api/taskqueue/TaskOptions.html#tag-byte:A-), 44 // only UTF-8 encoded tags can be used in Cloud Tasks. If a tag isn't UTF-8 45 // encoded, the tag will be empty when the task is returned by Cloud Tasks. 46 string tag = 2; 47} 48 49// HTTP request. 50// 51// The task will be pushed to the worker as an HTTP request. If the worker 52// or the redirected worker acknowledges the task by returning a successful HTTP 53// response code ([`200` - `299`]), the task will be removed from the queue. If 54// any other HTTP response code is returned or no response is received, the 55// task will be retried according to the following: 56// 57// * User-specified throttling: [retry 58// configuration][google.cloud.tasks.v2beta3.Queue.retry_config], 59// [rate limits][google.cloud.tasks.v2beta3.Queue.rate_limits], and the 60// [queue's state][google.cloud.tasks.v2beta3.Queue.state]. 61// 62// * System throttling: To prevent the worker from overloading, Cloud Tasks may 63// temporarily reduce the queue's effective rate. User-specified settings 64// will not be changed. 65// 66// System throttling happens because: 67// 68// * Cloud Tasks backs off on all errors. Normally the backoff specified in 69// [rate limits][google.cloud.tasks.v2beta3.Queue.rate_limits] will be used. 70// But if the worker returns `429` (Too Many Requests), `503` (Service 71// Unavailable), or the rate of errors is high, Cloud Tasks will use a 72// higher backoff rate. The retry specified in the `Retry-After` HTTP 73// response header is considered. 74// 75// * To prevent traffic spikes and to smooth sudden increases in traffic, 76// dispatches ramp up slowly when the queue is newly created or idle and 77// if large numbers of tasks suddenly become available to dispatch (due to 78// spikes in create task rates, the queue being unpaused, or many tasks 79// that are scheduled at the same time). 80message HttpRequest { 81 // Required. The full url path that the request will be sent to. 82 // 83 // This string must begin with either "http://" or "https://". Some examples 84 // are: `http://acme.com` and `https://acme.com/sales:8080`. Cloud Tasks will 85 // encode some characters for safety and compatibility. The maximum allowed 86 // URL length is 2083 characters after encoding. 87 // 88 // The `Location` header response from a redirect response [`300` - `399`] 89 // may be followed. The redirect is not counted as a separate attempt. 90 string url = 1; 91 92 // The HTTP method to use for the request. The default is POST. 93 HttpMethod http_method = 2; 94 95 // HTTP request headers. 96 // 97 // This map contains the header field names and values. 98 // Headers can be set when the 99 // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask]. 100 // 101 // These headers represent a subset of the headers that will accompany the 102 // task's HTTP request. Some HTTP request headers will be ignored or replaced. 103 // 104 // A partial list of headers that will be ignored or replaced is: 105 // 106 // * Host: This will be computed by Cloud Tasks and derived from 107 // [HttpRequest.url][google.cloud.tasks.v2beta3.HttpRequest.url]. 108 // * Content-Length: This will be computed by Cloud Tasks. 109 // * User-Agent: This will be set to `"Google-Cloud-Tasks"`. 110 // * `X-Google-*`: Google use only. 111 // * `X-AppEngine-*`: Google use only. 112 // 113 // `Content-Type` won't be set by Cloud Tasks. You can explicitly set 114 // `Content-Type` to a media type when the 115 // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask]. 116 // For example, `Content-Type` can be set to `"application/octet-stream"` or 117 // `"application/json"`. 118 // 119 // Headers which can have multiple values (according to RFC2616) can be 120 // specified using comma-separated values. 121 // 122 // The size of the headers must be less than 80KB. 123 map<string, string> headers = 3; 124 125 // HTTP request body. 126 // 127 // A request body is allowed only if the 128 // [HTTP method][google.cloud.tasks.v2beta3.HttpRequest.http_method] is POST, 129 // PUT, or PATCH. It is an error to set body on a task with an incompatible 130 // [HttpMethod][google.cloud.tasks.v2beta3.HttpMethod]. 131 bytes body = 4; 132 133 // The mode for generating an `Authorization` header for HTTP requests. 134 // 135 // If specified, all `Authorization` headers in the 136 // [HttpRequest.headers][google.cloud.tasks.v2beta3.HttpRequest.headers] field 137 // will be overridden. 138 oneof authorization_header { 139 // If specified, an 140 // [OAuth token](https://developers.google.com/identity/protocols/OAuth2) 141 // will be generated and attached as an `Authorization` header in the HTTP 142 // request. 143 // 144 // This type of authorization should generally only be used when calling 145 // Google APIs hosted on *.googleapis.com. 146 OAuthToken oauth_token = 5; 147 148 // If specified, an 149 // [OIDC](https://developers.google.com/identity/protocols/OpenIDConnect) 150 // token will be generated and attached as an `Authorization` header in the 151 // HTTP request. 152 // 153 // This type of authorization can be used for many scenarios, including 154 // calling Cloud Run, or endpoints where you intend to validate the token 155 // yourself. 156 OidcToken oidc_token = 6; 157 } 158} 159 160// App Engine HTTP queue. 161// 162// The task will be delivered to the App Engine application hostname 163// specified by its 164// [AppEngineHttpQueue][google.cloud.tasks.v2beta3.AppEngineHttpQueue] and 165// [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest]. The 166// documentation for 167// [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest] 168// explains how the task's host URL is constructed. 169// 170// Using [AppEngineHttpQueue][google.cloud.tasks.v2beta3.AppEngineHttpQueue] 171// requires 172// [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control) 173// Google IAM permission for the project 174// and the following scope: 175// 176// `https://www.googleapis.com/auth/cloud-platform` 177message AppEngineHttpQueue { 178 // Overrides for the 179 // [task-level 180 // app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing]. 181 // 182 // If set, `app_engine_routing_override` is used for all tasks in 183 // the queue, no matter what the setting is for the 184 // [task-level 185 // app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing]. 186 AppEngineRouting app_engine_routing_override = 1; 187} 188 189// App Engine HTTP request. 190// 191// The message defines the HTTP request that is sent to an App Engine app when 192// the task is dispatched. 193// 194// Using [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest] 195// requires 196// [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control) 197// Google IAM permission for the project 198// and the following scope: 199// 200// `https://www.googleapis.com/auth/cloud-platform` 201// 202// The task will be delivered to the App Engine app which belongs to the same 203// project as the queue. For more information, see 204// [How Requests are 205// Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) 206// and how routing is affected by 207// [dispatch 208// files](https://cloud.google.com/appengine/docs/python/config/dispatchref). 209// Traffic is encrypted during transport and never leaves Google datacenters. 210// Because this traffic is carried over a communication mechanism internal to 211// Google, you cannot explicitly set the protocol (for example, HTTP or HTTPS). 212// The request to the handler, however, will appear to have used the HTTP 213// protocol. 214// 215// The [AppEngineRouting][google.cloud.tasks.v2beta3.AppEngineRouting] used to 216// construct the URL that the task is delivered to can be set at the queue-level 217// or task-level: 218// 219// * If set, 220// [app_engine_routing_override][google.cloud.tasks.v2beta3.AppEngineHttpQueue.app_engine_routing_override] 221// is used for all tasks in the queue, no matter what the setting 222// is for the 223// [task-level 224// app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing]. 225// 226// 227// The `url` that the task will be sent to is: 228// 229// * `url =` [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] `+` 230// [relative_uri][google.cloud.tasks.v2beta3.AppEngineHttpRequest.relative_uri] 231// 232// Tasks can be dispatched to secure app handlers, unsecure app handlers, and 233// URIs restricted with 234// [`login: 235// admin`](https://cloud.google.com/appengine/docs/standard/python/config/appref). 236// Because tasks are not run as any user, they cannot be dispatched to URIs 237// restricted with 238// [`login: 239// required`](https://cloud.google.com/appengine/docs/standard/python/config/appref) 240// Task dispatches also do not follow redirects. 241// 242// The task attempt has succeeded if the app's request handler returns an HTTP 243// response code in the range [`200` - `299`]. The task attempt has failed if 244// the app's handler returns a non-2xx response code or Cloud Tasks does 245// not receive response before the 246// [deadline][google.cloud.tasks.v2beta3.Task.dispatch_deadline]. Failed tasks 247// will be retried according to the [retry 248// configuration][google.cloud.tasks.v2beta3.Queue.retry_config]. `503` (Service 249// Unavailable) is considered an App Engine system error instead of an 250// application error and will cause Cloud Tasks' traffic congestion control to 251// temporarily throttle the queue's dispatches. Unlike other types of task 252// targets, a `429` (Too Many Requests) response from an app handler does not 253// cause traffic congestion control to throttle the queue. 254message AppEngineHttpRequest { 255 // The HTTP method to use for the request. The default is POST. 256 // 257 // The app's request handler for the task's target URL must be able to handle 258 // HTTP requests with this http_method, otherwise the task attempt fails with 259 // error code 405 (Method Not Allowed). See [Writing a push task request 260 // handler](https://cloud.google.com/appengine/docs/java/taskqueue/push/creating-handlers#writing_a_push_task_request_handler) 261 // and the App Engine documentation for your runtime on [How Requests are 262 // Handled](https://cloud.google.com/appengine/docs/standard/python3/how-requests-are-handled). 263 HttpMethod http_method = 1; 264 265 // Task-level setting for App Engine routing. 266 // 267 // If set, 268 // [app_engine_routing_override][google.cloud.tasks.v2beta3.AppEngineHttpQueue.app_engine_routing_override] 269 // is used for all tasks in the queue, no matter what the setting is for the 270 // [task-level 271 // app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing]. 272 AppEngineRouting app_engine_routing = 2; 273 274 // The relative URI. 275 // 276 // The relative URI must begin with "/" and must be a valid HTTP relative URI. 277 // It can contain a path and query string arguments. 278 // If the relative URI is empty, then the root path "/" will be used. 279 // No spaces are allowed, and the maximum length allowed is 2083 characters. 280 string relative_uri = 3; 281 282 // HTTP request headers. 283 // 284 // This map contains the header field names and values. 285 // Headers can be set when the 286 // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask]. 287 // Repeated headers are not supported but a header value can contain commas. 288 // 289 // Cloud Tasks sets some headers to default values: 290 // 291 // * `User-Agent`: By default, this header is 292 // `"AppEngine-Google; (+http://code.google.com/appengine)"`. 293 // This header can be modified, but Cloud Tasks will append 294 // `"AppEngine-Google; (+http://code.google.com/appengine)"` to the 295 // modified `User-Agent`. 296 // 297 // If the task has a 298 // [body][google.cloud.tasks.v2beta3.AppEngineHttpRequest.body], Cloud Tasks 299 // sets the following headers: 300 // 301 // * `Content-Type`: By default, the `Content-Type` header is set to 302 // `"application/octet-stream"`. The default can be overridden by explicitly 303 // setting `Content-Type` to a particular media type when the 304 // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask]. 305 // For example, `Content-Type` can be set to `"application/json"`. 306 // * `Content-Length`: This is computed by Cloud Tasks. This value is 307 // output only. It cannot be changed. 308 // 309 // The headers below cannot be set or overridden: 310 // 311 // * `Host` 312 // * `X-Google-*` 313 // * `X-AppEngine-*` 314 // 315 // In addition, Cloud Tasks sets some headers when the task is dispatched, 316 // such as headers containing information about the task; see 317 // [request 318 // headers](https://cloud.google.com/tasks/docs/creating-appengine-handlers#reading_request_headers). 319 // These headers are set only when the task is dispatched, so they are not 320 // visible when the task is returned in a Cloud Tasks response. 321 // 322 // Although there is no specific limit for the maximum number of headers or 323 // the size, there is a limit on the maximum size of the 324 // [Task][google.cloud.tasks.v2beta3.Task]. For more information, see the 325 // [CreateTask][google.cloud.tasks.v2beta3.CloudTasks.CreateTask] 326 // documentation. 327 map<string, string> headers = 4; 328 329 // HTTP request body. 330 // 331 // A request body is allowed only if the HTTP method is POST or PUT. It is 332 // an error to set a body on a task with an incompatible 333 // [HttpMethod][google.cloud.tasks.v2beta3.HttpMethod]. 334 bytes body = 5; 335} 336 337// App Engine Routing. 338// 339// Defines routing characteristics specific to App Engine - service, version, 340// and instance. 341// 342// For more information about services, versions, and instances see 343// [An Overview of App 344// Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine), 345// [Microservices Architecture on Google App 346// Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine), 347// [App Engine Standard request 348// routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed), 349// and [App Engine Flex request 350// routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). 351message AppEngineRouting { 352 // App service. 353 // 354 // By default, the task is sent to the service which is the default 355 // service when the task is attempted. 356 // 357 // For some queues or tasks which were created using the App Engine 358 // Task Queue API, [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is 359 // not parsable into 360 // [service][google.cloud.tasks.v2beta3.AppEngineRouting.service], 361 // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and 362 // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance]. For 363 // example, some tasks which were created using the App Engine SDK use a 364 // custom domain name; custom domains are not parsed by Cloud Tasks. If 365 // [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is not parsable, 366 // then [service][google.cloud.tasks.v2beta3.AppEngineRouting.service], 367 // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and 368 // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance] are the 369 // empty string. 370 string service = 1; 371 372 // App version. 373 // 374 // By default, the task is sent to the version which is the default 375 // version when the task is attempted. 376 // 377 // For some queues or tasks which were created using the App Engine 378 // Task Queue API, [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is 379 // not parsable into 380 // [service][google.cloud.tasks.v2beta3.AppEngineRouting.service], 381 // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and 382 // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance]. For 383 // example, some tasks which were created using the App Engine SDK use a 384 // custom domain name; custom domains are not parsed by Cloud Tasks. If 385 // [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is not parsable, 386 // then [service][google.cloud.tasks.v2beta3.AppEngineRouting.service], 387 // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and 388 // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance] are the 389 // empty string. 390 string version = 2; 391 392 // App instance. 393 // 394 // By default, the task is sent to an instance which is available when 395 // the task is attempted. 396 // 397 // Requests can only be sent to a specific instance if 398 // [manual scaling is used in App Engine 399 // Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes). 400 // App Engine Flex does not support instances. For more information, see 401 // [App Engine Standard request 402 // routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) 403 // and [App Engine Flex request 404 // routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). 405 string instance = 3; 406 407 // Output only. The host that the task is sent to. 408 // 409 // The host is constructed from the domain name of the app associated with 410 // the queue's project ID (for example <app-id>.appspot.com), and the 411 // [service][google.cloud.tasks.v2beta3.AppEngineRouting.service], 412 // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and 413 // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance]. Tasks 414 // which were created using the App Engine SDK might have a custom domain 415 // name. 416 // 417 // For more information, see 418 // [How Requests are 419 // Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed). 420 string host = 4; 421} 422 423// The HTTP method used to execute the task. 424enum HttpMethod { 425 // HTTP method unspecified 426 HTTP_METHOD_UNSPECIFIED = 0; 427 428 // HTTP POST 429 POST = 1; 430 431 // HTTP GET 432 GET = 2; 433 434 // HTTP HEAD 435 HEAD = 3; 436 437 // HTTP PUT 438 PUT = 4; 439 440 // HTTP DELETE 441 DELETE = 5; 442 443 // HTTP PATCH 444 PATCH = 6; 445 446 // HTTP OPTIONS 447 OPTIONS = 7; 448} 449 450// Contains information needed for generating an 451// [OAuth token](https://developers.google.com/identity/protocols/OAuth2). 452// This type of authorization should generally only be used when calling Google 453// APIs hosted on *.googleapis.com. 454message OAuthToken { 455 // [Service account email](https://cloud.google.com/iam/docs/service-accounts) 456 // to be used for generating OAuth token. 457 // The service account must be within the same project as the queue. The 458 // caller must have iam.serviceAccounts.actAs permission for the service 459 // account. 460 string service_account_email = 1; 461 462 // OAuth scope to be used for generating OAuth access token. 463 // If not specified, "https://www.googleapis.com/auth/cloud-platform" 464 // will be used. 465 string scope = 2; 466} 467 468// Contains information needed for generating an 469// [OpenID Connect 470// token](https://developers.google.com/identity/protocols/OpenIDConnect). 471// This type of authorization can be used for many scenarios, including 472// calling Cloud Run, or endpoints where you intend to validate the token 473// yourself. 474message OidcToken { 475 // [Service account email](https://cloud.google.com/iam/docs/service-accounts) 476 // to be used for generating OIDC token. 477 // The service account must be within the same project as the queue. The 478 // caller must have iam.serviceAccounts.actAs permission for the service 479 // account. 480 string service_account_email = 1; 481 482 // Audience to be used when generating OIDC token. If not specified, the URI 483 // specified in target will be used. 484 string audience = 2; 485} 486