Package com.google.cloud.tasks.v2beta3 (2.21.0)

A client to Cloud Tasks API

The interfaces provided are listed below, along with usage samples.

CloudTasksClient

Service Description: Cloud Tasks allows developers to manage the execution of background work in their applications.

Sample for CloudTasksClient:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 try (CloudTasksClient cloudTasksClient = CloudTasksClient.create()) {
   QueueName name = QueueName.of("[PROJECT]", "[LOCATION]", "[QUEUE]");
   Queue response = cloudTasksClient.getQueue(name);
 }
 

Classes

AppEngineHttpQueue

App Engine HTTP queue.

The task will be delivered to the App Engine application hostname specified by its AppEngineHttpQueue and AppEngineHttpRequest. The documentation for AppEngineHttpRequest explains how the task's host URL is constructed.

Using AppEngineHttpQueue requires appengine.applications.get Google IAM permission for the project and the following scope:

https://www.googleapis.com/auth/cloud-platform

Protobuf type google.cloud.tasks.v2beta3.AppEngineHttpQueue

AppEngineHttpQueue.Builder

App Engine HTTP queue.

The task will be delivered to the App Engine application hostname specified by its AppEngineHttpQueue and AppEngineHttpRequest. The documentation for AppEngineHttpRequest explains how the task's host URL is constructed.

Using AppEngineHttpQueue requires appengine.applications.get Google IAM permission for the project and the following scope:

https://www.googleapis.com/auth/cloud-platform

Protobuf type google.cloud.tasks.v2beta3.AppEngineHttpQueue

AppEngineHttpRequest

App Engine HTTP request.

The message defines the HTTP request that is sent to an App Engine app when the task is dispatched.

Using AppEngineHttpRequest requires appengine.applications.get 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 and how routing is affected by dispatch files. 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 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 is used for all tasks in the queue, no matter what the setting is for the task-level app_engine_routing.

The url that the task will be sent to is:

  • url = host + relative_uri

    Tasks can be dispatched to secure app handlers, unsecure app handlers, and URIs restricted with login: admin. Because tasks are not run as any user, they cannot be dispatched to URIs restricted with login: required 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]. The task attempt has failed if the app's handler returns a non-2xx response code or Cloud Tasks does not receive response before the deadline. Failed tasks will be retried according to the retry configuration. 503 (Service Unavailable) is considered an App Engine system error instead of an application error and will cause Cloud Tasks' traffic congestion control to temporarily throttle the queue's dispatches. Unlike other types of task targets, a 429 (Too Many Requests) response from an app handler does not cause traffic congestion control to throttle the queue.

Protobuf type google.cloud.tasks.v2beta3.AppEngineHttpRequest

AppEngineHttpRequest.Builder

App Engine HTTP request.

The message defines the HTTP request that is sent to an App Engine app when the task is dispatched.

Using AppEngineHttpRequest requires appengine.applications.get 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 and how routing is affected by dispatch files. 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 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 is used for all tasks in the queue, no matter what the setting is for the task-level app_engine_routing.

The url that the task will be sent to is:

  • url = host + relative_uri

    Tasks can be dispatched to secure app handlers, unsecure app handlers, and URIs restricted with login: admin. Because tasks are not run as any user, they cannot be dispatched to URIs restricted with login: required 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]. The task attempt has failed if the app's handler returns a non-2xx response code or Cloud Tasks does not receive response before the deadline. Failed tasks will be retried according to the retry configuration. 503 (Service Unavailable) is considered an App Engine system error instead of an application error and will cause Cloud Tasks' traffic congestion control to temporarily throttle the queue's dispatches. Unlike other types of task targets, a 429 (Too Many Requests) response from an app handler does not cause traffic congestion control to throttle the queue.

Protobuf type google.cloud.tasks.v2beta3.AppEngineHttpRequest

AppEngineRouting

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, Microservices Architecture on Google App Engine, App Engine Standard request routing, and App Engine Flex request routing.

Protobuf type google.cloud.tasks.v2beta3.AppEngineRouting

AppEngineRouting.Builder

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, Microservices Architecture on Google App Engine, App Engine Standard request routing, and App Engine Flex request routing.

Protobuf type google.cloud.tasks.v2beta3.AppEngineRouting

