Async Job Operations

To create the asynchronous GET job request, set the following preference:

-H 'Prefer: respond-async'

Setting this preference executes the request during low-traffic times as an asynchronous job in the background, which lightens network traffic loads.

Workflow for Async Job Operations

The workflow for requesting an asynchronous bulk job consists of the following tasks: 

  1. Create the asynchronous GET job request.
  2. Poll the job until the status is "Done" or "Failed."
  3. Obtain the HREF of the completed request job.
  4. Use the HREF to get the results of the request job.

Create an Async Job Request

This example demonstrates a request for an asynchronous collection of labels.

NOTE:

Use query parameters for a filtered job request, such as to return only the environment labels: .../labels?key=env

URI to Create a Job Request 

GET [api_version]/labels

The asynchronous collection header is highlighted in blue bold font:

curl -i -X GET 'https://pce.my-company.com:8443/api/v2/orgs/1/labels' -H 'Accept: application/json' -H 'Prefer: respond-async' -u $KEY:$TOKEN

Response with a Job Status

The response is 202 - Accepted, which includes Location, the header Retry-After and an empty body: 

Server: nginx
Date: Thu, 14 Jan 2016 23:16:52 GMT
Location: /orgs/1/jobs/[href]
Retry-After: 5
Transfer-Encoding: chunked
Connection: keep-alive
Status: 202 Accepted
Cache-Control: no-cache
X-Request-Id: 36aae8ce-82ed-4a6a-8a76-77d2df78daff

Poll the Job

After submitting the job request, poll the job using the suggested Retry-After time to determine when the job is complete.

URI to Get the Status of the Job

The following example demonstrates how to poll the job to determine its status. 

GET [api_version][org_href]/jobs/[href]

Poll the HREF provided in the Location field of the response using the duration specified in Retry-After until the status is either done or failed.

curl -i -X GET 'https://pce.my-company.com:8443/api/v2/orgs/1/jobs/[href]' -H 'Accept: application/json' -u $KEY:$TOKEN

Async Job Response Properties

The following table defines the properties returned in the response:

Property Description Type Required
href HREF for resource String Yes
job_type Query type defined during job creation String Yes
description Reference information String No
result Query result Object (HREF, not required) Yes
requested_at Time PCE received request Date-time Yes
requested_by User who initiated request Object (HREF, required) Yes
terminated_at Termination time of job (regardless of outcome) Date-time Yes
status Status of async request

Enum

Pending: Waiting to start

Running: In progress

Done: Complete (successful/unsuccessful)

Failed: Unable to complete (exceeded time limit)

 Yes
created_by Creator of request Object (HREF, required) Yes

Async Job Status

If the job status is running, the response body includes the following results:

{
  "href": "/orgs/1/jobs/43f6e9e3-6a68-4481-87c6-18fd096dafbe",
  "job_type": ":illumio/async_requests",
  "description": "/orgs/1/labels",
  "result": {
  },
  "status": "running",
  "requested_at": "2016-01-14 23:16:52.303166",
  "requested_by": {
    "href": "/users/1"
  }
}

Get Async Job Results

The following example demonstrates how to get job results.

URI to Get Async Job Results

GET [api_version][org_href]/datafiles/[href]

Curl Command to Get Async Job Results

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/1/datafiles/[href] -H 'Accept: application/json' -u $KEY:$TOKEN

Response Body with Request Results

When the job is complete, use the HREF in the Result field to obtain the results:

{
  "href": "/orgs/1/jobs/43f6e9e3-6a68-4481-87c6-18fd096dafbe",
  "job_type": ":illumio/async_requests",
  "description": "/orgs/1/labels",
  "result": {
    "href": "/orgs/1/datafiles/[href]"
  },
  "status": "done",
  "requested_at": "2016-01-14 23:16:52.303166",
  "terminated_at": "2016-01-14 23:17:05.223047",
  "requested_by": {
    "href": "/users/1"
  }
}

Poll the Query Job Status

After submitting the job request, poll the job using the suggested "Retry-After" duration to determine when the job is complete.

The PCE has four possible status options for the job: 

  • Pending: Waiting to start
  • Running: In progress
  • Done: Complete (successful/unsuccessful)
  • Failed: Unable to complete (exceeded time limit)

Get Jobs

Specify the maximum number of jobs to return with the max_results query parameter.

Specify the type of job to return with the job_type query parameter.

URI to Get the Status of All Jobs

GET [api_version]/jobs

Curl Command to Get All Job Status

curl -i -X GET 'https://pce.my-company.com:8443/api/v2/orgs/1/jobs' -H 'Accept: application/json' -u $KEY:$TOKEN

Get a Job

URI to Get the Status of a Job

GET [api_version]/jobs/[href]

Curl Command to Get a Job Status

curl -i -X GET 'https://pce.my-company.com:8443/api/v2/orgs/1/jobs/[href]' -H 'Accept: application/json' -u $KEY:$TOKEN

Response Properties

Poll the HREF provided in the Location field of the response using the duration specified in Retry-After until the status is either "done" or ""failed": 

Property Description Type In Results
href HREF for resource String Yes
job_type Query type defined during job creation String Yes
description Reference information String Might not be in results
result Query result Object (HREF, not required) Yes
requested_at Time PCE received request Date-time Yes
requested_by User who initiated request Object (HREF, required) Yes
terminated_at Termination time of job (regardless of outcome) Date-time Yes
status Status of the asynchronous request Enum ("done", "pending", "running", or "failed") Yes
created_by Creator of request Object (HREF, required) Yes

Response - Updated Job Status

If the job is still running, the response includes a status of "running", as highlighted in blue below:

  {
  "href": "/orgs/1/jobs/43f6e9e3-6a68-4481-87c6-18fd096dafbe",
  "job_type": ":illumio/async_requests",
  "description": "/orgs/1/labels",
  "result": {
  },
  "status": "running",
  "requested_at": "2016-01-14 23:16:52.303166",
  "requested_by": {
    "href": "/users/1"
  }
}

Delete a Job

URI to Delete a Job

DELETE [api_version]/jobs/[href]

Curl Command to Delete a Job

curl -i -X DELETE 'https://pce.my-company.com:8443/api/v2/orgs/1/jobs/[href]' -u $KEY:$TOKEN

Get the Job Results

This example demonstrates how to get job results after polling job returns a status of "done".

The uuid path parameter is required. The filename path parameter is optional, it specifies the filename to save the job as.

URI to Get Job Results

GET [api_version][org_href]/datafiles/[uuid]

Curl Command to Get Job Results

curl -i -X GET 'https://yourcompany.com:1234/api/v2/orgs/1/datafiles/[uuid]' -H 'Accept: application/json' -u $KEY:$TOKEN

Response with Results of Request

{
  "href": "/orgs/1/jobs/43f6e9e3-6a68-4481-87c6-18fd096dafbe",
  "job_type": ":illumio/async_requests",
  "description": "/orgs/1/labels",
  "result": {
    "href": "/orgs/1/datafiles/[uuid]"
  },
  "status": "done",
  "requested_at": "2016-01-14 23:16:52.303166",
  "terminated_at": "2016-01-14 23:17:05.223047",
  "requested_by": {
    "href": "/users/1"
  }
}