Oracle Cloud Infrastructure Documentation

Asynchronous Work Requests

This topic describes asynchronous work requests for long-running operations against Oracle Cloud Infrastructure services. It also provides guidance on obtaining request status, and for inspecting the request response to enable filtering for affected resources.

Overview

API calls to Oracle Cloud Infrastructure services can launch long-running operations that do not complete the client's request before a response is returned. In these cases, the service spawns an asynchronous work request that allows for visibility into the progress of long-running, asynchronous operations. The response to the REST API call contains a work request ID in the opc-work-request-id header, which allows you to monitor its progress and status. The work request itself remains in a queue until the operation has completed.

You can monitor the status of the work request at any time by calling GetWorkRequest and passing in the work request ID.

Note

The Compute and Database services support work requests using Work Requests API, which contains the GetWorkRequest operation.

The Container Engine for Kubernetes, Load Balancing, Object Storage and IAM services each support work requests through the service APIs. These service APIs each include operations that work in a similar manner to the GetWorkRequest operation used by the Work Requests API.

 

Two features of the request response are of particular interest: the status of the work request, and a list of the resources that are affected by the work request. The status is important because asynchronous work requests must know when an operation has completed, is still running, or whether it has failed altogether.

To retrieve information about work request failures or errors, each service provides APIs for fetching information about errors, and logs. For links to API reference documentation for each of the service, see the section For More Information.

Also important in cases where a work request operation affects several resources is having a list of the resources that a work request affects, along with each one's entityType and actionType attributes.

Work Request Status

Asynchronous work requests allow you to monitor their progress by providing a status attribute on the WorkRequest object. Each of the supported services provides its own API for obtaining status, as listed in the following sections.

Note

There is a ContainerEngineWaiters class that allows you to create a callback using the forWorkRequest method. Use this API to forward a notification when an operation's status changes, for example, from IN_PROGRESS to COMPLETED.

The following table lists status attributes that are supported by the WorkRequest object on the respective services.

Service Status Attributes
Compute
  • ACCEPTED
  • IN_PROGRESS
  • FAILED
  • SUCCEEDED
  • CANCELING
  • CANCELED
Container Engine for Kubernetes
  • ACCEPTED
  • IN_PROGRESS
  • FAILED
  • SUCCEEDED
  • CANCELING
  • CANCELED
Database
  • ACCEPTED
  • IN_PROGRESS
  • FAILED
  • SUCCEEDED
IAM
  • ACCEPTED
  • IN_PROGRESS
  • FAILED
  • SUCCEEDED
  • CANCELING
  • CANCELED
Load Balancing
  • CREATING
  • FAILED
  • ACTIVE
  • DELETING
  • DELETED
Object Storage
  • ACCEPTED
  • IN_PROGRESS
  • FAILED
  • COMPLETED
  • CANCELING
  • CANCELED

Filtering the Request Response

You sometimes need to know which resources are affected by a given asynchronous work request. In cases where the request response includes just one or two affected resources, the body of the request response is probably sufficient. However, in cases where a request response affects a great many resources, you must filter the response to identify the resources that you're interested in.

Filtering of resources listed in a work request response relies on two attributes of the WorkRequestResource type: entityType and actionType.

  • entityType: Represents the resource type which the work request affects. This is an optional attribute, but each resource can have only one entityType.
  • actionType: Represents how the specified resource is affected by the operation associated with the work request. Each service specifies a fixed list of allowable actionType values (shown in the sections following).

To obtain resource information on a work request, call GetWorkRequest and pass in the work request ID. The call returns a response in JSON format. Following is an example from calling GetWorkRequest on the Object Storage service.

{
    operationType: "COPY_OBJECT",
    status: "IN_PROGRESS",
    id: "f54527d6-029b-4221-9046-a811b7686202",
    resources: [
        {
            entityType: "object",
            actionType: "READ",
            entityUri: "/n/mynamespace/b/backups/o/myobject"
        },
        {
            entityType: "object",
            actionType: "WRITTEN",
            entityUri: "/n/mynamespace/b/backups/o/copyofmyobject"
        },
    ],
    timeAccepted: 2017-10-13T17:23:46.000Z,
    timeStarted: 2017-10-13T17:23:52.198Z,
    percentComplete: 10.0
}

Note

