Custom Objects Jobs

The Jobs API lets you define and run asynchronous batch operation jobs onobject recordsandrelationship records. For example, you can define and run a single job that creates many object records.

For more information, seeJobsin the定制对象开发者指南.

See alsoRate limitsin the introduction.

JSON format

Jobs are represented as JSON objects with the following properties:

Job statuses

A job can have one of the following statuses:

You might also receive an "404 Not Found" HTTP response. Jobs and their related ids expire after a day.

Example

             

              
{"completed_at":"2017-11-03T16:00:16Z","created_at":"2017-11-03T16:00:06Z","id":"8b72559ae838-c9a0-11e7-abc4-cec278b6b50a6e6",“job_status”:"completed","results":[{"data":{"id":"73c698be-cb64-4678-ba73-29683d2c32er"},"success":true},{"errors":[{"code":"UnprocessableEntity","detail":"External Id is already in use for the Resource Type key: product","status":"422","title":"Unprocessable Entity"}],"success":false}],"updated_at":"2017-11-03T16:00:16Z"}
             

List Jobs

• GET /api/sunshine/jobs

Returns all current jobs or a list filtered by status. SeeJob statuses.

Jobs expire after one day, after which they can no longer be accessed.

You can use a parameter namedstatusto filter the results. Example:

GET /api/sunshine/jobs?status=queued

The allowed parameter values are queued, processing, failed, completed, or aborted.

Allowed for

• Agents

Parameters

              

               
旋度https://{subdomain}.zendesk.com/api/sunshine/jobs\-v -u{email_address}:{password}
              

Example response(s)

              

               
// Status 200 OK{"data":[{"completed_at":"2017-11-03T16:04:06Z","created_at":"2017-11-03T16:00:06Z","id":"559ae838-c9a0-11e7-abc4-cec278b6b50a",“job_status”:"completed","updated_at":"2017-11-03T16:04:06Z"},{"completed_at":null,"created_at":"2017-11-03T16:02:06Z","id":"886ae838-c9a0-11e7-abc4-cec278b6b50a",“job_status”:"processing","updated_at":"2017-11-03T16:04:06Z"}]}
              

Show Job

• GET /api/sunshine/jobs/{custom_object_job_id}

Returns the status of the specified job. SeeJob statuses.

Jobs expire after one day, after which they can no longer be accessed.

Allowed for

• Agents

Parameters

              

               
旋度https://{subdomain}.zendesk.com/api/sunshine/jobs/{id}\-v -u{email_address}:{password}
              

Example response(s)

              

               
// Status 200 OK{"data":{"completed_at":"2017-11-03T16:00:16Z","created_at":"2017-11-03T16:00:06Z","id":"8b72559ae838-c9a0-11e7-abc4-cec278b6b50a6e6",“job_status”:"completed","results":[{"data":{"id":"73c698be-cb64-4678-ba73-29683d2c32er"},"success":true},{"errors":[{"code":"UnprocessableEntity","detail":"External Id is already in use for the Resource Type key: product","status":"422","title":"Unprocessable Entity"}],"success":false}],"updated_at":"2017-11-03T16:00:16Z"}}
              

Create Job

• POST /api/sunshine/jobs

Creates a job with supported type and action.

The API doesn't wait for the job to finish before sending a response. The response gives you a job id that you can use to poll the API for the status of the job. SeeShow JobandJob statuses.

The maximum number of concurrent jobs that can be processed for an account is 1000.

When creating a Job, you may use the following properties:

action property

The action you can specify depends on the job type.

A job of type "resources" (object records) supports the following actions:

• "post"
• "delete"
• "update"
• "external_id_delete"
• "external_id_set"

A job of type "relationships" (relationship records) supports the following action:

• "post"
• "delete"

data property

Thedataproperty in the request body specifies an array of JSON objects to batch process. The format of the JSON objects you can specify depends on the job.

Jobs to post object records or relationship records

When a job's type is "resources" or "relationships" and its action is "post", thedataproperty supports object records or relationship records. The format of each object is the same as thedataobject for the equivalent single-operation endpoints forobject recordsorrelationship records.

Example:

             

              
{"type":"resources","action":"post","data":[{"type":"product","external_id":"3","attributes":{"id":"3","name":"Strawberry Chewing Gum"}},{"type":"product","external_id":"4","attributes":{"id":"4","name":"Coffee Chewing Gum"}}]}
             

Jobs to update object records

When a job's type is "resources" and its action is "update", thedataproperty supports JSON objects with the following properties:

For each object, theidvalue is used to locate the object record in the database and theattributesvalue is used to patch the existing value.

Example:

             

              
{"type":"resources","action":"update","data":[{"id":"576a0d0d-fb3f-11e9-80f8-65590b274410","attributes":{"name":"Strawberry Chewing Gum v2"}},{"id":"576a5b2e-fb3f-11e9-80f8-f1af99ee4b4c","attributes":{"name":"Coffee Chewing Gum (decaf)"}}]}
             

Jobs to set object records using external id

When a job's type is "resources" and its action is "external_id_set", thedataproperty supports JSON objects with the following properties:

For each object, theexternal_idand resourcetypevalues are used to locate the object record in the database. If the resource exists, theattributesvalue is used to patch the existing value. If the resource does not exist, a new resource of the given resource type is created with the external_id and attributes.

Example:

             

              
{"type":"resources","action":"external_id_set","data":[{"type":"product","external_id":"4","attributes":{"name":"Coffee Chewing Gum (decaf)"}},{"type":"product","external_id":"5","attributes":{"name":"Blueberry Chewing Gum"}}]}
             

Jobs to delete object records or relationship records

When a job's type is "resources" or "relationships" and its action is "delete", thedataproperty supports a list of ids of the object or relationship records to be deleted.

Examples:

             

              
{"type":"resources","action":"delete","data":["576a0d0d-fb3f-11e9-80f8-65590b274410","576a5b2e-fb3f-11e9-80f8-f1af99ee4b4c","69d0b3e2-ec4e-11e9-ad75-4b6f5c0467f5"]}
             

             

              
{"type":"relationships","action":"delete","data":["576a0d0d-fb3f-11e9-80f8-65590b274410","576a5b2e-fb3f-11e9-80f8-f1af99ee4b4c","69d0b3e2-ec4e-11e9-ad75-4b6f5c0467f5"]}
             

Jobs to delete object records using external id

When a job's type is "resources" and its action is "delete", thedataproperty supports a list of objecttypeandexternal_id对象的记录被删除。

Examples:

             

              
{"type":"resources","action":"external_id_delete","data":[{"type":"product","external_id":"4"},{"type":"product","external_id":"5"}]}
             

              

               
旋度https://{subdomain}.zendesk.com/api/sunshine/jobs\-d'{"type": "resources", "action": "post", "data": [{...}, {...}, ...]}'\-H"Content-Type: application/json"-X POST\-v -u{email_address}:{password}
              

Example response(s)

              

               
// Status 201 Created{"data":{"completed_at":null,"created_at":"2017-11-03T16:00:06Z","id":"8b72559ae838-c9a0-11e7-abc4-cec278b6b50a6e6",“job_status”:"queued","results":[],"updated_at":"2017-11-03T16:00:06Z"}}