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