1. REST API for Oracle Java Cloud Service
  2. Tasks
  3. Backups and Restorations

Restore a Service Instance

post

/paas/api/v1.1/instancemgmt/{identityDomainId}/services/jaas/instances/{serviceId}/restoredbackups

Restores an Oracle Java Cloud Service instance from a backup to undo configuration changes for the existing service instance.

The same endpoint can also be used to extract the contents of a backup archive to the Administration Server node of the service instance. A backup archive is a zip of encrypted sub-archives. The extraction operation will decrypt the sub-archives to produce the original compressed tarballs, then place the tar files in the location /u01/data/backup/work. After extraction and decryption, you should move the tar files to a different location because the next backup or restore operation on the service instance will remove any existing files that are in this location.

Note: An incremental backup archive has only the tar files that have been modified since the previous full backup operation was performed on the service instance. This means you may need to perform the extraction operation on the incremental backup and also on the previous full backup archives in order to obtain the complete tar files of a specific directory.

About undoing changes for an existing instance: You use a backup ID to restore the Oracle Java Cloud Service instance.

In this restore operation, you can also choose to reset the Oracle WebLogic Server and the JDK software to the versions that correspond to the official patch set update (PSU) level of the software that Oracle Java Cloud Service is currently running, or leave the versions unchanged. After the restore operation completes, you may need to perform a set of manual tasks to return the service instance to full operation.

As described in View a Backup, requiresForceScaleFor lists the host names of nodes on the current Oracle Java Cloud Service instance that are not found in the backup you are using to undo configuration changes. If a service instance contains nodes that are not included in the backup being restored, you must scale in the service instance before trying to restore the instance or you can use forceScaleIn in the restore request to automatically scale in the service instance after and only if restoration is successful.

See these topics in Administering Oracle Java Cloud Service:

If a database backup was included in the Oracle Java Cloud Service instance backup: Restoration of the database files for the database deployment associated with the Java Cloud Service instance (you are restoring) is not supported through the Java Cloud Service instance restore operation. You need to restore the database files separately. Depending on whether the database deployment is hosting a single-instance database or an Oracle Real Application Clusters (RAC) database, you use an RMAN tag or a timestamp of the associated database backup to restore the database files. The RMAN tag or timestamp is the dbTag attribute value that is returned by using a GET request on the Oracle Java Cloud Service instance backup, as described in View a Backup.

Request

Supported Media Types
Path Parameters
Header Parameters
Body ()
The request body defines the details of the restoration request.
Root Schema : restoration-postrequest
Type: object
The request body defines the details of the restoration request.
Show Source
  • Backup ID. To retrieve the backup ID, see View All Backups.
  • Flag that specifies whether to automatically scale in the Oracle Java Cloud Service instance if there are nodes configured that are not included in the backup being restored. This value defaults to false, indicating that the service instance should not be scaled in automatically.

    When false and if the Oracle Java Cloud Service instance has nodes configured that are not included in the backup being restored, the restore operation cannot proceed. You can either set the flag to true to allow an automatic scale in as part of the restore operation, or you can manually scale in the service instance before trying to restore. As described in View a Backup, requiresForceScaleFor lists the host names of nodes on the current service instance configuration that are not found in the backup you are using to undo changes.

  • Free-form text to provide additional information about the restoration operation.

  • Flag that specifies whether to pause the load balancer during the restoration process. This value defaults to false.

    If set to true, the load balancer is paused and stops forwarding requests to the Managed Servers in the service instance during the restoration process, and responds with an HTTP 503 status code to client requests. After the restoration process completes, the load balancer is restarted.

    If pause or restart of the load balancer fails, for example, because the load balancer Administration Server is not available, the restoration process proceeds. The restoration process will fail, however, if the load balancer health check fails.

    You should not rely on this feature if any manual tasks are required to be performed once the restoration completes. See Return an Oracle Java Cloud Service Instance to Service After Restoration from a Backup in Administering Oracle Java Cloud Service.

    Note: This flag is valid only if the OTD load balancer is enabled.

  • Flag that specifies whether to reset the Oracle WebLogic Server and the JDK software to the versions that correspond to the official patch set update (PSU) level of the software that Oracle Java Cloud Service is currently running. This value defaults to false, indicating that the binary files should not be replaced.

    Note: To restore software to an older version, initiate a roll back of the appropriate patch.

  • Flag that specifies configuration data is restored. This value defaults to true. false is not supported.
  • The most recent schema password that was used to update the infrastructure database schemas associated with the service instance.

    This attribute is required only if the status of the backup specified in backupId is retired because the schema password was changed after the backup was taken.

  • Only applicable when extracting the contents of a backup archive. Only this attribute and backupId are required for the extraction operation; all other attributes will be ignored.

    Set this flag to true to indicate that the contents of the backup archive specified in backupId should be extracted and decrypted. The original compressed tarballs will be placed in the location /u01/data/backup/work on the Administration Server node of the service instance.

Back to Top

Response

Supported Media Types

202 Response

Accepted. See Status Codes for information about other possible HTTP status codes.
Body ()
Root Schema : restoration-response
Type: object
The response body defines the details of the restoration operation.
Show Source
Back to Top

Examples

The following example shows how to restore an Oracle Java Cloud Service instance by submitting a POST request on the REST resource using cURL.

Note: The command in this example uses the URL structure https://rest_server_url/resource-path, where rest_server_url is the REST server to contact for your identity domain (or Cloud Account). See Send Requests.

cURL Command

curl -i -X POST -u username:password -d @restore.json -H "Content-Type:application/json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/jaas/instances/ExampleInstance/restoredbackups

The request payload to provide depends on the type of restore operation you want to perform.

Example of Request Body (Undo Changes for an Existing Instance)

The following shows an example of the request body for undoing changes on an existing service instance. Three optional values are provided. Note that the only required value is backupId. 

{
     "backupId":"1449332100032",
     "forceScaleIn":true,
     "notes":"Restore from a backup that was taken before scale out",
     "pauseOTD":true
}

The following shows an example of the request body for undoing changes by restoring from a backup that was retired because of a database schema password change. That is, the schema password change was made after the backup was taken. Note that schemaPassword is required when you restore from such a backup. 

{
   "backupId":"9eb8e667-2eea-4c55-8ade-5e14e9711d67",
   "schemaPassword": "password",
   "notes": "This is a schema password change retired backup."
}

Example of Response Header

The following shows an example of the response header:

HTTP/1.1 202 Accepted
Date: Sat, 05 Dec 2015 23:39:02 GMT
Transfer-Encoding: chunked
Content-Type: application/json

Example of Response Body

The following shows an example of the response JSON document. Note the job ID that you can use to view the status of the restoration operation.

{
    "operationName":"restore-backup",
    "job_id":"8226",
    "target_uri":"https:\/\/rest_server_url\/paas\/api\/v1.1\/instancemgmt\/ExampleIdentityDomainID\/services\/jaas\/instances\/ExampleInstance\/restoredbackups\/8226"
}
Back to Top