Different services provide slightly different responses. See the reference documentation for each service's work request API for details. Links to each are provided in the For More Information section.

 

The following table lists the entity types and action types that are supported by Oracle Cloud Infrastructure services.

Service Name Operation entityType actionType
Container Engine for Kubernetes

CreateCluster

DeleteCluster

UpdateCluster

CreateNodePool

DeleteNodePool

UpdateNodePool

cluster

nodepool

ACCEPTED

IN_PROGRESS

FAILED

SUCCEEDED

CANCELING

CANCELED

Load Balancing

CreateLoadBalancer

UpdateLoadBalancer

DeleteLoadBalancer

LoadBalancer

ACCEPTED

IN_PROGRESS

FAILED

SUCCEEDED

Object Storage CopyObject object READ

WRITTEN

Request/Response Sample

Following is a sequence of REST API calls to create a cluster, which is a common long-running operation. The caller retrieves the work request ID from the response to the initial POST call and then periodically polls the WorkRequest to determine the status of the operation. The request/response sequence that follows depicts this workflow:

  1. The user issues a CreateCluster API call.
  2. The service responds with status code 202, indicating that the request has been accepted and returns a work request ID in the Opc-Work-Request-Id header.
  3. Next, the user issues a GET call on the work request ID to obtain the status of the work request.
  4. The service responds with status code 200, indicating in the response body that the CLUSTER_CREATE operation has the status ACCEPTED.
  5. With continued polling, we see another GET call for the work request.
  6. The service responds with status code 200. The response body reports that the operation SUCCEEDED.

Step 1. Initial API call to initiate a CLUSTER_CREATE operation.

POST https://containerengine.eu-frankfurt-1.oraclecloud.com/20180222/clusters
Accept: application/json
authorization: <Redacted>
content-length: 480
Content-Type: application/json
date: Mon, 02 Jul 2018 18:20:03 GMT
host: containerengine.eu-frankfurt-1.oraclecloud.com
opc-client-info: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT
opc-request-id: D7A390ED909C47038C438BA3629FB612
User-Agent: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT (Mac OS X/10.13.5; Java/1.8.0_172; Java HotSpot(TM) 64-Bit Server VM/25.172-b11)
x-content-sha256: S8U8OKQHyTLNViAzgexkjxvF4ctncJJHTjuRfXn0ya4={
   "name":"JavaSDK.CRUD",
   "compartmentId":"ocid1.compartment.oc1..<unique_ID>",
   "vcnId":"ocid1.vcn.oc1.eu-frankfurt-1.<unique_ID>",
   "kubernetesVersion":"v1.10.3",
   "options":{"serviceLbSubnetIds":["ocid1.subnet.oc1.eu-frankfurt-1.<unique_ID>",
   "ocid1.subnet.oc1.eu-frankfurt-1.<unique_ID>"]}}

Step 2. The response to the initial API call, which contains the work request ID in the Opc-Work-Request-Id header.

202
Access-Control-Allow-Methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: opc-work-request-id
Content-Length: 0
Date: Mon, 02 Jul 2018 18:20:04 GMT
Opc-Request-Id: D7A390ED909C47038C438BA3629FB612/33EEDCAAB2E84508B34AA75CD0FD86F4/8261D1CC89814E9BB934440A1F43DA09
Opc-Work-Request-Id: ocid1.clustersworkrequest.oc1.eu-frankfurt-1.exampleuniqueID
Uri: /20180222/clusters
Vary: Accept-Encoding
X-Rate-Limit-Duration: 1
X-Rate-Limit-Limit: 16.70
X-Rate-Limit-Request-Forwarded-For: 10.237.10.0, 10.237.9.51
X-Rate-Limit-Request-Remote-Addr: 10.237.9.51:53077

Step 3. Because this is a long-running operation, the user periodically polls the work request using a GET call to determine its status.

GET https://containerengine.eu-frankfurt-1.oraclecloud.com/20180222/workRequests/<clusters_work_request_OCID>
Accept: application/json
authorization: <Redacted>
date: Mon, 02 Jul 2018 18:20:04 GMT
host: containerengine.eu-frankfurt-1.oraclecloud.com
opc-client-info: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT
opc-request-id: E8F20DAC443346B3B0EA599F367EE294
User-Agent: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT (Mac OS X/10.13.5; Java/1.8.0_172; Java HotSpot(TM) 64-Bit Server VM/25.172-b11)

