transfer_jobs

Creates, updates, deletes, gets or lists a transfer_jobs resource.

Overview

Name	transfer_jobs
Type	Resource
Id	google.storagetransfer.transfer_jobs

Fields

The following fields are returned by SELECT queries:

get

Successful response

Name	Datatype	Description
name	string	A unique name (within the transfer project) assigned when the job is created. If this field is empty in a CreateTransferJobRequest, Storage Transfer Service assigns a unique name. Otherwise, the specified name is used as the unique name for this job. If the specified name is in use by a job, the creation request fails with an ALREADY_EXISTS error. This name must start with "transferJobs/" prefix and end with a letter or a number, and should be no more than 128 characters. For transfers involving PosixFilesystem, this name must start with transferJobs/OPI specifically. For all other transfer types, this name must not start with transferJobs/OPI. Non-PosixFilesystem example: "transferJobs/^(?!OPI)[A-Za-z0-9-._~]*[A-Za-z0-9]$" PosixFilesystem example: "transferJobs/OPI^[A-Za-z0-9-._~]*[A-Za-z0-9]$" Applications must not rely on the enforcement of naming requirements involving OPI. Invalid job names fail with an INVALID_ARGUMENT error.
creationTime	string (google-datetime)	Output only. The time that the transfer job was created.
deletionTime	string (google-datetime)	Output only. The time that the transfer job was deleted.
description	string	A description provided by the user for the job. Its max length is 1024 bytes when Unicode-encoded.
eventStream	object	Specifies the event stream for the transfer job for event-driven transfers. When EventStream is specified, the Schedule fields are ignored. (id: EventStream)
lastModificationTime	string (google-datetime)	Output only. The time that the transfer job was last modified.
latestOperationName	string	The name of the most recently started TransferOperation of this JobConfig. Present if a TransferOperation has been created for this JobConfig.
loggingConfig	object	Logging configuration. (id: LoggingConfig)
notificationConfig	object	Notification configuration. (id: NotificationConfig)
projectId	string	The ID of the Google Cloud project that owns the job.
replicationSpec	object	Replication specification. (id: ReplicationSpec)
schedule	object	Specifies schedule for the transfer job. This is an optional field. When the field is not set, the job never executes a transfer, unless you invoke RunTransferJob or update the job to have a non-empty schedule. (id: Schedule)
serviceAccount	string	Optional. The user-managed service account to which to delegate service agent permissions. You can grant Cloud Storage bucket permissions to this service account instead of to the Transfer Service service agent. Format is projects/-/serviceAccounts/ACCOUNT_EMAIL_OR_UNIQUEID Either the service account email (SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com) or the unique ID (123456789012345678901) are accepted in the string. The - wildcard character is required; replacing it with a project ID is invalid. See https://cloud.google.com//storage-transfer/docs/delegate-service-agent-permissions for required permissions.
status	string	Status of the job. This value MUST be specified for CreateTransferJobRequests. Note: The effect of the new job status takes place during a subsequent job run. For example, if you change the job status from ENABLED to DISABLED, and an operation spawned by the transfer is running, the status change would not affect the current operation.
transferSpec	object	Transfer specification. (id: TransferSpec)

list

Successful response

