Async Job Operations

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

-H 'Prefer: respond-async'

Setting this preference executes the request as an asynchronous job in the background during low-traffic times, 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

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

Asynchronous GET Collections

When using the standard synchronous GET method on more than the maximum allowed number of 500 resources, only the latest 500 results are returned.

To GET all the results when the number of resources exceeds 500, specify in the header that the call is asynchronous (“async”). This will execute the request as an offline job.

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

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 the results
`result`	Query result	Object (HREF, not required)	Yes
`requested_at`	Time PCE received the request	Date-time	Yes
`requested_by`	The user who initiated the request	Object (HREF, required)	Yes
`terminated_at`	Termination time of the job (regardless of outcome)	Date-time	Yes
`status`	Status of the asynchronous request	Enum (`done`, `pending`, `running`, or `failed`)	Yes
`created_by`	Creator of the 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

Illumio REST APIs 25.4