Attempt

The status of a task attempt.

Protobuf type google.cloud.tasks.v2beta3.Attempt

Attempt.Builder

The status of a task attempt.

Protobuf type google.cloud.tasks.v2beta3.Attempt

CloudTasksClient

Service Description: Cloud Tasks allows developers to manage the execution of background work in their applications.

This class provides the ability to make remote calls to the backing service through method calls that map to API methods. Sample code to get started:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 try (CloudTasksClient cloudTasksClient = CloudTasksClient.create()) {
   QueueName name = QueueName.of("[PROJECT]", "[LOCATION]", "[QUEUE]");
   Queue response = cloudTasksClient.getQueue(name);
 }
 

Note: close() needs to be called on the CloudTasksClient object to clean up resources such as threads. In the example above, try-with-resources is used, which automatically calls close().

The surface of this class includes several types of Java methods for each of the API's methods:

  1. A "flattened" method. With this type of method, the fields of the request type have been converted into function parameters. It may be the case that not all fields are available as parameters, and not every API method will have a flattened method entry point.
  2. A "request object" method. This type of method only takes one parameter, a request object, which must be constructed before the call. Not every API method will have a request object method.
  3. A "callable" method. This type of method takes no parameters and returns an immutable API callable object, which can be used to initiate calls to the service.

See the individual methods for example code.

Many parameters require resource names to be formatted in a particular way. To assist with these names, this class includes a format method for each type of name, and additionally a parse method to extract the individual identifiers contained within names that are returned.

This class can be customized by passing in a custom instance of CloudTasksSettings to create(). For example:

To customize credentials:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 CloudTasksSettings cloudTasksSettings =
     CloudTasksSettings.newBuilder()
         .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
         .build();
 CloudTasksClient cloudTasksClient = CloudTasksClient.create(cloudTasksSettings);
 

To customize the endpoint:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 CloudTasksSettings cloudTasksSettings =
     CloudTasksSettings.newBuilder().setEndpoint(myEndpoint).build();
 CloudTasksClient cloudTasksClient = CloudTasksClient.create(cloudTasksSettings);
 

To use REST (HTTP1.1/JSON) transport (instead of gRPC) for sending and receiving requests over the wire:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 CloudTasksSettings cloudTasksSettings = CloudTasksSettings.newHttpJsonBuilder().build();
 CloudTasksClient cloudTasksClient = CloudTasksClient.create(cloudTasksSettings);
 

Please refer to the GitHub repository's samples for more quickstart code snippets.

CloudTasksClient.ListQueuesFixedSizeCollection

CloudTasksClient.ListQueuesPage

CloudTasksClient.ListQueuesPagedResponse

CloudTasksClient.ListTasksFixedSizeCollection

CloudTasksClient.ListTasksPage

CloudTasksClient.ListTasksPagedResponse

CloudTasksGrpc

Cloud Tasks allows developers to manage the execution of background work in their applications.

CloudTasksGrpc.CloudTasksBlockingStub

A stub to allow clients to do synchronous rpc calls to service CloudTasks.

Cloud Tasks allows developers to manage the execution of background work in their applications.

CloudTasksGrpc.CloudTasksFutureStub

A stub to allow clients to do ListenableFuture-style rpc calls to service CloudTasks.

Cloud Tasks allows developers to manage the execution of background work in their applications.

CloudTasksGrpc.CloudTasksImplBase

Base class for the server implementation of the service CloudTasks.

Cloud Tasks allows developers to manage the execution of background work in their applications.

CloudTasksGrpc.CloudTasksStub

A stub to allow clients to do asynchronous rpc calls to service CloudTasks.

Cloud Tasks allows developers to manage the execution of background work in their applications.

CloudTasksProto

CloudTasksSettings

Settings class to configure an instance of CloudTasksClient.

The default instance has everything set to sensible defaults:

  • The default service address (cloudtasks.googleapis.com) and default port (443) are used.
  • Credentials are acquired automatically through Application Default Credentials.
  • Retries are configured for idempotent methods but not for non-idempotent methods.

The builder of this class is recursive, so contained classes are themselves builders. When build() is called, the tree of builders is called to create the complete settings object.

