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.
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.
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 |
|
Autonomous Recovery Service |
|
Big Data Service |
|
Blockchain Platform |
|
Cluster Placement Groups |
|
Compute |
|
Connector Hub |
|
Content Management |
|
Database Management |
|
OCI Database with PostgreSQL |
|
Data Catalog |
|
Data Integration |
|
Data Labeling |
|
Data Science |
|
Database |
|
Database Migration |
|
DevOps |
|
Full Stack Disaster Recovery |
|
Globally Distributed Autonomous Database |
|
GoldenGate |
|
IAM |
|
Integration |
|
Java Management |
|
Kubernetes Engine |
|
Load Balancer |
|
Logging Analytics for
LogAnalyticsQueryJobWorkRequest |
|
Logging Analytics for
LogAnalyticsStorageWorkRequest |
|
Logging Analytics for
LogAnalyticsConfigWorkRequest |
|
Management Agent |
|
Network Firewall |
|
Object Storage |
|
Oracle Cloud Bridge |
|
Oracle Cloud Migrations |
|
OS Management Hub |
|
Process Automation |
|
Queue |
|
Resource Manager |
|
Secure Desktops |
|
Service Mesh |
|
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
}
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 |
---|---|---|---|
Application Performance Monitoring | apm-domains |
|
|
Autonomous Recovery Service |
ChangeProtectionPolicyCompartment ChangeRecoveryServiceSubnetCompartment |
|
|
Blockchain Platform | instance
|
|
|
Cluster Placement Groups |
|
|
|
Content Management | oceInstance |
|
|
Database Management |
ChangeDbManagementPrivateEndpointCompartment CreateDbManagementPrivateEndpoint DeleteDbManagementPrivateEndpoint GetDbManagementPrivateEndpoint |
private-endpoints |
|
Database Migration |
|
|
|
OCI Database with PostgreSQL | |||
Data Catalog | catalog
|
|
|
Data Integration | disworkspace
|
|
|
Data Labeling | datalabelingdataset |
|
|
Data Science |
|
|
|
DevOps |
|
|
|
Full Stack Disaster Recovery |
|
|
|
Globally Distributed Autonomous Database |
ChangeShardedDatabaseCompartment |
|
|
GoldenGate |
|
|
|
Integration |
Note: |
instance |
|
Kubernetes Engine |
|
|
|
Load Balancer | LoadBalancer
|
|
|
Management Agent | DeployPlugins | managementAgent |
|
Network Firewall |
|
|
|
Object Storage | CopyObject | object
|
|
Oracle Cloud Bridge | ocbworkrequest |
|
|
Oracle Cloud Migrations |
ChangeReplicationScheduleCompartment |
ocmworkrequest |
|
OS Management Hub |
AttachManagedInstancesToLifecycleStage AttachManagedInstancesToManagedInstanceGroup AttachSoftwareSourcesToManagedInstance AttachSoftwareSourcesToManagedInstanceGroup DetachManagedInstancesFromLifecycleStage DetachManagedInstancesFromManagedInstanceGroup DetachSoftwareSourcesFromManagedInstance DisableModuleStreamOnManagedInstance DisableModuleStreamOnManagedInstanceGroup EnableModuleStreamOnManagedInstance EnableModuleStreamOnManagedInstanceGroup InstallModuleStreamProfileOnManagedInstance InstallModuleStreamProfileOnManagedInstanceGroup InstallPackagesOnManagedInstance InstallPackagesOnManagedInstanceGroup InstallWindowsUpdatesOnManagedInstance InstallAllWindowsUpdatesOnManagedInstancesInCompartment InstallWindowsUpdatesOnManagedInstanceGroup ManageModuleStreamsOnManagedInstance ManageModuleStreamsOnManagedInstanceGroup PromoteSoftwareSourceToLifecycleStage RefreshSoftwareOnManagedInstance RemoveModuleStreamProfileFromManagedInstance RemoveModuleStreamProfileFromManagedInstanceGroup RemovePackagesFromManagedInstance RemovePackagesFromManagedInstanceGroup ScheduledJob/RunScheduledJobNow SwitchModuleStreamOnManagedInstance UpdateAllPackagesOnManagedInstanceGroup UpdateAllPackagesOnManagedInstancesInCompartment |
|
|
Process Automation | instance |
|
|
Queue | |||
Resource Manager |
|
|
|
Secure Desktops |
|
|
|
Service Mesh |
CreateVirtualServiceRouteTable UpdateVirtualServiceRouteTable DeleteVirtualServiceRouteTable CreateIngressGatewayRouteTable UpdateIngressGatewayRouteTable |
|
|
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:
- 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 statusACCEPTED
. - 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.
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
- 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:
- Container Instances work request API
- Content Management work request API
-
Data Catalog:
- Data Integration work request API
-
Data Labeling:
-
Data Science:
- 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
- Full Stack Disaster Recovery work request API
- Globally Distributed Autonomous Database work request API
- GoldenGate work request API
-
IAM:
- Integration work request API
- Java Management work request API
- Kubernetes Engine work request API
-
Load Balancer:
- Logging Analytics work request API
- Management Agent work request API
- HeatWave work request API
- Network Firewall work request API
-
Object Storage:
- 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