0
# Transfer Run Management
1

2
Management and monitoring of individual transfer executions, including manual execution, status monitoring, log retrieval, and run lifecycle operations.
3

4
## Capabilities
5

6
### Get Transfer Run
7

8
Returns information about the particular transfer run.
9

10
```python { .api }
11
def get_transfer_run(
12
    self,
13
    request: Optional[Union[GetTransferRunRequest, dict]] = None,
14
    *,
15
    name: Optional[str] = None,
16
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
17
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
18
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
19
) -> TransferRun:
20
    """
21
    Returns information about the particular transfer run.
22

23
    Args:
24
        request: The request object containing run name.
25
        name: Required. The field will contain name of the resource requested.
26
        retry: Designation of what errors should be retried.
27
        timeout: The timeout for this request.
28
        metadata: Strings which should be sent along with the request.
29

30
    Returns:
31
        TransferRun: The requested transfer run.
32
    """
33
```
34

35
### Delete Transfer Run
36

37
Deletes the specified transfer run.
38

39
```python { .api }
40
def delete_transfer_run(
41
    self,
42
    request: Optional[Union[DeleteTransferRunRequest, dict]] = None,
43
    *,
44
    name: Optional[str] = None,
45
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
46
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
47
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
48
) -> None:
49
    """
50
    Deletes the specified transfer run.
51

52
    Args:
53
        request: The request object containing run name.
54
        name: Required. The field will contain name of the resource requested.
55
        retry: Designation of what errors should be retried.
56
        timeout: The timeout for this request.
57
        metadata: Strings which should be sent along with the request.
58
    """
59
```
60

61
### List Transfer Runs
62

63
Returns information about running and completed transfer runs.
64

65
```python { .api }
66
def list_transfer_runs(
67
    self,
68
    request: Optional[Union[ListTransferRunsRequest, dict]] = None,
69
    *,
70
    parent: Optional[str] = None,
71
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
72
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
73
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
74
) -> pagers.ListTransferRunsPager:
75
    """
76
    Returns information about running and completed transfer runs.
77

78
    Args:
79
        request: The request object containing parent transfer config.
80
        parent: Required. Name of transfer configuration for which transfer runs should be retrieved.
81
        retry: Designation of what errors should be retried.
82
        timeout: The timeout for this request.
83
        metadata: Strings which should be sent along with the request.
84

85
    Returns:
86
        ListTransferRunsResponse: The list of transfer runs.
87
    """
88
```
89

90
### Start Manual Transfer Runs
91

92
Start manual transfer runs to be executed now with schedule_time equal to current time.
93

94
```python { .api }
95
def start_manual_transfer_runs(
96
    self,
97
    request: Optional[Union[StartManualTransferRunsRequest, dict]] = None,
98
    *,
99
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
100
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
101
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
102
) -> StartManualTransferRunsResponse:
103
    """
104
    Start manual transfer runs to be executed now with schedule_time equal to current time.
105

106
    Args:
107
        request: The request object containing manual run parameters.
108
        retry: Designation of what errors should be retried.
109
        timeout: The timeout for this request.
110
        metadata: Strings which should be sent along with the request.
111

112
    Returns:
113
        StartManualTransferRunsResponse: The response containing created runs.
114
    """
115
```
116

117
### Schedule Transfer Runs
118

119
Creates transfer runs for a time range.
120

121
```python { .api }
122
def schedule_transfer_runs(
123
    self,
124
    request: Optional[Union[ScheduleTransferRunsRequest, dict]] = None,
125
    *,
126
    parent: Optional[str] = None,
127
    start_time: Optional[timestamp_pb2.Timestamp] = None,
128
    end_time: Optional[timestamp_pb2.Timestamp] = None,
129
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
130
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
131
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
132
) -> ScheduleTransferRunsResponse:
133
    """
134
    Creates transfer runs for a time range.
135

136
    Args:
137
        request: The request object containing schedule parameters.
138
        parent: Required. Transfer configuration name.
139
        start_time: Required. Start time of the range of transfer runs.
140
        end_time: Required. End time of the range of transfer runs.
141
        retry: Designation of what errors should be retried.
142
        timeout: The timeout for this request.
143
        metadata: Strings which should be sent along with the request.
144

145
    Returns:
146
        ScheduleTransferRunsResponse: The response containing scheduled runs.
147
    """
148
```
149

150
### List Transfer Logs
151

152
Returns log messages for the transfer run.
153

154
```python { .api }
155
def list_transfer_logs(
156
    self,
157
    request: Optional[Union[ListTransferLogsRequest, dict]] = None,
158
    *,
159
    parent: Optional[str] = None,
160
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
161
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
162
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
163
) -> pagers.ListTransferLogsPager:
164
    """
165
    Returns user facing log messages for the data transfer run.
166

167
    Args:
168
        request: The request object containing run name.
169
        parent: Required. Transfer run name.
170
        retry: Designation of what errors should be retried.
171
        timeout: The timeout for this request.
172
        metadata: Strings which should be sent along with the request.
173

174
    Returns:
175
        ListTransferLogsResponse: The list of transfer log messages.
176
    """
177
```
178

