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:

Create the asynchronous GET job request.
Poll the job until the status is "Done" or "Failed."
Obtain the HREF of the completed request job.
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": 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
`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`	The 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`	The 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"
  }
}

REST APIs for 24.2.20 and 24.2.10