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

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 2020 23:16:52 GMT
	"location": https://pce.my-company.com:8443/api/v2/orgs/1/jobs/d1775367-1951-4707-aa2e-37a0b9076d31",
	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
status The current state of the job, to the effect of its success, failure, etc

String

 Yes
job_type An arbitrary designator for the job type or kind, typically supplied by the job requestor String No
result The result produced by the job, typically a URI (with 'href' sub-property), or an error in case of failure. Object, Null No
requested_at Time PCE received request Date-time No
requested_by The URI of the user who requested this job Object (HREF, required) No
terminated_at The time (rfc3339 timestamp) at which this job terminated, either successfully or failingly.", Date-time No
created_by Creator of request Object (HREF, required) No

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": "2020-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": "2020-01-14 23:16:52.303166",
  "terminated_at": "2020-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:$TOKE

Response - Updated Job

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.

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"
  }
}