0
# Google Cloud Tasks
1

2
Google Cloud Tasks is a fully managed service that allows you to manage the execution, dispatch and delivery of a large number of distributed tasks. It enables asynchronous task execution with HTTP endpoints or App Engine applications, featuring automatic retry logic, rate limiting, and comprehensive queue management.
3

4
## Package Information
5

6
- **Package Name**: google-cloud-tasks
7
- **Language**: Python
8
- **Installation**: `pip install google-cloud-tasks`
9

10
## Core Imports
11

12
```python
13
from google.cloud import tasks
14
```
15

16
For specific components:
17

18
```python
19
from google.cloud.tasks import CloudTasksClient, CloudTasksAsyncClient
20
from google.cloud.tasks import Queue, Task, HttpRequest, AppEngineHttpRequest
21
from typing import Dict
22
```
23

24
## Basic Usage
25

26
```python
27
from google.cloud import tasks
28

29
# Create a client
30
client = tasks.CloudTasksClient()
31

32
# Define project, location, and queue
33
project = 'my-project-id'
34
location = 'us-central1'
35
queue_name = 'my-queue'
36

37
# Create a queue
38
parent = client.common_location_path(project, location)
39
queue_path = client.queue_path(project, location, queue_name)
40

41
queue = tasks.Queue(name=queue_path)
42
created_queue = client.create_queue(parent=parent, queue=queue)
43

44
# Create an HTTP task
45
task = tasks.Task(
46
    http_request=tasks.HttpRequest(
47
        url='https://example.com/task-handler',
48
        http_method=tasks.HttpMethod.POST,
49
        body=b'{"data": "example"}'
50
    )
51
)
52

53
# Add the task to the queue
54
response = client.create_task(parent=queue_path, task=task)
55
print(f'Created task: {response.name}')
56

57
# Using context manager for automatic resource cleanup
58
with tasks.CloudTasksClient() as client:
59
    queue = client.get_queue(name=queue_path)
60
    print(f'Queue state: {queue.state}')
61
```
62

63
## Architecture
64

65
Google Cloud Tasks provides a comprehensive task queue system with these key components:
66

67
- **Clients**: Synchronous and asynchronous clients for API operations
68
- **Queues**: Containers for tasks with configurable rate limits, retry policies, and routing
69
- **Tasks**: Units of work that can target HTTP endpoints or App Engine applications
70
- **Request/Response Types**: Structured message types for all API operations
71
- **Authentication**: OAuth and OIDC token support for secure task execution
72

73
The service integrates with Google Cloud IAM for access control and provides automatic scaling, monitoring, and error handling for distributed task processing.
74

75
## Capabilities
76

77
### Client Operations
78

79
Core client functionality for managing Cloud Tasks service connections, authentication, and transport configuration. Includes both synchronous and asynchronous clients with identical APIs.
80

81
```python { .api }
82
class CloudTasksClient:
83
    def __init__(
84
        self, 
85
        *, 
86
        credentials=None, 
87
        transport=None, 
88
        client_options=None, 
89
        client_info=None
90
    ): ...
91
    
92
    @classmethod
93
    def from_service_account_file(cls, filename: str, *args, **kwargs): ...
94
    
95
    @classmethod
96
    def from_service_account_info(cls, info: dict, *args, **kwargs): ...
97

98
class CloudTasksAsyncClient:
99
    def __init__(
100
        self, 
101
        *, 
102
        credentials=None, 
103
        transport=None, 
104
        client_options=None, 
105
        client_info=None
106
    ): ...
107
```
108

109
[Client Operations](./client-operations.md)
110

111
### Queue Management
112

113
Comprehensive queue lifecycle management including creation, configuration, monitoring, and control operations. Queues serve as containers for tasks with configurable rate limits, retry policies, and routing rules.
114

115
```python { .api }
116
def list_queues(self, request=None, *, parent=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> ListQueuesPager: ...
117
def get_queue(self, request=None, *, name=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Queue: ...
118
def create_queue(self, request=None, *, parent=None, queue=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Queue: ...
119
def update_queue(self, request=None, *, queue=None, update_mask=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Queue: ...
120
def delete_queue(self, request=None, *, name=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> None: ...
121
def purge_queue(self, request=None, *, name=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Queue: ...
122
def pause_queue(self, request=None, *, name=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Queue: ...
123
def resume_queue(self, request=None, *, name=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Queue: ...
124
```
125

126
[Queue Management](./queue-management.md)
127

128
### Task Management
129

130
Task lifecycle operations for creating, monitoring, and executing distributed work units. Tasks can target HTTP endpoints or App Engine applications with configurable scheduling, authentication, and retry behavior.
131

132
```python { .api }
133
def list_tasks(self, request=None, *, parent=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> ListTasksPager: ...
134
def get_task(self, request=None, *, name=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Task: ...
135
def create_task(self, request=None, *, parent=None, task=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Task: ...
136
def delete_task(self, request=None, *, name=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> None: ...
137
def run_task(self, request=None, *, name=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Task: ...
138
```
139

140
[Task Management](./task-management.md)
141

142
### Queue Configuration
143

144
Advanced queue configuration options including rate limiting, retry policies, App Engine routing, and logging settings for fine-tuned task processing behavior.
145

