Asynchronous Work Requests

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.

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 services, 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.

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.

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

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
}

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

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

• Application Performance Monitoring work request API
• Autonomous Recovery Service work request API
• Bastion work request API
• Blockchain Platform work requests
• Cloud Advisor work request API
• Cluster Placement Groups work request API
• Compute work request API

• Connector Hub:

  • Viewing the State of a Connector Hub Work Request
  • Connector Hub work request API
• Container Instances work request API
• Content Management work request API

• Data Catalog:

  • Data Catalog Work Requests
  • Data Catalog work request API
• Data Integration work request API

• Data Labeling:

  • Data Labeling Work Requests
  • Data Labeling work request API

• Data Science:

  • Creating Notebook Sessions and Deleting Projects
  • Data Science work request API
• Database work request API
• Database Management work request API
• Database Migration work request API
• Database Tools work request API
• OCI Database with PostgreSQL work request API
• DevOps work request API
• File Storage work request API
• Fleet Application Management work request API
• Full Stack Disaster Recovery work request API
• Globally Distributed Autonomous Database work request API
• GoldenGate work request API

• IAM:

  • IAM work request API (To delete a different compartment)
  • TaggingWorkRequest API (Tags and Tag Namespace Concepts)
• Integration work request API
• Java Management work request API
• Kubernetes Engine work request API

• Load Balancer:

  • Work Requests for Load Balancer
  • Load Balancer work request API
• Logging Analytics work request API
• Management Agent work request API
• HeatWave work request API
• Network Firewall work request API

• Object Storage:

  • Copy Object Work Requests
  • Object Storage work request API
• Oracle Cloud Bridge work request API
• Oracle Cloud Migrations work request API
• OS Management Hub work request API
• Process Automation work request API
• Queue work request API
• Resource Manager work request API
• Secure Desktops work request API
• Service Mesh work request API
• Stack Monitoring work request API
• Vision work request API
• Visual Builder Studio: WorkRequest API
• Vulnerability Scanning work request API