Skip to main content

jobs

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

Overview​

Namejobs
TypeResource
Idgoogle.cloudscheduler.jobs

Fields​

The following fields are returned by SELECT queries:

Successful response

NameDatatypeDescription
namestringOptionally caller-specified in CreateJob, after which it becomes output only. The job name. For example: projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID. * PROJECT_ID can contain letters ([A-Za-z]), numbers ([0-9]), hyphens (-), colons (:), or periods (.). For more information, see Identifying projects * LOCATION_ID is the canonical ID for the job's location. The list of available locations can be obtained by calling ListLocations. For more information, see https://cloud.google.com/about/locations/. * JOB_ID can contain only letters ([A-Za-z]), numbers ([0-9]), hyphens (-), or underscores (_). The maximum length is 500 characters.
appEngineHttpTargetobjectApp Engine HTTP target. (id: AppEngineHttpTarget)
attemptDeadlinestring (google-duration)The deadline for job attempts. If the request handler does not respond by this deadline then the request is cancelled and the attempt is marked as a DEADLINE_EXCEEDED failure. The failed attempt can be viewed in execution logs. Cloud Scheduler will retry the job according to the RetryConfig. The default and the allowed values depend on the type of target: * For HTTP targets, the default is 3 minutes. The deadline must be in the interval [15 seconds, 30 minutes]. * For App Engine HTTP targets, 0 indicates that the request has the default deadline. The default deadline depends on the scaling type of the service: 10 minutes for standard apps with automatic scaling, 24 hours for standard apps with manual and basic scaling, and 60 minutes for flex apps. If the request deadline is set, it must be in the interval [15 seconds, 24 hours 15 seconds]. * For Pub/Sub targets, this field is ignored.
descriptionstringOptionally caller-specified in CreateJob or UpdateJob. A human-readable description for the job. This string must not contain more than 500 characters.
httpTargetobjectHTTP target. (id: HttpTarget)
lastAttemptTimestring (google-datetime)Output only. The time the last job attempt started.
pubsubTargetobjectPub/Sub target. (id: PubsubTarget)
retryConfigobjectSettings that determine the retry behavior. (id: RetryConfig)
satisfiesPzsbooleanOutput only. Whether or not this Job satisfies the requirements of physical zone separation
schedulestringRequired, except when used with UpdateJob. Describes the schedule on which the job will be executed. The schedule can be either of the following types: * Crontab * English-like schedule As a general rule, execution n + 1 of a job will not begin until execution n has finished. Cloud Scheduler will never allow two simultaneously outstanding executions. For example, this implies that if the n+1th execution is scheduled to run at 16:00 but the nth execution takes until 16:15, the n+1th execution will not start until 16:15. A scheduled start time will be delayed if the previous execution has not ended when its scheduled time occurs. If retry_count > 0 and a job attempt fails, the job will be tried a total of retry_count times, with exponential backoff, until the next scheduled start time. If retry_count is 0, a job attempt will not be retried if it fails. Instead the Cloud Scheduler system will wait for the next scheduled execution time. Setting retry_count to 0 does not prevent failed jobs from running according to schedule after the failure.
scheduleTimestring (google-datetime)Output only. The next time the job is scheduled. Note that this may be a retry of a previously failed attempt or the next execution time according to the schedule.
statestringOutput only. State of the job.
statusobjectOutput only. The response from the target for the last attempted execution. (id: Status)
timeZonestringSpecifies the time zone to be used in interpreting schedule. The value of this field must be a time zone name from the tz database. Note that some time zones include a provision for daylight savings time. The rules for daylight saving time are determined by the chosen tz. For UTC use the string "utc". If a time zone is not specified, the default will be in UTC (also known as GMT).
userUpdateTimestring (google-datetime)Output only. The creation time of the job.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectprojectsId, locationsId, jobsIdGets a job.
listselectprojectsId, locationsIdpageSize, pageTokenLists jobs.
createinsertprojectsId, locationsIdCreates a job.
patchupdateprojectsId, locationsId, jobsIdupdateMaskUpdates a job. If successful, the updated Job is returned. If the job does not exist, NOT_FOUND is returned. If UpdateJob does not successfully return, it is possible for the job to be in an Job.State.UPDATE_FAILED state. A job in this state may not be executed. If this happens, retry the UpdateJob request until a successful response is received.
deletedeleteprojectsId, locationsId, jobsIdDeletes a job.
pauseexecprojectsId, locationsId, jobsIdPauses a job. If a job is paused then the system will stop executing the job until it is re-enabled via ResumeJob. The state of the job is stored in state; if paused it will be set to Job.State.PAUSED. A job must be in Job.State.ENABLED to be paused.
resumeexecprojectsId, locationsId, jobsIdResume a job. This method reenables a job after it has been Job.State.PAUSED. The state of a job is stored in Job.state; after calling this method it will be set to Job.State.ENABLED. A job must be in Job.State.PAUSED to be resumed.
runexecprojectsId, locationsId, jobsIdForces a job to run now. When this method is called, Cloud Scheduler will dispatch the job, even if the job is already running.

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.