179
## Request Types
180

181
```python { .api }
182
class GetTransferRunRequest:
183
    """
184
    A request to get information about a transfer run.
185
    
186
    Attributes:
187
        name (str): Required. The field will contain name of the resource requested.
188
                   Format: projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}/runs/{run_id}
189
    """
190
    name: str
191

192
class DeleteTransferRunRequest:
193
    """
194
    A request to delete a transfer run.
195
    
196
    Attributes:
197
        name (str): Required. The field will contain name of the resource requested.
198
                   Format: projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}/runs/{run_id}
199
    """
200
    name: str
201

202
class ListTransferRunsRequest:
203
    """
204
    A request message for ListTransferRuns.
205
    
206
    Attributes:
207
        parent (str): Required. Name of transfer configuration for which transfer runs should be retrieved.
208
                     Format: projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}
209
        states (Sequence[TransferState]): When specified, only transfer runs with requested states are returned.
210
        page_token (str): Pagination token.
211
        page_size (int): Page size. The default page size is the maximum value of 1000 results.
212
        run_attempt (RunAttempt): Indicates how run attempts are to be pulled.
213
    """
214
    parent: str
215
    states: Sequence[TransferState]
216
    page_token: str
217
    page_size: int
218
    run_attempt: RunAttempt
219

220
    class RunAttempt(proto.Enum):
221
        """Represents which runs should be pulled."""
222
        RUN_ATTEMPT_UNSPECIFIED = 0
223
        LATEST = 1
224
```
225

226
```python { .api }
227
class StartManualTransferRunsRequest:
228
    """
229
    A request to start manual transfer runs.
230
    
231
    Attributes:
232
        parent (str): Required. Transfer configuration name.
233
                     Format: projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}
234
        requested_time_range (TimeRange): The requested time range for the transfer run.
235
        requested_run_time (Timestamp): The requested run time for the transfer run.
236
    """
237
    parent: str
238
    requested_time_range: TimeRange
239
    requested_run_time: timestamp_pb2.Timestamp
240

241
    class TimeRange(proto.Message):
242
        """
243
        A specification for a time range for transfer runs.
244
        
245
        Attributes:
246
            start_time (Timestamp): Start time of the range of transfer runs.
247
            end_time (Timestamp): End time of the range of transfer runs.
248
        """
249
        start_time: timestamp_pb2.Timestamp
250
        end_time: timestamp_pb2.Timestamp
251
```
252

253
```python { .api }
254
class ScheduleTransferRunsRequest:
255
    """
256
    A request to schedule transfer runs for a time range.
257
    
258
    Attributes:
259
        parent (str): Required. Transfer configuration name.
260
                     Format: projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}
261
        start_time (Timestamp): Required. Start time of the range of transfer runs.
262
        end_time (Timestamp): Required. End time of the range of transfer runs.
263
    """
264
    parent: str
265
    start_time: timestamp_pb2.Timestamp
266
    end_time: timestamp_pb2.Timestamp
267

268
class ListTransferLogsRequest:
269
    """
270
    A request message for ListTransferLogs.
271
    
272
    Attributes:
273
        parent (str): Required. Transfer run name.
274
                     Format: projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}/runs/{run_id}
275
        page_token (str): Pagination token.
276
        page_size (int): Page size. The default page size is the maximum value of 1000 results.
277
        message_types (Sequence[MessageType]): Message types to return.
278
    """
279
    parent: str
280
    page_token: str
281
    page_size: int
282
    message_types: Sequence[MessageType]
283
```
284

285
## Response Types
286

287
```python { .api }
288
class ListTransferRunsResponse:
289
    """
290
    The returned list of pipelines in the project.
291
    
292
    Attributes:
293
        transfer_runs (Sequence[TransferRun]): Output only. The stored pipeline transfer runs.
294
        next_page_token (str): Output only. The next-pagination token.
295
    """
296
    transfer_runs: Sequence[TransferRun]
297
    next_page_token: str
298

299
class StartManualTransferRunsResponse:
300
    """
301
    A response to start manual transfer runs.
302
    
303
    Attributes:
304
        runs (Sequence[TransferRun]): The transfer runs that were created.
305
    """
306
    runs: Sequence[TransferRun]
307

308
class ScheduleTransferRunsResponse:
309
    """
310
    A response to schedule transfer runs for a time range.
311
    
312
    Attributes:
313
        runs (Sequence[TransferRun]): The transfer runs that were scheduled.
314
    """
315
    runs: Sequence[TransferRun]
316

317
class ListTransferLogsResponse:
318
    """
319
    The returned list transfer run messages.
320
    
321
    Attributes:
322
        transfer_messages (Sequence[TransferMessage]): Output only. The stored pipeline transfer messages.
323
        next_page_token (str): Output only. The next-pagination token.
324
    """
325
    transfer_messages: Sequence[TransferMessage]
326
    next_page_token: str
327
```
328

329
## Usage Examples
330

331
### List Transfer Runs
332

