0
# Task Targeting
1

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

4
## Capabilities
5

6
### HTTP Request Targeting
7

8
Configure tasks to make HTTP requests to external endpoints with full control over method, headers, body, and authentication.
9

10
```python { .api }
11
class HttpRequest:
12
    url: str  # Required full URL path for request
13
    http_method: HttpMethod  # HTTP method to use (default POST)
14
    headers: MutableMapping[str, str]  # HTTP request headers
15
    body: bytes  # HTTP request body (allowed only for POST/PUT/PATCH)
16
    oauth_token: OAuthToken  # OAuth token for authorization (oneof authorization_header)
17
    oidc_token: OidcToken  # OIDC token for authorization (oneof authorization_header)
18
```
19

20
### App Engine Request Targeting
21

22
Configure tasks to call App Engine applications with service/version routing and relative URI paths.
23

24
```python { .api }
25
class AppEngineHttpRequest:
26
    http_method: HttpMethod  # HTTP method to use (default POST)
27
    app_engine_routing: AppEngineRouting  # Task-level App Engine routing settings
28
    relative_uri: str  # Relative URI (must begin with "/")
29
    headers: MutableMapping[str, str]  # HTTP request headers
30
    body: bytes  # HTTP request body (allowed only for POST/PUT)
31
```
32

33
### App Engine Routing
34

35
Control which App Engine service, version, and instance processes the task.
36

37
```python { .api }
38
class AppEngineRouting:
39
    service: str  # App service (default service if not specified)
40
    version: str  # App version (default version if not specified)
41
    instance: str  # App instance (available instance if not specified)
42
    host: str  # Output only host that task is sent to
43
```
44

45
### OAuth Authentication
46

47
Configure OAuth tokens for authenticating requests to Google Cloud APIs and services.
48

49
```python { .api }
50
class OAuthToken:
51
    service_account_email: str  # Service account email for generating OAuth token
52
    scope: str  # OAuth scope (default "https://www.googleapis.com/auth/cloud-platform")
53
```
54

55
### OIDC Authentication
56

57
Configure OpenID Connect tokens for authenticating requests to any HTTP endpoint.
58

59
```python { .api }
60
class OidcToken:
61
    service_account_email: str  # Service account email for generating OIDC token
62
    audience: str  # Audience for OIDC token (uses target URI if not specified)
63
```
64

65
### HTTP Methods
66

67
Supported HTTP methods for task requests.
68

69
```python { .api }
70
class HttpMethod:
71
    HTTP_METHOD_UNSPECIFIED = 0  # HTTP method unspecified
72
    POST = 1  # HTTP POST
73
    GET = 2  # HTTP GET
74
    HEAD = 3  # HTTP HEAD
75
    PUT = 4  # HTTP PUT
76
    DELETE = 5  # HTTP DELETE
77
    PATCH = 6  # HTTP PATCH
78
    OPTIONS = 7  # HTTP OPTIONS
79
```
80

81
## Usage Examples
82

83
### Basic HTTP Tasks
84

85
```python
86
from google.cloud import tasks
87
import json
88

89
client = tasks.CloudTasksClient()
90
queue_path = client.queue_path('my-project-id', 'us-central1', 'http-queue')
91

92
# Simple POST request
93
simple_task = tasks.Task(
94
    http_request=tasks.HttpRequest(
95
        url='https://api.example.com/webhook',
96
        http_method=tasks.HttpMethod.POST,
97
        body=b'{"event": "task_executed"}'
98
    )
99
)
100

101
# GET request with query parameters (include in URL)
102
get_task = tasks.Task(
103
    http_request=tasks.HttpRequest(
104
        url='https://api.example.com/status?check=health',
105
        http_method=tasks.HttpMethod.GET
106
    )
107
)
108

109
# Create both tasks
110
client.create_task(parent=queue_path, task=simple_task)
111
client.create_task(parent=queue_path, task=get_task)
112
```
113

114
### HTTP Tasks with Headers and JSON Payload
115