For example, to set the total timeout of getQueue to 30 seconds:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 CloudTasksSettings.Builder cloudTasksSettingsBuilder = CloudTasksSettings.newBuilder();
 cloudTasksSettingsBuilder
     .getQueueSettings()
     .setRetrySettings(
         cloudTasksSettingsBuilder
             .getQueueSettings()
             .getRetrySettings()
             .toBuilder()
             .setTotalTimeout(Duration.ofSeconds(30))
             .build());
 CloudTasksSettings cloudTasksSettings = cloudTasksSettingsBuilder.build();
 

CloudTasksSettings.Builder

Builder for CloudTasksSettings.

CreateQueueRequest

Request message for CreateQueue.

Protobuf type google.cloud.tasks.v2beta3.CreateQueueRequest

CreateQueueRequest.Builder

Request message for CreateQueue.

Protobuf type google.cloud.tasks.v2beta3.CreateQueueRequest

CreateTaskRequest

Request message for CreateTask.

Protobuf type google.cloud.tasks.v2beta3.CreateTaskRequest

CreateTaskRequest.Builder

Request message for CreateTask.

Protobuf type google.cloud.tasks.v2beta3.CreateTaskRequest

DeleteQueueRequest

Request message for DeleteQueue.

Protobuf type google.cloud.tasks.v2beta3.DeleteQueueRequest

DeleteQueueRequest.Builder

Request message for DeleteQueue.

Protobuf type google.cloud.tasks.v2beta3.DeleteQueueRequest

DeleteTaskRequest

Request message for deleting a task using DeleteTask.

Protobuf type google.cloud.tasks.v2beta3.DeleteTaskRequest

DeleteTaskRequest.Builder

Request message for deleting a task using DeleteTask.

Protobuf type google.cloud.tasks.v2beta3.DeleteTaskRequest

GetQueueRequest

Request message for GetQueue.

Protobuf type google.cloud.tasks.v2beta3.GetQueueRequest

GetQueueRequest.Builder

Request message for GetQueue.

Protobuf type google.cloud.tasks.v2beta3.GetQueueRequest

GetTaskRequest

Request message for getting a task using GetTask.

Protobuf type google.cloud.tasks.v2beta3.GetTaskRequest

GetTaskRequest.Builder

Request message for getting a task using GetTask.

Protobuf type google.cloud.tasks.v2beta3.GetTaskRequest

HttpRequest

HTTP request.

The task will be pushed to the worker as an HTTP request. If the worker or the redirected worker acknowledges the task by returning a successful HTTP response code ([200 - 299]), the task will be removed from the queue. If any other HTTP response code is returned or no response is received, the task will be retried according to the following:

  • User-specified throttling: retry configuration, rate limits, and the queue's state.

  • System throttling: To prevent the worker from overloading, Cloud Tasks may temporarily reduce the queue's effective rate. User-specified settings will not be changed.

    System throttling happens because:

    • Cloud Tasks backs off on all errors. Normally the backoff specified in rate limits will be used. But if the worker returns 429 (Too Many Requests), 503 (Service Unavailable), or the rate of errors is high, Cloud Tasks will use a higher backoff rate. The retry specified in the Retry-After HTTP response header is considered.

    • To prevent traffic spikes and to smooth sudden increases in traffic, dispatches ramp up slowly when the queue is newly created or idle and if large numbers of tasks suddenly become available to dispatch (due to spikes in create task rates, the queue being unpaused, or many tasks that are scheduled at the same time).

Protobuf type google.cloud.tasks.v2beta3.HttpRequest

HttpRequest.Builder

HTTP request.

The task will be pushed to the worker as an HTTP request. If the worker or the redirected worker acknowledges the task by returning a successful HTTP response code ([200 - 299]), the task will be removed from the queue. If any other HTTP response code is returned or no response is received, the task will be retried according to the following:

  • User-specified throttling: retry configuration, rate limits, and the queue's state.

  • System throttling: To prevent the worker from overloading, Cloud Tasks may temporarily reduce the queue's effective rate. User-specified settings will not be changed.

    System throttling happens because:

    • Cloud Tasks backs off on all errors. Normally the backoff specified in rate limits will be used. But if the worker returns 429 (Too Many Requests), 503 (Service Unavailable), or the rate of errors is high, Cloud Tasks will use a higher backoff rate. The retry specified in the Retry-After HTTP response header is considered.

    • To prevent traffic spikes and to smooth sudden increases in traffic, dispatches ramp up slowly when the queue is newly created or idle and if large numbers of tasks suddenly become available to dispatch (due to spikes in create task rates, the queue being unpaused, or many tasks that are scheduled at the same time).

