diff --git a/google/cloud/tasks/artman_cloudtasks_v2.yaml b/google/cloud/tasks/artman_cloudtasks_v2.yaml new file mode 100644 index 0000000000..f3af7e6d4e --- /dev/null +++ b/google/cloud/tasks/artman_cloudtasks_v2.yaml @@ -0,0 +1,36 @@ +common: + api_name: tasks + api_version: v2 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + - name: google-iam-v1 + proto_path: google/iam/v1 + src_proto_paths: + - v2 + service_yaml: cloudtasks_v2.yaml + gapic_yaml: v2/cloudtasks_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/tasks/cloudtasks_v2.yaml b/google/cloud/tasks/cloudtasks_v2.yaml new file mode 100644 index 0000000000..ba53c17f77 --- /dev/null +++ b/google/cloud/tasks/cloudtasks_v2.yaml @@ -0,0 +1,56 @@ +type: google.api.Service +config_version: 3 +name: cloudtasks.googleapis.com +title: Cloud Tasks API + +apis: + - name: google.cloud.tasks.v2.CloudTasks + +documentation: + summary: Manages the execution of large numbers of distributed requests. + overview: |- + Cloud Tasks manages the execution of large numbers of distributed requests. + + For more information, see https://cloud.google.com/tasks/. + +backend: + rules: + - selector: google.cloud.tasks.v2.CloudTasks.ListQueues + deadline: 15.0 + - selector: google.cloud.tasks.v2.CloudTasks.GetQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.CreateQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.UpdateQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.DeleteQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.PurgeQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.PauseQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.ResumeQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.GetIamPolicy + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.SetIamPolicy + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.TestIamPermissions + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.ListTasks + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.GetTask + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.CreateTask + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.DeleteTask + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.RunTask + deadline: 10.0 + +authentication: + rules: + - selector: 'google.cloud.tasks.v2.CloudTasks.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/tasks/v2/cloudtasks.proto b/google/cloud/tasks/v2/cloudtasks.proto new file mode 100644 index 0000000000..dfad1f91e0 --- /dev/null +++ b/google/cloud/tasks/v2/cloudtasks.proto @@ -0,0 +1,601 @@ +// Copyright 2019 Google LLC. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +syntax = "proto3"; + +package google.cloud.tasks.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/cloud/tasks/v2/task.proto"; +import "google/cloud/tasks/v2/queue.proto"; +import "google/iam/v1/iam_policy.proto"; +import "google/iam/v1/policy.proto"; +import "google/rpc/code.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "CloudTasksProto"; +option java_package = "com.google.cloud.tasks.v2"; +option objc_class_prefix = "TASKS"; + + +// Cloud Tasks allows developers to manage the execution of background +// work in their applications. +service CloudTasks { + // Lists queues. + // + // Queues are returned in lexicographical order. + rpc ListQueues(ListQueuesRequest) returns (ListQueuesResponse) { + option (google.api.http) = { + get: "/v2/{parent=projects/*/locations/*}/queues" + }; + } + + // Gets a queue. + rpc GetQueue(GetQueueRequest) returns (Queue) { + option (google.api.http) = { + get: "/v2/{name=projects/*/locations/*/queues/*}" + }; + } + + // Creates a queue. + // + // Queues created with this method allow tasks to live for a maximum of 31 + // days. After a task is 31 days old, the task will be deleted regardless of whether + // it was dispatched or not. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) + // before using this method. + rpc CreateQueue(CreateQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/locations/*}/queues" + body: "queue" + }; + } + + // Updates a queue. + // + // This method creates the queue if it does not exist and updates + // the queue if it does exist. + // + // Queues created with this method allow tasks to live for a maximum of 31 + // days. After a task is 31 days old, the task will be deleted regardless of whether + // it was dispatched or not. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) + // before using this method. + rpc UpdateQueue(UpdateQueueRequest) returns (Queue) { + option (google.api.http) = { + patch: "/v2/{queue.name=projects/*/locations/*/queues/*}" + body: "queue" + }; + } + + // Deletes a queue. + // + // This command will delete the queue even if it has tasks in it. + // + // Note: If you delete a queue, a queue with the same name can't be created + // for 7 days. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) + // before using this method. + rpc DeleteQueue(DeleteQueueRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2/{name=projects/*/locations/*/queues/*}" + }; + } + + // Purges a queue by deleting all of its tasks. + // + // All tasks created before this method is called are permanently deleted. + // + // Purge operations can take up to one minute to take effect. Tasks + // might be dispatched before the purge takes effect. A purge is irreversible. + rpc PurgeQueue(PurgeQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2/{name=projects/*/locations/*/queues/*}:purge" + body: "*" + }; + } + + // Pauses the queue. + // + // If a queue is paused then the system will stop dispatching tasks + // until the queue is resumed via + // [ResumeQueue][google.cloud.tasks.v2.CloudTasks.ResumeQueue]. Tasks can still be added + // when the queue is paused. A queue is paused if its + // [state][google.cloud.tasks.v2.Queue.state] is [PAUSED][google.cloud.tasks.v2.Queue.State.PAUSED]. + rpc PauseQueue(PauseQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2/{name=projects/*/locations/*/queues/*}:pause" + body: "*" + }; + } + + // Resume a queue. + // + // This method resumes a queue after it has been + // [PAUSED][google.cloud.tasks.v2.Queue.State.PAUSED] or + // [DISABLED][google.cloud.tasks.v2.Queue.State.DISABLED]. The state of a queue is stored + // in the queue's [state][google.cloud.tasks.v2.Queue.state]; after calling this method it + // will be set to [RUNNING][google.cloud.tasks.v2.Queue.State.RUNNING]. + // + // WARNING: Resuming many high-QPS queues at the same time can + // lead to target overloading. If you are resuming high-QPS + // queues, follow the 500/50/5 pattern described in + // [Managing Cloud Tasks Scaling Risks](https://cloud.google.com/tasks/docs/manage-cloud-task-scaling). + rpc ResumeQueue(ResumeQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2/{name=projects/*/locations/*/queues/*}:resume" + body: "*" + }; + } + + // Gets the access control policy for a [Queue][google.cloud.tasks.v2.Queue]. + // Returns an empty policy if the resource exists and does not have a policy + // set. + // + // Authorization requires the following + // [Google IAM](https://cloud.google.com/iam) permission on the specified + // resource parent: + // + // * `cloudtasks.queues.getIamPolicy` + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v2/{resource=projects/*/locations/*/queues/*}:getIamPolicy" + body: "*" + }; + } + + // Sets the access control policy for a [Queue][google.cloud.tasks.v2.Queue]. Replaces any existing + // policy. + // + // Note: The Cloud Console does not check queue-level IAM permissions yet. + // Project-level permissions are required to use the Cloud Console. + // + // Authorization requires the following + // [Google IAM](https://cloud.google.com/iam) permission on the specified + // resource parent: + // + // * `cloudtasks.queues.setIamPolicy` + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v2/{resource=projects/*/locations/*/queues/*}:setIamPolicy" + body: "*" + }; + } + + // Returns permissions that a caller has on a [Queue][google.cloud.tasks.v2.Queue]. + // If the resource does not exist, this will return an empty set of + // permissions, not a [NOT_FOUND][google.rpc.Code.NOT_FOUND] error. + // + // Note: This operation is designed to be used for building permission-aware + // UIs and command-line tools, not for authorization checking. This operation + // may "fail open" without warning. + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) { + option (google.api.http) = { + post: "/v2/{resource=projects/*/locations/*/queues/*}:testIamPermissions" + body: "*" + }; + } + + // Lists the tasks in a queue. + // + // By default, only the [BASIC][google.cloud.tasks.v2.Task.View.BASIC] view is retrieved + // due to performance considerations; + // [response_view][google.cloud.tasks.v2.ListTasksRequest.response_view] controls the + // subset of information which is returned. + // + // The tasks may be returned in any order. The ordering may change at any + // time. + rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) { + option (google.api.http) = { + get: "/v2/{parent=projects/*/locations/*/queues/*}/tasks" + }; + } + + // Gets a task. + rpc GetTask(GetTaskRequest) returns (Task) { + option (google.api.http) = { + get: "/v2/{name=projects/*/locations/*/queues/*/tasks/*}" + }; + } + + // Creates a task and adds it to a queue. + // + // Tasks cannot be updated after creation; there is no UpdateTask command. + // + // * For [App Engine queues][google.cloud.tasks.v2.AppEngineHttpQueue], the maximum task size is + // 100KB. + rpc CreateTask(CreateTaskRequest) returns (Task) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/locations/*/queues/*}/tasks" + body: "*" + }; + } + + // Deletes a task. + // + // A task can be deleted if it is scheduled or dispatched. A task + // cannot be deleted if it has executed successfully or permanently + // failed. + rpc DeleteTask(DeleteTaskRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2/{name=projects/*/locations/*/queues/*/tasks/*}" + }; + } + + // Forces a task to run now. + // + // When this method is called, Cloud Tasks will dispatch the task, even if + // the task is already running, the queue has reached its [RateLimits][google.cloud.tasks.v2.RateLimits] or + // is [PAUSED][google.cloud.tasks.v2.Queue.State.PAUSED]. + // + // This command is meant to be used for manual debugging. For + // example, [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask] can be used to retry a failed + // task after a fix has been made or to manually force a task to be + // dispatched now. + // + // The dispatched task is returned. That is, the task that is returned + // contains the [status][Task.status] after the task is dispatched but + // before the task is received by its target. + // + // If Cloud Tasks receives a successful response from the task's + // target, then the task will be deleted; otherwise the task's + // [schedule_time][google.cloud.tasks.v2.Task.schedule_time] will be reset to the time that + // [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask] was called plus the retry delay specified + // in the queue's [RetryConfig][google.cloud.tasks.v2.RetryConfig]. + // + // [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask] returns + // [NOT_FOUND][google.rpc.Code.NOT_FOUND] when it is called on a + // task that has already succeeded or permanently failed. + rpc RunTask(RunTaskRequest) returns (Task) { + option (google.api.http) = { + post: "/v2/{name=projects/*/locations/*/queues/*/tasks/*}:run" + body: "*" + }; + } +} + +// Request message for [ListQueues][google.cloud.tasks.v2.CloudTasks.ListQueues]. +message ListQueuesRequest { + // Required. + // + // The location name. + // For example: `projects/PROJECT_ID/locations/LOCATION_ID` + string parent = 1; + + // `filter` can be used to specify a subset of queues. Any [Queue][google.cloud.tasks.v2.Queue] + // field can be used as a filter and several operators as supported. + // For example: `<=, <, >=, >, !=, =, :`. The filter syntax is the same as + // described in + // [Stackdriver's Advanced Logs Filters](https://cloud.google.com/logging/docs/view/advanced_filters). + // + // Sample filter "state: PAUSED". + // + // Note that using filters might cause fewer queues than the + // requested page_size to be returned. + string filter = 2; + + // Requested page size. + // + // The maximum page size is 9800. If unspecified, the page size will + // be the maximum. Fewer queues than requested might be returned, + // even if more queues exist; use the + // [next_page_token][google.cloud.tasks.v2.ListQueuesResponse.next_page_token] in the + // response to determine if more queues exist. + int32 page_size = 3; + + // A token identifying the page of results to return. + // + // To request the first page results, page_token must be empty. To + // request the next page of results, page_token must be the value of + // [next_page_token][google.cloud.tasks.v2.ListQueuesResponse.next_page_token] returned + // from the previous call to [ListQueues][google.cloud.tasks.v2.CloudTasks.ListQueues] + // method. It is an error to switch the value of the + // [filter][google.cloud.tasks.v2.ListQueuesRequest.filter] while iterating through pages. + string page_token = 4; +} + +// Response message for [ListQueues][google.cloud.tasks.v2.CloudTasks.ListQueues]. +message ListQueuesResponse { + // The list of queues. + repeated Queue queues = 1; + + // A token to retrieve next page of results. + // + // To return the next page of results, call + // [ListQueues][google.cloud.tasks.v2.CloudTasks.ListQueues] with this value as the + // [page_token][google.cloud.tasks.v2.ListQueuesRequest.page_token]. + // + // If the next_page_token is empty, there are no more results. + // + // The page token is valid for only 2 hours. + string next_page_token = 2; +} + +// Request message for [GetQueue][google.cloud.tasks.v2.CloudTasks.GetQueue]. +message GetQueueRequest { + // Required. + // + // The resource name of the queue. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [CreateQueue][google.cloud.tasks.v2.CloudTasks.CreateQueue]. +message CreateQueueRequest { + // Required. + // + // The location name in which the queue will be created. + // For example: `projects/PROJECT_ID/locations/LOCATION_ID` + // + // The list of allowed locations can be obtained by calling Cloud + // Tasks' implementation of + // [ListLocations][google.cloud.location.Locations.ListLocations]. + string parent = 1; + + // Required. + // + // The queue to create. + // + // [Queue's name][google.cloud.tasks.v2.Queue.name] cannot be the same as an existing queue. + Queue queue = 2; +} + +// Request message for [UpdateQueue][google.cloud.tasks.v2.CloudTasks.UpdateQueue]. +message UpdateQueueRequest { + // Required. + // + // The queue to create or update. + // + // The queue's [name][google.cloud.tasks.v2.Queue.name] must be specified. + // + // Output only fields cannot be modified using UpdateQueue. + // Any value specified for an output only field will be ignored. + // The queue's [name][google.cloud.tasks.v2.Queue.name] cannot be changed. + Queue queue = 1; + + // A mask used to specify which fields of the queue are being updated. + // + // If empty, then all fields will be updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for [DeleteQueue][google.cloud.tasks.v2.CloudTasks.DeleteQueue]. +message DeleteQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [PurgeQueue][google.cloud.tasks.v2.CloudTasks.PurgeQueue]. +message PurgeQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [PauseQueue][google.cloud.tasks.v2.CloudTasks.PauseQueue]. +message PauseQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [ResumeQueue][google.cloud.tasks.v2.CloudTasks.ResumeQueue]. +message ResumeQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for listing tasks using [ListTasks][google.cloud.tasks.v2.CloudTasks.ListTasks]. +message ListTasksRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string parent = 1; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2.Task] resource. + Task.View response_view = 2; + + // Requested page size. Fewer tasks than requested might be returned. + // + // The maximum page size is 1000. If unspecified, the page size will + // be the maximum. Fewer tasks than requested might be returned, + // even if more tasks exist; use + // [next_page_token][google.cloud.tasks.v2.ListTasksResponse.next_page_token] in the + // response to determine if more tasks exist. + int32 page_size = 3; + + // A token identifying the page of results to return. + // + // To request the first page results, page_token must be empty. To + // request the next page of results, page_token must be the value of + // [next_page_token][google.cloud.tasks.v2.ListTasksResponse.next_page_token] returned + // from the previous call to [ListTasks][google.cloud.tasks.v2.CloudTasks.ListTasks] + // method. + // + // The page token is valid for only 2 hours. + string page_token = 4; +} + +// Response message for listing tasks using [ListTasks][google.cloud.tasks.v2.CloudTasks.ListTasks]. +message ListTasksResponse { + // The list of tasks. + repeated Task tasks = 1; + + // A token to retrieve next page of results. + // + // To return the next page of results, call + // [ListTasks][google.cloud.tasks.v2.CloudTasks.ListTasks] with this value as the + // [page_token][google.cloud.tasks.v2.ListTasksRequest.page_token]. + // + // If the next_page_token is empty, there are no more results. + string next_page_token = 2; +} + +// Request message for getting a task using [GetTask][google.cloud.tasks.v2.CloudTasks.GetTask]. +message GetTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2.Task] resource. + Task.View response_view = 2; +} + +// Request message for [CreateTask][google.cloud.tasks.v2.CloudTasks.CreateTask]. +message CreateTaskRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + // + // The queue must already exist. + string parent = 1; + + // Required. + // + // The task to add. + // + // Task names have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID`. + // The user can optionally specify a task [name][google.cloud.tasks.v2.Task.name]. If a + // name is not specified then the system will generate a random + // unique task id, which will be set in the task returned in the + // [response][google.cloud.tasks.v2.Task.name]. + // + // If [schedule_time][google.cloud.tasks.v2.Task.schedule_time] is not set or is in the + // past then Cloud Tasks will set it to the current time. + // + // Task De-duplication: + // + // Explicitly specifying a task ID enables task de-duplication. If + // a task's ID is identical to that of an existing task or a task + // that was deleted or executed recently then the call will fail + // with [ALREADY_EXISTS][google.rpc.Code.ALREADY_EXISTS]. + // If the task's queue was created using Cloud Tasks, then another task with + // the same name can't be created for ~1hour after the original task was + // deleted or executed. If the task's queue was created using queue.yaml or + // queue.xml, then another task with the same name can't be created + // for ~9days after the original task was deleted or executed. + // + // Because there is an extra lookup cost to identify duplicate task + // names, these [CreateTask][google.cloud.tasks.v2.CloudTasks.CreateTask] calls have significantly + // increased latency. Using hashed strings for the task id or for + // the prefix of the task id is recommended. Choosing task ids that + // are sequential or have sequential prefixes, for example using a + // timestamp, causes an increase in latency and error rates in all + // task commands. The infrastructure relies on an approximately + // uniform distribution of task ids to store and serve tasks + // efficiently. + Task task = 2; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2.Task] resource. + Task.View response_view = 3; +} + +// Request message for deleting a task using +// [DeleteTask][google.cloud.tasks.v2.CloudTasks.DeleteTask]. +message DeleteTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; +} + +// Request message for forcing a task to run now using +// [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask]. +message RunTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2.Task] resource. + Task.View response_view = 2; +} diff --git a/google/cloud/tasks/v2/cloudtasks_gapic.yaml b/google/cloud/tasks/v2/cloudtasks_gapic.yaml new file mode 100644 index 0000000000..1252c921f7 --- /dev/null +++ b/google/cloud/tasks/v2/cloudtasks_gapic.yaml @@ -0,0 +1,441 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.tasks.v2 + python: + package_name: google.cloud.tasks_v2.gapic + go: + package_name: cloud.google.com/go/cloudtasks/apiv2 + csharp: + package_name: Google.Cloud.Tasks.V2 + ruby: + package_name: Google::Cloud::Tasks::V2 + php: + package_name: Google\Cloud\Tasks\V2 + nodejs: + package_name: tasks.v2 +# The configuration for the license header to put on generated files. +license_header: + # The file containing the copyright line(s). + copyright_file: copyright-google.txt + # The file containing the raw license header without any copyright line(s). + license_file: license-header-apache-2.0.txt +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.tasks.v2.CloudTasks + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/queues/{queue} + entity_name: queue + - name_pattern: projects/{project}/locations/{location}/queues/{queue}/tasks/{task} + entity_name: task + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListQueues + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: queues + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 10000 + - name: GetQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: CreateQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - queue + required_fields: + - parent + - queue + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 10000 + - name: UpdateQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - queue + - update_mask + required_fields: + - queue + header_request_params: + - queue.name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + queue.name: queue + timeout_millis: 10000 + - name: DeleteQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: PurgeQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: PauseQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: ResumeQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: GetIamPolicy + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + required_fields: + - resource + header_request_params: + - resource + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: SetIamPolicy + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + - policy + required_fields: + - resource + - policy + header_request_params: + - resource + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: TestIamPermissions + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + - permissions + required_fields: + - resource + - permissions + header_request_params: + - resource + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: ListTasks + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: tasks + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: queue + timeout_millis: 10000 + - name: GetTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 + - name: CreateTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - task + required_fields: + - parent + - task + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: queue + timeout_millis: 10000 + - name: DeleteTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 + - name: RunTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 +resource_name_generation: +- message_name: Queue + field_entity_map: + name: queue +- message_name: Task + field_entity_map: + name: task +- message_name: ListQueuesRequest + field_entity_map: + parent: location +- message_name: GetQueueRequest + field_entity_map: + name: queue +- message_name: CreateQueueRequest + field_entity_map: + parent: location +- message_name: UpdateQueueRequest + field_entity_map: + queue.name: queue +- message_name: DeleteQueueRequest + field_entity_map: + name: queue +- message_name: PurgeQueueRequest + field_entity_map: + name: queue +- message_name: PauseQueueRequest + field_entity_map: + name: queue +- message_name: ResumeQueueRequest + field_entity_map: + name: queue +- message_name: ListTasksRequest + field_entity_map: + parent: queue +- message_name: GetTaskRequest + field_entity_map: + name: task +- message_name: CreateTaskRequest + field_entity_map: + parent: queue +- message_name: DeleteTaskRequest + field_entity_map: + name: task +- message_name: RunTaskRequest + field_entity_map: + name: task +- message_name: google.iam.v1.GetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.SetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.TestIamPermissionsRequest + field_entity_map: + resource: "*" diff --git a/google/cloud/tasks/v2/queue.proto b/google/cloud/tasks/v2/queue.proto new file mode 100644 index 0000000000..b38b614151 --- /dev/null +++ b/google/cloud/tasks/v2/queue.proto @@ -0,0 +1,342 @@ +// Copyright 2019 Google LLC. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +syntax = "proto3"; + +package google.cloud.tasks.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/tasks/v2/target.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "QueueProto"; +option java_package = "com.google.cloud.tasks.v2"; + + +// A queue is a container of related tasks. Queues are configured to manage +// how those tasks are dispatched. Configurable properties include rate limits, +// retry options, queue types, and others. +message Queue { + // State of the queue. + enum State { + // Unspecified state. + STATE_UNSPECIFIED = 0; + + // The queue is running. Tasks can be dispatched. + // + // If the queue was created using Cloud Tasks and the queue has + // had no activity (method calls or task dispatches) for 30 days, + // the queue may take a few minutes to re-activate. Some method + // calls may return [NOT_FOUND][google.rpc.Code.NOT_FOUND] and + // tasks may not be dispatched for a few minutes until the queue + // has been re-activated. + RUNNING = 1; + + // Tasks are paused by the user. If the queue is paused then Cloud + // Tasks will stop delivering tasks from it, but more tasks can + // still be added to it by the user. + PAUSED = 2; + + // The queue is disabled. + // + // A queue becomes `DISABLED` when + // [queue.yaml](https://cloud.google.com/appengine/docs/python/config/queueref) + // or + // [queue.xml](https://cloud.google.com/appengine/docs/standard/java/config/queueref) + // is uploaded which does not contain the queue. You cannot directly disable + // a queue. + // + // When a queue is disabled, tasks can still be added to a queue + // but the tasks are not dispatched. + // + // To permanently delete this queue and all of its tasks, call + // [DeleteQueue][google.cloud.tasks.v2.CloudTasks.DeleteQueue]. + DISABLED = 3; + } + + // Caller-specified and required in [CreateQueue][google.cloud.tasks.v2.CloudTasks.CreateQueue], + // after which it becomes output only. + // + // The queue name. + // + // The queue name must have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + // + // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), colons (:), or periods (.). + // For more information, see + // [Identifying + // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + // * `LOCATION_ID` is the canonical ID for the queue's location. + // The list of available locations can be obtained by calling + // [ListLocations][google.cloud.location.Locations.ListLocations]. + // For more information, see https://cloud.google.com/about/locations/. + // * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or + // hyphens (-). The maximum length is 100 characters. + string name = 1; + + // Overrides for + // [task-level app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing]. + // These settings apply only to + // [App Engine tasks][google.cloud.tasks.v2.AppEngineHttpRequest] in this queue. + // + // If set, `app_engine_routing_override` is used for all + // [App Engine tasks][google.cloud.tasks.v2.AppEngineHttpRequest] in the queue, no matter what the + // setting is for the + // [task-level app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing]. + AppEngineRouting app_engine_routing_override = 2; + + // Rate limits for task dispatches. + // + // [rate_limits][google.cloud.tasks.v2.Queue.rate_limits] and [retry_config][google.cloud.tasks.v2.Queue.retry_config] are + // related because they both control task attempts. However they control task + // attempts in different ways: + // + // * [rate_limits][google.cloud.tasks.v2.Queue.rate_limits] controls the total rate of + // dispatches from a queue (i.e. all traffic dispatched from the + // queue, regardless of whether the dispatch is from a first + // attempt or a retry). + // * [retry_config][google.cloud.tasks.v2.Queue.retry_config] controls what happens to + // particular a task after its first attempt fails. That is, + // [retry_config][google.cloud.tasks.v2.Queue.retry_config] controls task retries (the + // second attempt, third attempt, etc). + // + // The queue's actual dispatch rate is the result of: + // + // * Number of tasks in the queue + // * User-specified throttling: [rate_limits][google.cloud.tasks.v2.Queue.rate_limits], + // [retry_config][google.cloud.tasks.v2.Queue.retry_config], and the + // [queue's state][google.cloud.tasks.v2.Queue.state]. + // * System throttling due to `429` (Too Many Requests) or `503` (Service + // Unavailable) responses from the worker, high error rates, or to smooth + // sudden large traffic spikes. + RateLimits rate_limits = 3; + + // Settings that determine the retry behavior. + // + // * For tasks created using Cloud Tasks: the queue-level retry settings + // apply to all tasks in the queue that were created using Cloud Tasks. + // Retry settings cannot be set on individual tasks. + // * For tasks created using the App Engine SDK: the queue-level retry + // settings apply to all tasks in the queue which do not have retry settings + // explicitly set on the task and were created by the App Engine SDK. See + // [App Engine + // documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks). + RetryConfig retry_config = 4; + + // Output only. The state of the queue. + // + // `state` can only be changed by called + // [PauseQueue][google.cloud.tasks.v2.CloudTasks.PauseQueue], + // [ResumeQueue][google.cloud.tasks.v2.CloudTasks.ResumeQueue], or uploading + // [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref). + // [UpdateQueue][google.cloud.tasks.v2.CloudTasks.UpdateQueue] cannot be used to change `state`. + State state = 5; + + // Output only. The last time this queue was purged. + // + // All tasks that were [created][google.cloud.tasks.v2.Task.create_time] before this time + // were purged. + // + // A queue can be purged using [PurgeQueue][google.cloud.tasks.v2.CloudTasks.PurgeQueue], the + // [App Engine Task Queue SDK, or the Cloud + // Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue). + // + // Purge time will be truncated to the nearest microsecond. Purge + // time will be unset if the queue has never been purged. + google.protobuf.Timestamp purge_time = 6; +} + +// Rate limits. +// +// This message determines the maximum rate that tasks can be dispatched by a +// queue, regardless of whether the dispatch is a first task attempt or a retry. +// +// Note: The debugging command, [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask], will run a task +// even if the queue has reached its [RateLimits][google.cloud.tasks.v2.RateLimits]. +message RateLimits { + // The maximum rate at which tasks are dispatched from this queue. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // * For [App Engine queues][google.cloud.tasks.v2.AppEngineHttpQueue], the maximum allowed value + // is 500. + // + // + // This field has the same meaning as + // [rate in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate). + double max_dispatches_per_second = 1; + + // Output only. The max burst size. + // + // Max burst size limits how fast tasks in queue are processed when + // many tasks are in the queue and the rate is high. This field + // allows the queue to have a high rate so processing starts shortly + // after a task is enqueued, but still limits resource usage when + // many tasks are enqueued in a short period of time. + // + // The [token bucket](https://wikipedia.org/wiki/Token_Bucket) + // algorithm is used to control the rate of task dispatches. Each + // queue has a token bucket that holds tokens, up to the maximum + // specified by `max_burst_size`. Each time a task is dispatched, a + // token is removed from the bucket. Tasks will be dispatched until + // the queue's bucket runs out of tokens. The bucket will be + // continuously refilled with new tokens based on + // [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second]. + // + // Cloud Tasks will pick the value of `max_burst_size` based on the + // value of + // [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second]. + // + // For App Engine queues that were created or updated using + // `queue.yaml/xml`, `max_burst_size` is equal to + // [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size). + // Since `max_burst_size` is output only, if + // [UpdateQueue][google.cloud.tasks.v2.CloudTasks.UpdateQueue] is called on a queue + // created by `queue.yaml/xml`, `max_burst_size` will be reset based + // on the value of + // [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second], + // regardless of whether + // [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second] + // is updated. + // + int32 max_burst_size = 2; + + // The maximum number of concurrent tasks that Cloud Tasks allows + // to be dispatched for this queue. After this threshold has been + // reached, Cloud Tasks stops dispatching tasks until the number of + // concurrent requests decreases. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // The maximum allowed value is 5,000. + // + // + // This field has the same meaning as + // [max_concurrent_requests in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests). + int32 max_concurrent_dispatches = 3; +} + +// Retry config. +// +// These settings determine when a failed task attempt is retried. +message RetryConfig { + // Number of attempts per task. + // + // Cloud Tasks will attempt the task `max_attempts` times (that is, if the + // first attempt fails, then there will be `max_attempts - 1` retries). Must + // be >= -1. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // -1 indicates unlimited attempts. + // + // This field has the same meaning as + // [task_retry_limit in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + int32 max_attempts = 1; + + // If positive, `max_retry_duration` specifies the time limit for + // retrying a failed task, measured from when the task was first + // attempted. Once `max_retry_duration` time has passed *and* the + // task has been attempted [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts] + // times, no further attempts will be made and the task will be + // deleted. + // + // If zero, then the task age is unlimited. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // `max_retry_duration` will be truncated to the nearest second. + // + // This field has the same meaning as + // [task_age_limit in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration max_retry_duration = 2; + + // A task will be [scheduled][google.cloud.tasks.v2.Task.schedule_time] for retry between + // [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff] and + // [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff] duration after it fails, + // if the queue's [RetryConfig][google.cloud.tasks.v2.RetryConfig] specifies that the task should be + // retried. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // `min_backoff` will be truncated to the nearest second. + // + // This field has the same meaning as + // [min_backoff_seconds in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration min_backoff = 3; + + // A task will be [scheduled][google.cloud.tasks.v2.Task.schedule_time] for retry between + // [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff] and + // [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff] duration after it fails, + // if the queue's [RetryConfig][google.cloud.tasks.v2.RetryConfig] specifies that the task should be + // retried. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // `max_backoff` will be truncated to the nearest second. + // + // This field has the same meaning as + // [max_backoff_seconds in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration max_backoff = 4; + + // The time between retries will double `max_doublings` times. + // + // A task's retry interval starts at + // [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff], then doubles + // `max_doublings` times, then increases linearly, and finally + // retries retries at intervals of + // [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff] up to + // [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts] times. + // + // For example, if [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff] is 10s, + // [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff] is 300s, and + // `max_doublings` is 3, then the a task will first be retried in + // 10s. The retry interval will double three times, and then + // increase linearly by 2^3 * 10s. Finally, the task will retry at + // intervals of [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff] until the + // task has been attempted [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts] + // times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s, + // 240s, 300s, 300s, .... + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // This field has the same meaning as + // [max_doublings in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + int32 max_doublings = 5; +} diff --git a/google/cloud/tasks/v2/target.proto b/google/cloud/tasks/v2/target.proto new file mode 100644 index 0000000000..8cf991e97b --- /dev/null +++ b/google/cloud/tasks/v2/target.proto @@ -0,0 +1,274 @@ +// Copyright 2019 Google LLC. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +syntax = "proto3"; + +package google.cloud.tasks.v2; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "TargetProto"; +option java_package = "com.google.cloud.tasks.v2"; + + +// App Engine HTTP request. +// +// The message defines the HTTP request that is sent to an App Engine app when +// the task is dispatched. +// +// This proto can only be used for tasks in a queue which has +// [app_engine_http_queue][Queue.app_engine_http_queue] set. +// +// Using [AppEngineHttpRequest][google.cloud.tasks.v2.AppEngineHttpRequest] requires +// [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control) +// Google IAM permission for the project +// and the following scope: +// +// `https://www.googleapis.com/auth/cloud-platform` +// +// The task will be delivered to the App Engine app which belongs to the same +// project as the queue. For more information, see +// [How Requests are +// Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) +// and how routing is affected by +// [dispatch +// files](https://cloud.google.com/appengine/docs/python/config/dispatchref). +// Traffic is encrypted during transport and never leaves Google datacenters. +// Because this traffic is carried over a communication mechanism internal to +// Google, you cannot explicitly set the protocol (for example, HTTP or HTTPS). +// The request to the handler, however, will appear to have used the HTTP +// protocol. +// +// The [AppEngineRouting][google.cloud.tasks.v2.AppEngineRouting] used to construct the URL that the task is +// delivered to can be set at the queue-level or task-level: +// +// * If set, +// [app_engine_routing_override][google.cloud.tasks.v2.AppEngineHttpQueue.app_engine_routing_override] +// is used for all tasks in the queue, no matter what the setting +// is for the +// [task-level app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing]. +// +// +// The `url` that the task will be sent to is: +// +// * `url =` [host][google.cloud.tasks.v2.AppEngineRouting.host] `+` +// [relative_uri][google.cloud.tasks.v2.AppEngineHttpRequest.relative_uri] +// +// Tasks can be dispatched to secure app handlers, unsecure app handlers, and +// URIs restricted with +// [`login: +// admin`](https://cloud.google.com/appengine/docs/standard/python/config/appref). +// Because tasks are not run as any user, they cannot be dispatched to URIs +// restricted with +// [`login: +// required`](https://cloud.google.com/appengine/docs/standard/python/config/appref) +// Task dispatches also do not follow redirects. +// +// The task attempt has succeeded if the app's request handler returns +// an HTTP response code in the range [`200` - `299`]. `503` is +// considered an App Engine system error instead of an application +// error. Requests returning error `503` will be retried regardless of +// retry configuration and not counted against retry counts. +// Any other response code or a failure to receive a response before the +// deadline is a failed attempt. +message AppEngineHttpRequest { + // The HTTP method to use for the request. The default is POST. + // + // The app's request handler for the task's target URL must be able to handle + // HTTP requests with this http_method, otherwise the task attempt will fail + // with error code 405 (Method Not Allowed). See + // [Writing a push task request + // handler](https://cloud.google.com/appengine/docs/java/taskqueue/push/creating-handlers#writing_a_push_task_request_handler) + // and the documentation for the request handlers in the language your app is + // written in e.g. + // [Python Request + // Handler](https://cloud.google.com/appengine/docs/python/tools/webapp/requesthandlerclass). + HttpMethod http_method = 1; + + // Task-level setting for App Engine routing. + // + // If set, + // [app_engine_routing_override][google.cloud.tasks.v2.AppEngineHttpQueue.app_engine_routing_override] + // is used for all tasks in the queue, no matter what the setting is for the + // [task-level app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing]. + AppEngineRouting app_engine_routing = 2; + + // The relative URI. + // + // The relative URI must begin with "/" and must be a valid HTTP relative URI. + // It can contain a path and query string arguments. + // If the relative URI is empty, then the root path "/" will be used. + // No spaces are allowed, and the maximum length allowed is 2083 characters. + string relative_uri = 3; + + // HTTP request headers. + // + // This map contains the header field names and values. + // Headers can be set when the + // [task is created][google.cloud.tasks.v2.CloudTasks.CreateTask]. + // Repeated headers are not supported but a header value can contain commas. + // + // Cloud Tasks sets some headers to default values: + // + // * `User-Agent`: By default, this header is + // `"AppEngine-Google; (+http://code.google.com/appengine)"`. + // This header can be modified, but Cloud Tasks will append + // `"AppEngine-Google; (+http://code.google.com/appengine)"` to the + // modified `User-Agent`. + // + // If the task has a [body][google.cloud.tasks.v2.AppEngineHttpRequest.body], Cloud + // Tasks sets the following headers: + // + // * `Content-Type`: By default, the `Content-Type` header is set to + // `"application/octet-stream"`. The default can be overridden by explicitly + // setting `Content-Type` to a particular media type when the + // [task is created][google.cloud.tasks.v2.CloudTasks.CreateTask]. + // For example, `Content-Type` can be set to `"application/json"`. + // * `Content-Length`: This is computed by Cloud Tasks. This value is + // output only. It cannot be changed. + // + // The headers below cannot be set or overridden: + // + // * `Host` + // * `X-Google-*` + // * `X-AppEngine-*` + // + // In addition, Cloud Tasks sets some headers when the task is dispatched, + // such as headers containing information about the task; see + // [request + // headers](https://cloud.google.com/appengine/docs/python/taskqueue/push/creating-handlers#reading_request_headers). + // These headers are set only when the task is dispatched, so they are not + // visible when the task is returned in a Cloud Tasks response. + // + // Although there is no specific limit for the maximum number of headers or + // the size, there is a limit on the maximum size of the [Task][google.cloud.tasks.v2.Task]. For more + // information, see the [CreateTask][google.cloud.tasks.v2.CloudTasks.CreateTask] documentation. + map headers = 4; + + // HTTP request body. + // + // A request body is allowed only if the HTTP method is POST or PUT. It is + // an error to set a body on a task with an incompatible [HttpMethod][google.cloud.tasks.v2.HttpMethod]. + bytes body = 5; +} + +// App Engine Routing. +// +// Defines routing characteristics specific to App Engine - service, version, +// and instance. +// +// For more information about services, versions, and instances see +// [An Overview of App +// Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine), +// [Microservices Architecture on Google App +// Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine), +// [App Engine Standard request +// routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed), +// and [App Engine Flex request +// routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). +message AppEngineRouting { + // App service. + // + // By default, the task is sent to the service which is the default + // service when the task is attempted. + // + // For some queues or tasks which were created using the App Engine + // Task Queue API, [host][google.cloud.tasks.v2.AppEngineRouting.host] is not parsable + // into [service][google.cloud.tasks.v2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2.AppEngineRouting.instance]. For example, some tasks + // which were created using the App Engine SDK use a custom domain + // name; custom domains are not parsed by Cloud Tasks. If + // [host][google.cloud.tasks.v2.AppEngineRouting.host] is not parsable, then + // [service][google.cloud.tasks.v2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2.AppEngineRouting.instance] are the empty string. + string service = 1; + + // App version. + // + // By default, the task is sent to the version which is the default + // version when the task is attempted. + // + // For some queues or tasks which were created using the App Engine + // Task Queue API, [host][google.cloud.tasks.v2.AppEngineRouting.host] is not parsable + // into [service][google.cloud.tasks.v2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2.AppEngineRouting.instance]. For example, some tasks + // which were created using the App Engine SDK use a custom domain + // name; custom domains are not parsed by Cloud Tasks. If + // [host][google.cloud.tasks.v2.AppEngineRouting.host] is not parsable, then + // [service][google.cloud.tasks.v2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2.AppEngineRouting.instance] are the empty string. + string version = 2; + + // App instance. + // + // By default, the task is sent to an instance which is available when + // the task is attempted. + // + // Requests can only be sent to a specific instance if + // [manual scaling is used in App Engine + // Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes). + // App Engine Flex does not support instances. For more information, see + // [App Engine Standard request + // routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) + // and [App Engine Flex request + // routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). + string instance = 3; + + // Output only. The host that the task is sent to. + // + // The host is constructed from the domain name of the app associated with + // the queue's project ID (for example .appspot.com), and the + // [service][google.cloud.tasks.v2.AppEngineRouting.service], [version][google.cloud.tasks.v2.AppEngineRouting.version], + // and [instance][google.cloud.tasks.v2.AppEngineRouting.instance]. Tasks which were created using + // the App Engine SDK might have a custom domain name. + // + // For more information, see + // [How Requests are + // Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed). + string host = 4; +} + +// The HTTP method used to deliver the task. +enum HttpMethod { + // HTTP method unspecified + HTTP_METHOD_UNSPECIFIED = 0; + + // HTTP POST + POST = 1; + + // HTTP GET + GET = 2; + + // HTTP HEAD + HEAD = 3; + + // HTTP PUT + PUT = 4; + + // HTTP DELETE + DELETE = 5; + + // HTTP PATCH + PATCH = 6; + + // HTTP OPTIONS + OPTIONS = 7; +} diff --git a/google/cloud/tasks/v2/task.proto b/google/cloud/tasks/v2/task.proto new file mode 100644 index 0000000000..11be05c46d --- /dev/null +++ b/google/cloud/tasks/v2/task.proto @@ -0,0 +1,182 @@ +// Copyright 2019 Google LLC. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +syntax = "proto3"; + +package google.cloud.tasks.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/tasks/v2/target.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "TaskProto"; +option java_package = "com.google.cloud.tasks.v2"; + + +// A unit of scheduled work. +message Task { + // The view specifies a subset of [Task][google.cloud.tasks.v2.Task] data. + // + // When a task is returned in a response, not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + enum View { + // Unspecified. Defaults to BASIC. + VIEW_UNSPECIFIED = 0; + + // The basic view omits fields which can be large or can contain + // sensitive data. + // + // This view does not include the + // [body in AppEngineHttpRequest][google.cloud.tasks.v2.AppEngineHttpRequest.body]. + // Bodies are desirable to return only when needed, because they + // can be large and because of the sensitivity of the data that you + // choose to store in it. + BASIC = 1; + + // All information is returned. + // + // Authorization for [FULL][google.cloud.tasks.v2.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Queue][google.cloud.tasks.v2.Queue] resource. + FULL = 2; + } + + // Optionally caller-specified in [CreateTask][google.cloud.tasks.v2.CloudTasks.CreateTask]. + // + // The task name. + // + // The task name must have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + // + // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), colons (:), or periods (.). + // For more information, see + // [Identifying + // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + // * `LOCATION_ID` is the canonical ID for the task's location. + // The list of available locations can be obtained by calling + // [ListLocations][google.cloud.location.Locations.ListLocations]. + // For more information, see https://cloud.google.com/about/locations/. + // * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or + // hyphens (-). The maximum length is 100 characters. + // * `TASK_ID` can contain only letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), or underscores (_). The maximum length is 500 characters. + string name = 1; + + // Required. The message to send to the worker. + oneof message_type { + // HTTP request that is sent to the App Engine app handler. + // + // An App Engine task is a task that has [AppEngineHttpRequest][google.cloud.tasks.v2.AppEngineHttpRequest] set. + AppEngineHttpRequest app_engine_http_request = 2; + } + + // The time when the task is scheduled to be attempted. + // + // For App Engine queues, this is when the task will be attempted or retried. + // + // `schedule_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp schedule_time = 4; + + // Output only. The time that the task was created. + // + // `create_time` will be truncated to the nearest second. + google.protobuf.Timestamp create_time = 5; + + // The deadline for requests sent to the worker. If the worker does not + // respond by this deadline then the request is cancelled and the attempt + // is marked as a `DEADLINE_EXCEEDED` failure. Cloud Tasks will retry the + // task according to the [RetryConfig][google.cloud.tasks.v2.RetryConfig]. + // + // Note that when the request is cancelled, Cloud Tasks will stop listing for + // the response, but whether the worker stops processing depends on the + // worker. For example, if the worker is stuck, it may not react to cancelled + // requests. + // + // The default and maximum values depend on the type of request: + // + // + // * For [App Engine tasks][google.cloud.tasks.v2.AppEngineHttpRequest], 0 indicates that the + // request has the default deadline. The default deadline depends on the + // [scaling + // type](https://cloud.google.com/appengine/docs/standard/go/how-instances-are-managed#instance_scaling) + // of the service: 10 minutes for standard apps with automatic scaling, 24 + // hours for standard apps with manual and basic scaling, and 60 minutes for + // flex apps. If the request deadline is set, it must be in the interval [15 + // seconds, 24 hours 15 seconds]. Regardless of the task's + // `dispatch_deadline`, the app handler will not run for longer than than + // the service's timeout. We recommend setting the `dispatch_deadline` to + // at most a few seconds more than the app handler's timeout. For more + // information see + // [Timeouts](https://cloud.google.com/tasks/docs/creating-appengine-handlers#timeouts). + // + // `dispatch_deadline` will be truncated to the nearest millisecond. The + // deadline is an approximate deadline. + google.protobuf.Duration dispatch_deadline = 6; + + // Output only. The number of attempts dispatched. + // + // This count includes attempts which have been dispatched but haven't + // received a response. + int32 dispatch_count = 7; + + // Output only. The number of attempts which have received a response. + int32 response_count = 8; + + // Output only. The status of the task's first attempt. + // + // Only [dispatch_time][google.cloud.tasks.v2.Attempt.dispatch_time] will be set. + // The other [Attempt][google.cloud.tasks.v2.Attempt] information is not retained by Cloud Tasks. + Attempt first_attempt = 9; + + // Output only. The status of the task's last attempt. + Attempt last_attempt = 10; + + // Output only. The view specifies which subset of the [Task][google.cloud.tasks.v2.Task] has + // been returned. + View view = 11; +} + +// The status of a task attempt. +message Attempt { + // Output only. The time that this attempt was scheduled. + // + // `schedule_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp schedule_time = 1; + + // Output only. The time that this attempt was dispatched. + // + // `dispatch_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp dispatch_time = 2; + + // Output only. The time that this attempt response was received. + // + // `response_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp response_time = 3; + + // Output only. The response from the worker for this attempt. + // + // If `response_time` is unset, then the task has not been attempted or is + // currently running and the `response_status` field is meaningless. + google.rpc.Status response_status = 4; +}