Restore a Service Instance
/paas/api/v1.1/instancemgmt/{identityDomainId}/services/jaas/instances/{serviceId}/restoredbackups
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:
- About Backup and Restoration for complete information about the contents of backups, what files can be restored, and what happens when a service instance is restored
- Return an Oracle Java Cloud Service Instance to Service After Restoration from a Backup
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
- application/json
-
identityDomainId: string
Identity domain ID for the Oracle Java Cloud Service account.
-
serviceId: string
Name of the Oracle Java Cloud Service instance.
-
Authorization: string
Base64 encoded user name and password separated by a colon or OAuth access token obtained from Oracle Identity Cloud Service. See Authenticate.
-
X-ID-TENANT-NAME: string
Identity domain ID for the Oracle Java Cloud Service account.
object
-
backupId:
string
Backup ID. To retrieve the backup ID, see View All Backups.
-
forceScaleIn(optional):
boolean
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 totrue
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. -
notes(optional):
string
Free-form text to provide additional information about the restoration operation.
-
pauseOTD(optional):
boolean
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.
-
resetBinaries(optional):
boolean
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.
-
restoreConfig(optional):
boolean
Flag that specifies configuration data is restored. This value defaults to
true
.false
is not supported. -
schemaPassword(optional):
string
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. -
unpackAndDecryptOnly(optional):
boolean
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 inbackupId
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.
Response
- application/json
202 Response
object
-
job_id(optional):
string
Job ID for the restoration operation. You can use the job ID to view the status of the restoration operation, as described in View the Status of a Restoration Operation.
-
operationName(optional):
string
Operation performed. This value is set to
restore-backup
. -
target_uri(optional):
string
URI of the restoration resource.
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"
}