Protobuf type google.cloud.tasks.v2beta3.HttpRequest

ListQueuesRequest

Request message for ListQueues.

Protobuf type google.cloud.tasks.v2beta3.ListQueuesRequest

ListQueuesRequest.Builder

Request message for ListQueues.

Protobuf type google.cloud.tasks.v2beta3.ListQueuesRequest

ListQueuesResponse

Response message for ListQueues.

Protobuf type google.cloud.tasks.v2beta3.ListQueuesResponse

ListQueuesResponse.Builder

Response message for ListQueues.

Protobuf type google.cloud.tasks.v2beta3.ListQueuesResponse

ListTasksRequest

Request message for listing tasks using ListTasks.

Protobuf type google.cloud.tasks.v2beta3.ListTasksRequest

ListTasksRequest.Builder

Request message for listing tasks using ListTasks.

Protobuf type google.cloud.tasks.v2beta3.ListTasksRequest

ListTasksResponse

Response message for listing tasks using ListTasks.

Protobuf type google.cloud.tasks.v2beta3.ListTasksResponse

ListTasksResponse.Builder

Response message for listing tasks using ListTasks.

Protobuf type google.cloud.tasks.v2beta3.ListTasksResponse

LocationName

LocationName.Builder

Builder for projects/{project}/locations/{location}.

OAuthToken

Contains information needed for generating an OAuth token. This type of authorization should generally only be used when calling Google APIs hosted on *.googleapis.com.

Protobuf type google.cloud.tasks.v2beta3.OAuthToken

OAuthToken.Builder

Contains information needed for generating an OAuth token. This type of authorization should generally only be used when calling Google APIs hosted on *.googleapis.com.

Protobuf type google.cloud.tasks.v2beta3.OAuthToken

OidcToken

Contains information needed for generating an OpenID Connect token. This type of authorization can be used for many scenarios, including calling Cloud Run, or endpoints where you intend to validate the token yourself.

Protobuf type google.cloud.tasks.v2beta3.OidcToken

OidcToken.Builder

Contains information needed for generating an OpenID Connect token. This type of authorization can be used for many scenarios, including calling Cloud Run, or endpoints where you intend to validate the token yourself.

Protobuf type google.cloud.tasks.v2beta3.OidcToken

PauseQueueRequest

Request message for PauseQueue.

Protobuf type google.cloud.tasks.v2beta3.PauseQueueRequest

PauseQueueRequest.Builder

Request message for PauseQueue.

Protobuf type google.cloud.tasks.v2beta3.PauseQueueRequest

ProjectName

ProjectName.Builder

Builder for ProjectName.

PullMessage

Pull Message.

This proto can only be used for tasks in a queue which has PULL type. It currently exists for backwards compatibility with the App Engine Task Queue SDK. This message type maybe returned with methods list and get, when the response view is FULL.

Protobuf type google.cloud.tasks.v2beta3.PullMessage

PullMessage.Builder

Pull Message.

This proto can only be used for tasks in a queue which has PULL type. It currently exists for backwards compatibility with the App Engine Task Queue SDK. This message type maybe returned with methods list and get, when the response view is FULL.

Protobuf type google.cloud.tasks.v2beta3.PullMessage

PurgeQueueRequest

Request message for PurgeQueue.

Protobuf type google.cloud.tasks.v2beta3.PurgeQueueRequest

PurgeQueueRequest.Builder

Request message for PurgeQueue.

Protobuf type google.cloud.tasks.v2beta3.PurgeQueueRequest

Queue

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.

Protobuf type google.cloud.tasks.v2beta3.Queue

Queue.Builder

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.

Protobuf type google.cloud.tasks.v2beta3.Queue

QueueName

QueueName.Builder

Builder for projects/{project}/locations/{location}/queues/{queue}.

QueueProto

QueueStats

Statistics for a queue.