333
```python
334
from google.cloud import bigquery_datatransfer
335

336
client = bigquery_datatransfer.DataTransferServiceClient()
337

338
# List all runs for a transfer config
339
parent = f"projects/{project_id}/locations/{location}/transferConfigs/{config_id}"
340
response = client.list_transfer_runs(parent=parent)
341

342
print("Transfer runs:")
343
for run in response:
344
    print(f"  Run ID: {run.name}")
345
    print(f"    State: {run.state}")
346
    print(f"    Schedule Time: {run.schedule_time}")
347
    print(f"    Start Time: {run.start_time}")
348
    print(f"    End Time: {run.end_time}")
349
    print(f"    Error Status: {run.error_status}")
350

351
# List runs with specific states only
352
from google.cloud.bigquery_datatransfer_v1 import TransferState
353

354
response = client.list_transfer_runs(
355
    parent=parent,
356
    states=[TransferState.FAILED, TransferState.SUCCEEDED]
357
)
358

359
print("Completed runs (success/failure):")
360
for run in response:
361
    print(f"  {run.name}: {run.state}")
362
```
363

364
### Get Transfer Run Details
365

366
```python
367
from google.cloud import bigquery_datatransfer
368

369
client = bigquery_datatransfer.DataTransferServiceClient()
370

371
# Get specific transfer run
372
run_name = f"projects/{project_id}/locations/{location}/transferConfigs/{config_id}/runs/{run_id}"
373
run = client.get_transfer_run(name=run_name)
374

375
print(f"Transfer Run: {run.name}")
376
print(f"State: {run.state}")
377
print(f"Data Source ID: {run.data_source_id}")
378
print(f"Destination Dataset ID: {run.destination_dataset_id}")
379
print(f"Schedule Time: {run.schedule_time}")
380
print(f"Start Time: {run.start_time}")
381
print(f"End Time: {run.end_time}")
382
print(f"User ID: {run.user_id}")
383

384
if run.error_status and run.error_status.code != 0:
385
    print(f"Error: {run.error_status.message}")
386
```
387

388
### Start Manual Transfer Run
389

390
```python
391
from google.cloud import bigquery_datatransfer
392
from google.protobuf import timestamp_pb2
393
import datetime
394

395
client = bigquery_datatransfer.DataTransferServiceClient()
396

397
# Start manual run with specific time
398
now = datetime.datetime.now(datetime.timezone.utc)
399
requested_time = timestamp_pb2.Timestamp()
400
requested_time.FromDatetime(now)
401

402
parent = f"projects/{project_id}/locations/{location}/transferConfigs/{config_id}"
403
request = {
404
    "parent": parent,
405
    "requested_run_time": requested_time
406
}
407

408
response = client.start_manual_transfer_runs(request=request)
409

410
print("Started manual transfer runs:")
411
for run in response.runs:
412
    print(f"  Run ID: {run.name}")
413
    print(f"  State: {run.state}")
414
    print(f"  Schedule Time: {run.schedule_time}")
415
```
416

417
### Schedule Transfer Runs for Time Range
418

419
```python
420
from google.cloud import bigquery_datatransfer
421
from google.protobuf import timestamp_pb2
422
import datetime
423

424
client = bigquery_datatransfer.DataTransferServiceClient()
425

426
# Schedule runs for a week
427
start_date = datetime.datetime(2024, 1, 1, tzinfo=datetime.timezone.utc)
428
end_date = datetime.datetime(2024, 1, 7, tzinfo=datetime.timezone.utc)
429

430
start_time = timestamp_pb2.Timestamp()
431
start_time.FromDatetime(start_date)
432

433
end_time = timestamp_pb2.Timestamp()
434
end_time.FromDatetime(end_date)
435

436
parent = f"projects/{project_id}/locations/{location}/transferConfigs/{config_id}"
437
response = client.schedule_transfer_runs(
438
    parent=parent,
439
    start_time=start_time,
440
    end_time=end_time
441
)
442

443
print(f"Scheduled {len(response.runs)} transfer runs:")
444
for run in response.runs:
445
    print(f"  Run ID: {run.name}")
446
    print(f"  Schedule Time: {run.schedule_time}")
447
```
448

449
### View Transfer Run Logs
450

451
```python
452
from google.cloud import bigquery_datatransfer
453

454
client = bigquery_datatransfer.DataTransferServiceClient()
455

456
# Get logs for a specific run
457
parent = f"projects/{project_id}/locations/{location}/transferConfigs/{config_id}/runs/{run_id}"
458
response = client.list_transfer_logs(parent=parent)
459

460
print("Transfer run logs:")
461
for message in response.transfer_messages:
462
    print(f"  [{message.message_time}] {message.severity}: {message.message_text}")
463
```
464

465
### Delete Transfer Run
466

467
```python
468
from google.cloud import bigquery_datatransfer
469

470
client = bigquery_datatransfer.DataTransferServiceClient()
471

472
# Delete specific transfer run
473
run_name = f"projects/{project_id}/locations/{location}/transferConfigs/{config_id}/runs/{run_id}"
474
client.delete_transfer_run(name=run_name)
475

476
print(f"Deleted transfer run: {run_name}")
477
```