146
```python { .api }
147
class Queue:
148
    name: str
149
    app_engine_routing_override: AppEngineRouting
150
    rate_limits: RateLimits
151
    retry_config: RetryConfig
152
    state: Queue.State
153
    purge_time: Timestamp
154
    stackdriver_logging_config: StackdriverLoggingConfig
155

156
class RateLimits:
157
    max_dispatches_per_second: float
158
    max_burst_size: int
159
    max_concurrent_dispatches: int
160

161
class RetryConfig:
162
    max_attempts: int
163
    max_retry_duration: Duration
164
    min_backoff: Duration
165
    max_backoff: Duration
166
    max_doublings: int
167
```
168

169
[Queue Configuration](./queue-configuration.md)
170

171
### Task Targeting
172

173
Task target configuration for HTTP endpoints and App Engine applications, including authentication, routing, and request formatting options.
174

175
```python { .api }
176
class HttpRequest:
177
    url: str
178
    http_method: HttpMethod
179
    headers: MutableMapping[str, str]
180
    body: bytes
181
    oauth_token: OAuthToken  # mutually exclusive with oidc_token
182
    oidc_token: OidcToken    # mutually exclusive with oauth_token
183

184
class AppEngineHttpRequest:
185
    http_method: HttpMethod
186
    app_engine_routing: AppEngineRouting
187
    relative_uri: str
188
    headers: MutableMapping[str, str]
189
    body: bytes
190

191
class AppEngineRouting:
192
    service: str
193
    version: str
194
    instance: str
195
    host: str
196
```
197

198
[Task Targeting](./task-targeting.md)
199

200
### IAM and Security
201

202
Identity and Access Management integration for queue-level access control, including policy management and permission testing for secure task queue operations.
203

204
```python { .api }
205
def get_iam_policy(self, request=None, *, resource=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Policy: ...
206
def set_iam_policy(self, request=None, *, resource=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Policy: ...
207
def test_iam_permissions(self, request=None, *, resource=None, permissions=None, retry=DEFAULT, timeout=DEFAULT, metadata=()): ...
208
```
209

210
[IAM and Security](./iam-security.md)
211

212
### Location Management
213

214
Service location discovery and information retrieval for managing Google Cloud Tasks across different geographic regions.
215

216
```python { .api }
217
def get_location(self, request=None, *, name=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> Location: ...
218
def list_locations(self, request=None, *, name=None, retry=DEFAULT, timeout=DEFAULT, metadata=()) -> ListLocationsResponse: ...
219
```
220

221
### Path Utilities
222

223
Resource path construction and parsing utilities for building proper resource names and extracting components from resource paths.
224

225
```python { .api }
226
@staticmethod
227
def queue_path(project: str, location: str, queue: str) -> str: ...
228
@staticmethod  
229
def task_path(project: str, location: str, queue: str, task: str) -> str: ...
230
@staticmethod
231
def common_location_path(project: str, location: str) -> str: ...
232
@staticmethod
233
def common_project_path(project: str) -> str: ...
234
@staticmethod
235
def parse_queue_path(path: str) -> Dict[str, str]: ...
236
@staticmethod
237
def parse_task_path(path: str) -> Dict[str, str]: ...
238
@staticmethod
239
def parse_common_location_path(path: str) -> Dict[str, str]: ...
240
```
241

242
Usage example:
243
```python
244
# Build resource paths
245
queue_path = client.queue_path('my-project', 'us-central1', 'my-queue')
246
task_path = client.task_path('my-project', 'us-central1', 'my-queue', 'task-123')
247

248
# Parse resource paths
249
components = client.parse_queue_path(queue_path)
250
# Returns: {'project': 'my-project', 'location': 'us-central1', 'queue': 'my-queue'}
251
```
252

253
### Client Properties
254

255
Advanced client configuration and introspection capabilities for transport management and endpoint configuration.
256

257
```python { .api }
258
@property
259
def transport(self) -> CloudTasksTransport: ...
260
@property  
261
def api_endpoint(self) -> str: ...
262
@property
263
def universe_domain(self) -> str: ...
264
```
265

266
## Common Types
267

268
### HttpMethod
269
```python { .api }
270
class HttpMethod:
271
    HTTP_METHOD_UNSPECIFIED = 0
272
    POST = 1
273
    GET = 2
274
    HEAD = 3
275
    PUT = 4
276
    DELETE = 5
277
    PATCH = 6
278
    OPTIONS = 7
279
```
280

281
### Authentication Types
282
```python { .api }
283
class OAuthToken:
284
    service_account_email: str
285
    scope: str
286

287
class OidcToken:
288
    service_account_email: str
289
    audience: str
290
```
291

292
### Task and Attempt Types
293
```python { .api }
294
class Task:
295
    name: str
296
    app_engine_http_request: AppEngineHttpRequest  # mutually exclusive with http_request
297
    http_request: HttpRequest                      # mutually exclusive with app_engine_http_request
298
    schedule_time: Timestamp
299
    create_time: Timestamp
300
    dispatch_deadline: Duration
301
    dispatch_count: int
302
    response_count: int
303
    first_attempt: Attempt
304
    last_attempt: Attempt
305
    view: Task.View
306

307
class Attempt:
308
    schedule_time: Timestamp
309
    dispatch_time: Timestamp
310
    response_time: Timestamp
311
    response_status: Status
312
```
313

314
### Additional Types
315

316
```python { .api }
317
class StackdriverLoggingConfig:
318
    sampling_ratio: float
319
```
320

321
### Enums
322

323
```python { .api }
324
class Queue.State:
325
    STATE_UNSPECIFIED = 0
326
    RUNNING = 1
327
    PAUSED = 2
328
    DISABLED = 3
329

330
class Task.View:
331
    VIEW_UNSPECIFIED = 0
332
    BASIC = 1
333
    FULL = 2
334
```