Name	Datatype	Description
name	string	A unique name (within the transfer project) assigned when the job is created. If this field is empty in a CreateTransferJobRequest, Storage Transfer Service assigns a unique name. Otherwise, the specified name is used as the unique name for this job. If the specified name is in use by a job, the creation request fails with an ALREADY_EXISTS error. This name must start with "transferJobs/" prefix and end with a letter or a number, and should be no more than 128 characters. For transfers involving PosixFilesystem, this name must start with transferJobs/OPI specifically. For all other transfer types, this name must not start with transferJobs/OPI. Non-PosixFilesystem example: "transferJobs/^(?!OPI)[A-Za-z0-9-._~]*[A-Za-z0-9]$" PosixFilesystem example: "transferJobs/OPI^[A-Za-z0-9-._~]*[A-Za-z0-9]$" Applications must not rely on the enforcement of naming requirements involving OPI. Invalid job names fail with an INVALID_ARGUMENT error.
creationTime	string (google-datetime)	Output only. The time that the transfer job was created.
deletionTime	string (google-datetime)	Output only. The time that the transfer job was deleted.
description	string	A description provided by the user for the job. Its max length is 1024 bytes when Unicode-encoded.
eventStream	object	Specifies the event stream for the transfer job for event-driven transfers. When EventStream is specified, the Schedule fields are ignored. (id: EventStream)
lastModificationTime	string (google-datetime)	Output only. The time that the transfer job was last modified.
latestOperationName	string	The name of the most recently started TransferOperation of this JobConfig. Present if a TransferOperation has been created for this JobConfig.
loggingConfig	object	Logging configuration. (id: LoggingConfig)
notificationConfig	object	Notification configuration. (id: NotificationConfig)
projectId	string	The ID of the Google Cloud project that owns the job.
replicationSpec	object	Replication specification. (id: ReplicationSpec)
schedule	object	Specifies schedule for the transfer job. This is an optional field. When the field is not set, the job never executes a transfer, unless you invoke RunTransferJob or update the job to have a non-empty schedule. (id: Schedule)
serviceAccount	string	Optional. The user-managed service account to which to delegate service agent permissions. You can grant Cloud Storage bucket permissions to this service account instead of to the Transfer Service service agent. Format is projects/-/serviceAccounts/ACCOUNT_EMAIL_OR_UNIQUEID Either the service account email (SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com) or the unique ID (123456789012345678901) are accepted in the string. The - wildcard character is required; replacing it with a project ID is invalid. See https://cloud.google.com//storage-transfer/docs/delegate-service-agent-permissions for required permissions.
status	string	Status of the job. This value MUST be specified for CreateTransferJobRequests. Note: The effect of the new job status takes place during a subsequent job run. For example, if you change the job status from ENABLED to DISABLED, and an operation spawned by the transfer is running, the status change would not affect the current operation.
transferSpec	object	Transfer specification. (id: TransferSpec)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	transferJobsId, projectId		Gets a transfer job.
list	select	filter	pageSize, pageToken	Lists transfer jobs.
create	insert			Creates a transfer job that runs periodically.
patch	update	transferJobsId		Updates a transfer job. Updating a job's transfer spec does not affect transfer operations that are running already. Note: The job's status field can be modified using this RPC (for example, to set a job's status to DELETED, DISABLED, or ENABLED).
delete	delete	transferJobsId, projectId		Deletes a transfer job. Deleting a transfer job sets its status to DELETED.
run	exec	transferJobsId		Starts a new operation for the specified transfer job. A TransferJob has a maximum of one active TransferOperation. If this method is called while a TransferOperation is active, an error is returned.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
filter	string
projectId	string
transferJobsId	string
pageSize	integer (int32)
pageToken	string

SELECT examples

get

Gets a transfer job.

SELECT
name,
creationTime,
deletionTime,
description,
eventStream,
lastModificationTime,
latestOperationName,
loggingConfig,
notificationConfig,
projectId,
replicationSpec,
schedule,
serviceAccount,
status,
transferSpec
FROM google.storagetransfer.transfer_jobs
WHERE transferJobsId = '{{ transferJobsId }}' -- required
AND projectId = '{{ projectId }}' -- required;

list

Lists transfer jobs.

SELECT
name,
creationTime,
deletionTime,
description,
eventStream,
lastModificationTime,
latestOperationName,
loggingConfig,
notificationConfig,
projectId,
replicationSpec,
schedule,
serviceAccount,
status,
transferSpec
FROM google.storagetransfer.transfer_jobs
WHERE filter = '{{ filter }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}';

INSERT examples

create

Creates a transfer job that runs periodically.

INSERT INTO google.storagetransfer.transfer_jobs (
data__name,
data__description,
data__projectId,
data__serviceAccount,
data__transferSpec,
data__replicationSpec,
data__notificationConfig,
data__loggingConfig,
data__schedule,
data__eventStream,
data__status,
data__latestOperationName
)
SELECT 
'{{ name }}',
'{{ description }}',
'{{ projectId }}',
'{{ serviceAccount }}',
'{{ transferSpec }}',
'{{ replicationSpec }}',
'{{ notificationConfig }}',
'{{ loggingConfig }}',
'{{ schedule }}',
'{{ eventStream }}',
'{{ status }}',
'{{ latestOperationName }}'
RETURNING
name,
creationTime,
deletionTime,
description,
eventStream,
lastModificationTime,
latestOperationName,
loggingConfig,
notificationConfig,
projectId,
replicationSpec,
schedule,
serviceAccount,
status,
transferSpec
;

Manifest

# Description fields are for documentation purposes
- name: transfer_jobs
  props:
    - name: name
      value: string
      description: >
        A unique name (within the transfer project) assigned when the job is created. If this field is empty in a CreateTransferJobRequest, Storage Transfer Service assigns a unique name. Otherwise, the specified name is used as the unique name for this job. If the specified name is in use by a job, the creation request fails with an ALREADY_EXISTS error. This name must start with `"transferJobs/"` prefix and end with a letter or a number, and should be no more than 128 characters. For transfers involving PosixFilesystem, this name must start with `transferJobs/OPI` specifically. For all other transfer types, this name must not start with `transferJobs/OPI`. Non-PosixFilesystem example: `"transferJobs/^(?!OPI)[A-Za-z0-9-._~]*[A-Za-z0-9]$"` PosixFilesystem example: `"transferJobs/OPI^[A-Za-z0-9-._~]*[A-Za-z0-9]$"` Applications must not rely on the enforcement of naming requirements involving OPI. Invalid job names fail with an INVALID_ARGUMENT error.
        
    - name: description
      value: string
      description: >
        A description provided by the user for the job. Its max length is 1024 bytes when Unicode-encoded.
        
    - name: projectId
      value: string
      description: >
        The ID of the Google Cloud project that owns the job.
        
    - name: serviceAccount
      value: string
      description: >
        Optional. The user-managed service account to which to delegate service agent permissions. You can grant Cloud Storage bucket permissions to this service account instead of to the Transfer Service service agent. Format is `projects/-/serviceAccounts/ACCOUNT_EMAIL_OR_UNIQUEID` Either the service account email (`SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com`) or the unique ID (`123456789012345678901`) are accepted in the string. The `-` wildcard character is required; replacing it with a project ID is invalid. See https://cloud.google.com//storage-transfer/docs/delegate-service-agent-permissions for required permissions.
        
    - name: transferSpec
      value: object
      description: >
        Transfer specification.
        
    - name: replicationSpec
      value: object
      description: >
        Replication specification.
        
    - name: notificationConfig
      value: object
      description: >
        Notification configuration.
        
    - name: loggingConfig
      value: object
      description: >
        Logging configuration.
        
    - name: schedule
      value: object
      description: >
        Specifies schedule for the transfer job. This is an optional field. When the field is not set, the job never executes a transfer, unless you invoke RunTransferJob or update the job to have a non-empty schedule.
        
    - name: eventStream
      value: object
      description: >
        Specifies the event stream for the transfer job for event-driven transfers. When EventStream is specified, the Schedule fields are ignored.
        
    - name: status
      value: string
      description: >
        Status of the job. This value MUST be specified for `CreateTransferJobRequests`. **Note:** The effect of the new job status takes place during a subsequent job run. For example, if you change the job status from ENABLED to DISABLED, and an operation spawned by the transfer is running, the status change would not affect the current operation.
        
      valid_values: ['STATUS_UNSPECIFIED', 'ENABLED', 'DISABLED', 'DELETED']
    - name: latestOperationName
      value: string
      description: >
        The name of the most recently started TransferOperation of this JobConfig. Present if a TransferOperation has been created for this JobConfig.
        

UPDATE examples

patch

Updates a transfer job. Updating a job's transfer spec does not affect transfer operations that are running already. Note: The job's status field can be modified using this RPC (for example, to set a job's status to DELETED, DISABLED, or ENABLED).

UPDATE google.storagetransfer.transfer_jobs
SET 
data__projectId = '{{ projectId }}',
data__transferJob = '{{ transferJob }}',
data__updateTransferJobFieldMask = '{{ updateTransferJobFieldMask }}'
WHERE 
transferJobsId = '{{ transferJobsId }}' --required
RETURNING
name,
creationTime,
deletionTime,
description,
eventStream,
lastModificationTime,
latestOperationName,
loggingConfig,
notificationConfig,
projectId,
replicationSpec,
schedule,
serviceAccount,
status,
transferSpec;

DELETE examples

delete

Deletes a transfer job. Deleting a transfer job sets its status to DELETED.

DELETE FROM google.storagetransfer.transfer_jobs
WHERE transferJobsId = '{{ transferJobsId }}' --required
AND projectId = '{{ projectId }}' --required;

Lifecycle Methods

run

Starts a new operation for the specified transfer job. A TransferJob has a maximum of one active TransferOperation. If this method is called while a TransferOperation is active, an error is returned.

EXEC google.storagetransfer.transfer_jobs.run 
@transferJobsId='{{ transferJobsId }}' --required 
@@json=
'{
"projectId": "{{ projectId }}"
}';