NameDatatypeDescription
jobsIdstring
locationsIdstring
projectsIdstring
pageSizeinteger (int32)
pageTokenstring
updateMaskstring (google-fieldmask)

SELECT examples​

Gets a job.

SELECT
name,
appEngineHttpTarget,
attemptDeadline,
description,
httpTarget,
lastAttemptTime,
pubsubTarget,
retryConfig,
satisfiesPzs,
schedule,
scheduleTime,
state,
status,
timeZone,
userUpdateTime
FROM google.cloudscheduler.jobs
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND jobsId = '{{ jobsId }}' -- required;

INSERT examples​

Creates a job.

INSERT INTO google.cloudscheduler.jobs (
data__name,
data__description,
data__pubsubTarget,
data__appEngineHttpTarget,
data__httpTarget,
data__schedule,
data__timeZone,
data__retryConfig,
data__attemptDeadline,
projectsId,
locationsId
)
SELECT 
'{{ name }}',
'{{ description }}',
'{{ pubsubTarget }}',
'{{ appEngineHttpTarget }}',
'{{ httpTarget }}',
'{{ schedule }}',
'{{ timeZone }}',
'{{ retryConfig }}',
'{{ attemptDeadline }}',
'{{ projectsId }}',
'{{ locationsId }}'
RETURNING
name,
appEngineHttpTarget,
attemptDeadline,
description,
httpTarget,
lastAttemptTime,
pubsubTarget,
retryConfig,
satisfiesPzs,
schedule,
scheduleTime,
state,
status,
timeZone,
userUpdateTime
;

UPDATE examples​

Updates a job. If successful, the updated Job is returned. If the job does not exist, NOT_FOUND is returned. If UpdateJob does not successfully return, it is possible for the job to be in an Job.State.UPDATE_FAILED state. A job in this state may not be executed. If this happens, retry the UpdateJob request until a successful response is received.

UPDATE google.cloudscheduler.jobs
SET 
data__name = '{{ name }}',
data__description = '{{ description }}',
data__pubsubTarget = '{{ pubsubTarget }}',
data__appEngineHttpTarget = '{{ appEngineHttpTarget }}',
data__httpTarget = '{{ httpTarget }}',
data__schedule = '{{ schedule }}',
data__timeZone = '{{ timeZone }}',
data__retryConfig = '{{ retryConfig }}',
data__attemptDeadline = '{{ attemptDeadline }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND jobsId = '{{ jobsId }}' --required
AND updateMask = '{{ updateMask}}'
RETURNING
name,
appEngineHttpTarget,
attemptDeadline,
description,
httpTarget,
lastAttemptTime,
pubsubTarget,
retryConfig,
satisfiesPzs,
schedule,
scheduleTime,
state,
status,
timeZone,
userUpdateTime;

DELETE examples​

Deletes a job.

DELETE FROM google.cloudscheduler.jobs
WHERE projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND jobsId = '{{ jobsId }}' --required;

Lifecycle Methods​

Pauses a job. If a job is paused then the system will stop executing the job until it is re-enabled via ResumeJob. The state of the job is stored in state; if paused it will be set to Job.State.PAUSED. A job must be in Job.State.ENABLED to be paused.

EXEC google.cloudscheduler.jobs.pause 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@jobsId='{{ jobsId }}' --required;