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
Some Oracle Cloud Infrastructure services, such as Compute and Database, support work requests using the Work Requests API, which contains the GetWorkRequest operation.
Some services offer work requests supported by the service API rather than the Work Requests API discussed in this topic. These service APIs each include operations that work in a similar manner to the GetWorkRequest operation used by the Work Requests API.
See the reference documentation for each service's work request API for details. Links to each are provided in the For More Information section.
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.
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
Application Performance Monitoring
ACCEPTED
IN_PROGRESS
SUCCEEDED
FAILED
CANCELING
CANCELED
Autonomous Recovery Service
ACCEPTED
IN_PROGRESS
WAITING
SUCCEEDED
FAILED
CANCELING
CANCELED
Big Data Service
CREATING
ACTIVE
UPDATING
SUSPENDING
SUSPENDED
RESUMING
DELETING
DELETED
FAILED
Blockchain Platform
ACCEPTED
IN PROGRESS
SUCCEEDED
FAILED
CANCELING
CANCELED
Cluster Placement Groups
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Compute
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Connector Hub
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Content Management
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Database Management
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
OCI Database with PostgreSQL
ACCEPTED
IN_PROGRESS
WAITING
FAILED
SUCCEEDED
CANCELING
CANCELED
Data Catalog
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Data Integration
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Data Labeling
ACCEPTED
IN_PROGRESS
WAITING
SUCCEEDED
CANCELING
CANCELED
FAILED
Data Science
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Database
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
Database Migration
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
DevOps
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
File Storage
CREATING
ACTIVE
DELETING
DELETED
FAILED
UPDATED
Fleet Application Management
ACCEPTED
IN_PROGRESS
CANCELING
CANCELED
SUCCEEDED
FAILED
Full Stack Disaster Recovery
ACCEPTED
IN_PROGRESS
WAITING
CANCELING
CANCELED
SUCCEEDED
FAILED
NEEDS_ATTENTION
Globally Distributed Autonomous Database
ACCEPTED
IN_PROGRESS
WAITING
FAILED
SUCCEEDED
CANCELING
CANCELED
GoldenGate
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELLED
IAM
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Integration
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Java Management
ACCEPTED
IN_PROGRESS
SUCCEEDED
CANCELING
CANCELED
FAILED
Kubernetes Engine
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Load Balancer
CREATING
FAILED
ACTIVE
DELETING
DELETED
Logging Analytics for LogAnalyticsQueryJobWorkRequest
ACCEPTED
IN_PROGRESS
SUCCEEDED
CANCELLED
FAILED
Logging Analytics for LogAnalyticsStorageWorkRequest
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELED
Logging Analytics for LogAnalyticsConfigWorkRequest
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
Management Agent
CREATED
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Network Firewall
ACCEPTED
IN_PROGRESS
WAITING
FAILED
SUCCEEDED
CANCELING
CANCELED
Object Storage
ACCEPTED
IN_PROGRESS
FAILED
COMPLETED
CANCELING
CANCELED
Oracle Cloud Bridge
ACCEPTED
IN_PROGRESS
WAITING
FAILED
SUCCEEDED
CANCELING
CANCELED
Oracle Cloud Migrations
ACCEPTED
IN_PROGRESS
WAITING
FAILED
SUCCEEDED
CANCELING
CANCELED
NEEDS_ATTENTION
OS Management Hub
ACCEPTED
IN_PROGRESS
SUCCEEDED
FAILED
CANCELING
CANCELED
Process Automation
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Queue
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
CANCELING
CANCELED
Resource Manager
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
Secure Desktops
ACCEPTED
IN_PROGRESS
WAITING
FAILED
SUCCEEDED
CANCELING
CANCELED
Service Mesh
ACCEPTED
IN_PROGRESS
FAILED
SUCCEEDED
WAITING
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.
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.
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:
The user issues a CreateCluster API call.
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.
Next, the user issues a GET call on the work request ID to obtain the status of the work request.
The service responds with status code 200, indicating in the response body that the CLUSTER_CREATE operation has the status ACCEPTED.
With continued polling, we see another GET call for the work request.
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.
Step 5. The operation continues, and the user continues to poll the work request using the GET method.
Copy
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".