116
```python
117
from google.cloud import tasks
118
import json
119

120
client = tasks.CloudTasksClient()
121
queue_path = client.queue_path('my-project-id', 'us-central1', 'api-queue')
122

123
# Structured JSON payload with custom headers
124
payload = {
125
    'user_id': 12345,
126
    'action': 'process_order',
127
    'metadata': {
128
        'priority': 'high',
129
        'source': 'cloud_tasks'
130
    }
131
}
132

133
task = tasks.Task(
134
    http_request=tasks.HttpRequest(
135
        url='https://myapp.com/api/process',
136
        http_method=tasks.HttpMethod.POST,
137
        headers={
138
            'Content-Type': 'application/json',
139
            'X-Custom-Header': 'task-processing',
140
            'Authorization': 'Bearer api-key-123'  # Static auth (not recommended for production)
141
        },
142
        body=json.dumps(payload).encode('utf-8')
143
    )
144
)
145

146
created_task = client.create_task(parent=queue_path, task=task)
147
print(f'Created API task: {created_task.name}')
148
```
149

150
### Authenticated HTTP Tasks with OAuth
151

152
```python
153
from google.cloud import tasks
154

155
client = tasks.CloudTasksClient()
156
queue_path = client.queue_path('my-project-id', 'us-central1', 'secure-queue')
157

158
# OAuth-authenticated request to Google Cloud API
159
oauth_task = tasks.Task(
160
    http_request=tasks.HttpRequest(
161
        url='https://cloudfunctions.googleapis.com/v1/projects/my-project/locations/us-central1/functions/processor:call',
162
        http_method=tasks.HttpMethod.POST,
163
        oauth_token=tasks.OAuthToken(
164
            service_account_email='task-runner@my-project.iam.gserviceaccount.com',
165
            scope='https://www.googleapis.com/auth/cloud-platform'
166
        ),
167
        headers={'Content-Type': 'application/json'},
168
        body=b'{"data": "secure_operation"}'
169
    )
170
)
171

172
created_task = client.create_task(parent=queue_path, task=oauth_task)
173
print(f'Created OAuth task: {created_task.name}')
174
```
175

176
### Authenticated HTTP Tasks with OIDC
177

178
```python
179
from google.cloud import tasks
180

181
client = tasks.CloudTasksClient()
182
queue_path = client.queue_path('my-project-id', 'us-central1', 'oidc-queue')
183

184
# OIDC-authenticated request to custom endpoint
185
oidc_task = tasks.Task(
186
    http_request=tasks.HttpRequest(
187
        url='https://secure-api.mycompany.com/process',
188
        http_method=tasks.HttpMethod.POST,
189
        oidc_token=tasks.OidcToken(
190
            service_account_email='task-runner@my-project.iam.gserviceaccount.com',
191
            audience='https://secure-api.mycompany.com'
192
        ),
193
        headers={'Content-Type': 'application/json'},
194
        body=b'{"secure": "data"}'
195
    )
196
)
197

198
created_task = client.create_task(parent=queue_path, task=oidc_task)
199
print(f'Created OIDC task: {created_task.name}')
200
```
201

202
### App Engine Tasks
203

204
```python
205
from google.cloud import tasks
206

207
client = tasks.CloudTasksClient()
208
queue_path = client.queue_path('my-project-id', 'us-central1', 'appengine-queue')
209

210
# Basic App Engine task
211
basic_ae_task = tasks.Task(
212
    app_engine_http_request=tasks.AppEngineHttpRequest(
213
        http_method=tasks.HttpMethod.POST,
214
        relative_uri='/tasks/process',
215
        body=b'{"task": "basic_processing"}'
216
    )
217
)
218

219
# App Engine task with specific routing
220
routed_ae_task = tasks.Task(
221
    app_engine_http_request=tasks.AppEngineHttpRequest(
222
        http_method=tasks.HttpMethod.POST,
223
        relative_uri='/api/heavy-computation',
224
        app_engine_routing=tasks.AppEngineRouting(
225
            service='worker-service',
226
            version='v2'
227
        ),
228
        headers={'Content-Type': 'application/json'},
229
        body=b'{"computation": "complex_algorithm"}'
230
    )
231
)
232

233
# Create both tasks
234
client.create_task(parent=queue_path, task=basic_ae_task)
235
client.create_task(parent=queue_path, task=routed_ae_task)
236
```
237