Step 4. The GET call returns the following response, which indicates in the response body that the CLUSTER_CREATE operation has a status of ACCEPTED.

200
Access-Control-Allow-Methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: opc-work-request-id
Content-Length: 717
Content-Type: application/json
Date: Mon, 02 Jul 2018 18:20:05 GMT
Etag: 56a41efaf33d81a54933495ee910c24d7bce7a83adf18810f95e07bdd2055805
Opc-Request-Id: E8F20DAC443346B3B0EA599F367EE294/8B19C9FC3B4442CEA14685D1973D0856/0BA60B0711764DE4A4373071632708C7
Retry-After: 30
Uri: /20180222/workRequests/_id_
Vary: Accept-Encoding
X-Rate-Limit-Duration: 1
X-Rate-Limit-Limit: 16.70
X-Rate-Limit-Request-Forwarded-For: 10.237.10.0, 10.237.9.51
X-Rate-Limit-Request-Remote-Addr: 10.237.9.51:43533
{
  "id": "ocid1.clustersworkrequest.oc1.eu-frankfurt-1.exampleuniqueID",
  "operationType": "CLUSTER_CREATE",
  "status": "ACCEPTED",
  "compartmentId": "ocid1.compartment.oc1..exampleuniqueID",
  "resources": [
    {
      "actionType": "IN_PROGRESS",
      "entityType": "cluster",
      "identifier": "ocid1.cluster.oc1.eu-frankfurt-1.exampleuniqueID",
      "entityUri": "/clusters/ocid1.cluster.oc1.eu-frankfurt-1.exampleuniqueID"
    }
  ],
  "timeAccepted": "2018-07-02T18:20:05Z",
  "timeStarted": null,
  "timeFinished": null
}

Step 5. The operation continues, and the user continues to poll the work request using the GET method.

GET https://containerengine.eu-frankfurt-1.oraclecloud.com/20180222/workRequests/<clusters_work_request_OCID>
Accept: application/json
authorization: <Redacted>
date: Mon, 02 Jul 2018 18:24:13 GMT
host: containerengine.eu-frankfurt-1.oraclecloud.com
opc-client-info: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT
opc-request-id: 64595B97E39A471A886DA29966BB6B1D
User-Agent: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT (Mac OS X/10.13.5; Java/1.8.0_172; Java HotSpot(TM) 64-Bit Server VM/25.172-b11)

Step 6. The last GET call produced the following response, which indicates that the operation has completed. Note the entityType is "cluster" and the actionType is "CREATED".

200
Access-Control-Allow-Methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: opc-work-request-id
Content-Length: 750
Content-Type: application/json
Date: Mon, 02 Jul 2018 18:24:14 GMT
Etag: 023d2a8ccb6d893fa8c875f64652353f21d22607825f49eeeb15b5394ae24918
Opc-Request-Id: 64595B97E39A471A886DA29966BB6B1D/3A81140991C94794AF365016E31DBE82/6245FBD8C25842B6BDF15187EA6ADB21
Uri: /20180222/workRequests/_id_
Vary: Accept-Encoding
X-Rate-Limit-Duration: 1
X-Rate-Limit-Limit: 16.70
X-Rate-Limit-Request-Forwarded-For: 10.237.3.0, 10.237.40.183
X-Rate-Limit-Request-Remote-Addr: 10.237.40.183:55856

{
  "id": "ocid1.clustersworkrequest.oc1.eu-frankfurt-1.exampleuniqueID",
  "operationType": "CLUSTER_CREATE",
  "status": "SUCCEEDED",
  "compartmentId": "ocid1.compartment.oc1..exampleuniqueID",
  "resources": [
    {
      "actionType": "CREATED",
      "entityType": "cluster",
      "identifier": "ocid1.cluster.oc1.eu-frankfurt-1.exampleuniqueID",
      "entityUri": "/clusters/ocid1.cluster.oc1.eu-frankfurt-1.exampleuniqueID"
    }
  ],
  "timeAccepted": "2018-07-02T18:20:05Z",
  "timeStarted": "2018-07-02T18:20:10Z",
  "timeFinished": "2018-07-02T18:24:01Z"
}

For More Information