Protobuf type google.cloud.tasks.v2beta3.QueueStats

QueueStats.Builder

Statistics for a queue.

Protobuf type google.cloud.tasks.v2beta3.QueueStats

RateLimits

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, will run a task even if the queue has reached its RateLimits.

Protobuf type google.cloud.tasks.v2beta3.RateLimits

RateLimits.Builder

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, will run a task even if the queue has reached its RateLimits.

Protobuf type google.cloud.tasks.v2beta3.RateLimits

ResumeQueueRequest

Request message for ResumeQueue.

Protobuf type google.cloud.tasks.v2beta3.ResumeQueueRequest

ResumeQueueRequest.Builder

Request message for ResumeQueue.

Protobuf type google.cloud.tasks.v2beta3.ResumeQueueRequest

RetryConfig

Retry config.

These settings determine when a failed task attempt is retried.

Protobuf type google.cloud.tasks.v2beta3.RetryConfig

RetryConfig.Builder

Retry config.

These settings determine when a failed task attempt is retried.

Protobuf type google.cloud.tasks.v2beta3.RetryConfig

RunTaskRequest

Request message for forcing a task to run now using RunTask.

Protobuf type google.cloud.tasks.v2beta3.RunTaskRequest

RunTaskRequest.Builder

Request message for forcing a task to run now using RunTask.

Protobuf type google.cloud.tasks.v2beta3.RunTaskRequest

StackdriverLoggingConfig

Configuration options for writing logs to Stackdriver Logging.

Protobuf type google.cloud.tasks.v2beta3.StackdriverLoggingConfig

StackdriverLoggingConfig.Builder

Configuration options for writing logs to Stackdriver Logging.

Protobuf type google.cloud.tasks.v2beta3.StackdriverLoggingConfig

TargetProto

Task

A unit of scheduled work.

Protobuf type google.cloud.tasks.v2beta3.Task

Task.Builder

A unit of scheduled work.

Protobuf type google.cloud.tasks.v2beta3.Task

TaskName

TaskName.Builder

Builder for projects/{project}/locations/{location}/queues/{queue}/tasks/{task}.

TaskProto

UpdateQueueRequest

Request message for UpdateQueue.

Protobuf type google.cloud.tasks.v2beta3.UpdateQueueRequest

UpdateQueueRequest.Builder

Request message for UpdateQueue.

Protobuf type google.cloud.tasks.v2beta3.UpdateQueueRequest

Interfaces

AppEngineHttpQueueOrBuilder

AppEngineHttpRequestOrBuilder

AppEngineRoutingOrBuilder

AttemptOrBuilder

CloudTasksGrpc.AsyncService

Cloud Tasks allows developers to manage the execution of background work in their applications.

CreateQueueRequestOrBuilder

CreateTaskRequestOrBuilder

DeleteQueueRequestOrBuilder

DeleteTaskRequestOrBuilder

GetQueueRequestOrBuilder

GetTaskRequestOrBuilder

HttpRequestOrBuilder

ListQueuesRequestOrBuilder

ListQueuesResponseOrBuilder

ListTasksRequestOrBuilder

ListTasksResponseOrBuilder

OAuthTokenOrBuilder

OidcTokenOrBuilder

PauseQueueRequestOrBuilder

PullMessageOrBuilder

PurgeQueueRequestOrBuilder

QueueOrBuilder

QueueStatsOrBuilder

RateLimitsOrBuilder

ResumeQueueRequestOrBuilder

RetryConfigOrBuilder

RunTaskRequestOrBuilder

StackdriverLoggingConfigOrBuilder

TaskOrBuilder

UpdateQueueRequestOrBuilder

Enums

HttpMethod

The HTTP method used to execute the task.

Protobuf enum google.cloud.tasks.v2beta3.HttpMethod

HttpRequest.AuthorizationHeaderCase

Queue.QueueTypeCase

Queue.State

State of the queue.

Protobuf enum google.cloud.tasks.v2beta3.Queue.State

Queue.Type

The type of the queue.

Protobuf enum google.cloud.tasks.v2beta3.Queue.Type

Task.PayloadTypeCase

Task.View

The view specifies a subset of 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.

Protobuf enum google.cloud.tasks.v2beta3.Task.View