238
### App Engine Tasks with Custom Headers
239

240
```python
241
from google.cloud import tasks
242
import json
243

244
client = tasks.CloudTasksClient()
245
queue_path = client.queue_path('my-project-id', 'us-central1', 'ae-custom-queue')
246

247
# App Engine task with custom headers and routing
248
task_data = {
249
    'batch_id': 'batch_001',
250
    'items': ['item1', 'item2', 'item3']
251
}
252

253
custom_ae_task = tasks.Task(
254
    app_engine_http_request=tasks.AppEngineHttpRequest(
255
        http_method=tasks.HttpMethod.POST,
256
        relative_uri='/batch/process',
257
        app_engine_routing=tasks.AppEngineRouting(
258
            service='batch-processor',
259
            version='stable',
260
            instance='instance-1'  # Target specific instance
261
        ),
262
        headers={
263
            'Content-Type': 'application/json',
264
            'X-Batch-Priority': 'high',
265
            'X-Processing-Mode': 'parallel'
266
        },
267
        body=json.dumps(task_data).encode('utf-8')
268
    )
269
)
270

271
created_task = client.create_task(parent=queue_path, task=custom_ae_task)
272
print(f'Created custom App Engine task: {created_task.name}')
273
```
274

275
### Multi-Method HTTP Task Examples
276

277
```python
278
from google.cloud import tasks
279

280
client = tasks.CloudTasksClient()
281
queue_path = client.queue_path('my-project-id', 'us-central1', 'multi-method-queue')
282

283
# PUT request for resource updates
284
put_task = tasks.Task(
285
    http_request=tasks.HttpRequest(
286
        url='https://api.example.com/resources/123',
287
        http_method=tasks.HttpMethod.PUT,
288
        headers={'Content-Type': 'application/json'},
289
        body=b'{"status": "updated", "timestamp": "2023-01-01T00:00:00Z"}'
290
    )
291
)
292

293
# DELETE request for cleanup
294
delete_task = tasks.Task(
295
    http_request=tasks.HttpRequest(
296
        url='https://api.example.com/temp-resources/temp-123',
297
        http_method=tasks.HttpMethod.DELETE,
298
        headers={'Authorization': 'Bearer cleanup-token'}
299
    )
300
)
301

302
# PATCH request for partial updates
303
patch_task = tasks.Task(
304
    http_request=tasks.HttpRequest(
305
        url='https://api.example.com/users/456',
306
        http_method=tasks.HttpMethod.PATCH,
307
        headers={'Content-Type': 'application/json'},
308
        body=b'{"last_login": "2023-01-01T12:00:00Z"}'
309
    )
310
)
311

312
# Create all tasks
313
client.create_task(parent=queue_path, task=put_task)
314
client.create_task(parent=queue_path, task=delete_task)
315
client.create_task(parent=queue_path, task=patch_task)
316
```
317

318
### Error Handling and Retry Considerations
319

320
```python
321
from google.cloud import tasks
322
from google.protobuf import duration_pb2
323

324
client = tasks.CloudTasksClient()
325
queue_path = client.queue_path('my-project-id', 'us-central1', 'resilient-queue')
326

327
# Task with custom dispatch deadline
328
resilient_task = tasks.Task(
329
    http_request=tasks.HttpRequest(
330
        url='https://slow-api.example.com/process',
331
        http_method=tasks.HttpMethod.POST,
332
        body=b'{"data": "long_running_operation"}'
333
    ),
334
    dispatch_deadline=duration_pb2.Duration(seconds=300)  # 5 minute timeout
335
)
336

337
created_task = client.create_task(parent=queue_path, task=resilient_task)
338
print(f'Created resilient task with 5min timeout: {created_task.name}')
339

340
# The queue's retry configuration will handle retries automatically
341
# if the endpoint returns 5xx errors or times out
342
```