1. Cloud Control Database Lifecycle Management Administrator's Guide
  2. Database Provisioning
  3. Database High Availability REST API

15 Database High Availability REST API

This chapter provides details of the REST APIs for Database High Availability supported in Enterprise Manager. Enable Data Guard to improve production database performance by offloading resource-intensive backup and reporting operations to standby systems.

Data Guard

Data Guard Switchover REST API

Table 15-1 Data Guard Switchover

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/dataguard/switchover

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "primaryTargetName" : "<primary target name>",
    "primaryTargetType" : "oracle_database|rac_database",
    "standbyTargetName" : "<standby target name>",
    "standbyTargetType" : "oracle_database|rac_database",
    ["primaryDbCredsName" : "<primary database credential name>",]
    ["primaryHostCredsName" : "<primary database host credential name>",]
    ["standbyDbCredsName" : "<standby database credential name>",]
    ["standbyHostCredsName" : "<standby database host credential name>",]
    ["swapJobs" : "false|true",]
    ["swapThresholds" : "false|true",]
    ["tdeWalletCredsName" : "<transparent data encryption wallet credentials of the primary database>"]
    ["tdeWalletPassword"  :  "<transparent data encryption wallet password of the primary database>"]
}

Request method

POST

Sample Body

 
{
    "primaryTargetName" : "dbname", 
    "primaryTargetType" : "oracle_database", 
    "standbyTargetName" : "sdbname", 
    "standbyTargetType" : "oracle_database", 
    "primaryDbCredsName" : "SYS", 
    "primaryHostCredsName" : "AIMEDB_N", 
    "standbyDbCredsName" : "SYS", 
    "standbyHostCredsName" : "AIMEDB_N", 
    "swapJobs" : "true", 
    "swapThresholds" : "true", 
    "tdeWalletCredsName" : "WC1"
}

Sample Response

 
{
    "status": "Succeeded",
    "submissionName": "dbname_DataguardSwitchover_091418163542",
    "executionGUID": "75D3A124B36D1A4DE0536A8A7B0A80E0",
    "databaseName": "dbname",
    "message": "Deployment procedure for switchover to dbname:oracle_database successfully submitted."
}

Supported Since Release

EM DB 13.3.2.0.0

Note:

Parameters listed within a square bracket are optional.

Table 15-2 Data Guard Switchover Parameters

Parameter Description
primaryTargetName

Primary database Enterprise Manager target name. Can be either a single-instance database or a cluster database.
primaryTargetType

Primary database target type. Allowed values are either single-instance database (oracle_database) or cluster database (rac_database).
standbyTargetName

Standby database Enterprise Manager target name. Can be either a single-instance database or a cluster database.
standbyTargetType

Standby database target type. Allowed values Allowed values are either single-instance database (oracle_database) or cluster database (rac_database).
primaryDbCredsName

Primary database named credential for a user with SYSDBA or SYSDG role. If this argument is not specified, preferred credential will be used.
primaryHostCredsName

Primary database host named credential for an operating system user who can access the primary database Oracle home. If this argument is not specified, preferred credential will be used.
standbyDbCredsName

Standby database named credential for a user with SYSDBA or SYSDG role. If this argument is not specified, preferred credential will be used.
standbyHostCredsName

Standby database host named credential for an operating system user who can access the standby database Oracle home.
swapJobs

Specifies that scheduled jobs on either the primary or standby database that are of a transferable type (Backup, RMAN Script, and SQL Script) will be moved to the other database after the switchover is complete. Only jobs that use global named or preferred credentials can be transferred. Default Value: Not enabled.
swapThresholds

Specifies that monitoring settings will be swapped between the primary and standby databases after the switchover is complete.

Default Value: Not enabled
tdeWalletCredsName

Transparent Data Encryption wallet credentials for the primary database. Use create_named_credential verb to create these credentials as shown below:

emcli create_named_credential -cred_name=WC1 -cred_type=GenericPassword -auth_target_type='<system>' -attributes="GENERIC_PASSWORD:<Primary Database TDE Wallet Password>"
tdeWalletPassword

Transparent Data Encryption wallet password for the primary database.

Convert Standby Database REST API

Table 15-3 Convert Standby Database

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/dataguard/convertStandby

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "dbTargetName" : "<standby target name>",
    "dbTargetType" : "oracle_database|rac_database",
    ["dbHostCredName" : "<standby database host credential name>",] 
    ["dbCredName" : "<standby database credential name>",]
    ["convertToDbRole" : "PHYSICAL STANDBY|SNAPSHOT STANDBY" ]
}

Sample Body

 
{
    "dbTargetName": "s11gfss",
    "dbTargetType":"oracle_database",
    "dbHostCredName": "GIMAN_N",
    "dbCredName": "SYSDBA_CREDS", 
    "convertToDbRole": "snapshot"
}

Sample Response

 
{
    "status":"Succeeded",
    "submissionName":"dbname_DGConvertStandby_092318020955",
    "executionGUID":"76815E6ABC9465F5E053C365F20A61AF",
    "databaseName":"dbname",
    "message":"Deployment procedure to convert the standby database successfully submitted."
}

Request method

POST

Supported Since Release

EM DB 13.3.2.0.0

Table 15-4 Convert Standby Database Parameters

Parameter Description
dbTargetName

Standby database Enterprise Manager target name. Can be either a single-instance database or a cluster database.
dbTargetType

Standby database target type. Allowed values Allowed values are either single-instance database (oracle_database) or cluster database (rac_database).
dbHostCredName

Standby database host named credential for an operating system user who can access the standby database Oracle home. If this argument is not specified, preferred credential will be used.
dbCredName

Standby database named credential for a user with SYSDBA or SYSDG role. If this argument is not specified, preferred credential will be used.
convertToDbRole

Standby database role to be converted to given role. Possible values are Physical Standby and Snapshot Standby.

Backup and Recovery

Configure Backup REST API

Table 15-5 Configure Database to Send Backup

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/backup/configure

Request header

Authorization: basic

Content-Type: application/json

Body1

Configure database to be protected by a Recovery Appliance, with the ability to send backups to the Recovery Appliance.

{
    "dbTargetName":"<database target name>",
    "dbTargetType":"oracle_database|rac_database",
    "configureRABackup":"true"
    "raTargetName":"<Recovery Appliance target name>"
    "raUser":"<Recovery Appliance database user name>"
    ["dbCredName":"<database named credential>"],
    ["dbHostCredName":"<database host named credential>"],
    ["enableRedoShip":"true"]
    ["forceBackupModuleInstall":"true"]
}

Sample Body

 
{
    "configureRABackup":"true",
    "dbTargetType":"oracle_database",
    "dbTargetName":"zd2", 
    "raTargetName":"ra",
    "raUser":"orsadmin",
    "dbCredName": "RMAN",
    "dbHostCredName":"AIMEDB_N"
}

Sample Response

 
{
    "status":"Succeeded",
    "submissionName":"BACKUP_CONFIG_011419155235",
    "executionGUID":"7F69505339B4413FE053EB987B0A226E",
    "databaseName":"zd2",
    "message":"Deployment procedure to configure high availability settings to database successfully submitted."
}

Body2

Configure database to send backups to Oracle Database Backup Cloud Service.

{
    "dbTargetName":"<database target name>",
    "dbTargetType":"oracle_database|rac_database",
    "configureCloudBackup":"true",
    ["dbCredName":"<database named credential>"],
    ["dbHostCredName":"<database host named credential>"],
    ["forceBackupModuleInstall":"true"]
    ["cloudAccount":"<Hybrid Cloud Console cloud service account name>"]
}

Sample Body

 
{
    "configureCloudBackup":"true",
    "dbTargetType":"oracle_database", 
    "dbTargetName":"dgprim", 
    "dbHostCredName":"GIMAN_N", 
    "dbCredName": "SYS",
    "cloudAccount":"endpoint:https://storage.example.com/v1/Storage-emdev2;identityDomain:emdev2;username:xxxx;password:xxxx;container:db19_cntr"
}

Sample Response

 
{
    "status":"Succeeded",
    "submissionName":"OPC_BACKUP_CONFIG_010919120757",
    "executionGUID":"7F000E71E0DE624BE053EB987B0ADF02",
    "databaseName":"dgprim",
    "message":"Deployment procedure to configure high availability settings to database successfully submitted."
}

Body3

Install an RMAN Backup Module in the Oracle Home of the specified database or install the Recovery Appliance file system backup agent on the host of the database.

{
    "dbTargetName":"<database target name>",
    "dbTargetType":"oracle_database|rac_database",
    "installSoftware":"true",
    "moduleType":"ra|cloud",
    "installBackupModule":"true",
    ["dbHostCredName":"<database host named credential>"],
    ["forceBackupModuleInstall":"true"]
}

Sample Body

 
{
    "installSoftware":"true",
    "dbTargetType":"oracle_database", 
    "dbTargetName":"dgprim", 
    "moduleType":"cloud",
    "installBackupModule":"true",
    "dbHostCredName":"GIMAN_N"
}

Sample Response

 
{
    "status":"Succeeded",
    "submissionName":"INSTALL_BKP_MODULE_011019111214",
    "executionGUID":"7F1502D6C5CB5E53E053EB987B0AA38E",
    "databaseName":"dgprim",
    "message":"Deployment procedure to configure high availability settings to database successfully submitted."
}

Request method

POST

Supported Since Release

EM DB 13.3.2.0.0

Table 15-6 Configure Backup Parameters

Parameter Description
Body1
dbTargetName

A single-instance or cluster database target name for the database that will be configured to send backups to the Recovery Appliance.
dbTargetType

The type of the target specified by "dbTargetName", either a single-instance database (oracle_database) or a cluster database (rac_database).
configureRABackup

Configure database to be protected by a Recovery Appliance, with the ability to send backups to the Recovery Appliance. Any one option configureRABackup, configureCloudBackup or installSoftware must be provided. The possible value is "true".

dbCredName

The name of an existing Enterprise Manager database named credential that can be used to connect to the specified target database. If this argument is not specified, preferred credential will be used.
dbHostCredName

The name of an existing Enterprise Manager database host named credential that can be used to run operating system commands on the specified target database hosts. The credential should be for a user that has write permission for Oracle Home. If this argument is not specified, preferred credential will be used.
raTargetName

The target name of the Recovery Appliance that the specified database will be configured to send backups to.
raUser

The name of the Recovery Appliance database user that will be used by the specified database to send backups to and ship redo to the Recovery Appliance. This must be a virtual private catalog user, not the Recovery Appliance administrator user.
enableRedoShip

Enable realtime redo transport to the Recovery Appliance from the specified target database.

Default value: True

forceBackupModuleInstall

Force installation of the version of the Recovery Appliance Backup Module stored in the Enterprise Manager software library into the Oracle Home of the specified target database, regardless of whether there is an existing Backup Module installed in the Oracle Home. This will overwrite any existing Backup Module, so this option should be selected only if it is known that the Backup Module version in the software library is at the same or later version than the version installed on the specified target database. If this option is not specified, the Backup Module will be installed only if there is no existing Backup Module installed in the Oracle Home.

Default value: True

Body2
dbTargetName

A single-instance or cluster database target name for the database that will be configured to send backups
dbTargetType

The type of the target specified by "dbTargetName", either a single-instance database (oracle_database) or a cluster database (rac_database).

configureCloudBackup

Configure database to send backups to Oracle Database Backup Cloud Service. Any one option configureRABackup, configureCloudBackup or installSoftware must be provided. The possible value is "true".

dbCredName

The name of an existing Enterprise Manager database named credential that can be used to connect to the specified target database. If this argument is not specified, preferred credential will be used.

dbHostCredName

The name of an existing Enterprise Manager database host named credential that can be used to run operating system commands on the specified target database hosts. The credential should be for a user that has write permission for Oracle Home. If this argument is not specified, preferred credential will be used.
forceBackupModuleInstall

Force installation of the version of the Oracle Database Cloud Backup Module stored in the Enterprise Manager software library into the Oracle Home of the specified target database, regardless of whether there is an existing Backup Module installed in the Oracle Home. This will overwrite any existing Backup Module, so this option should be selected only if it is known that the Backup Module version in the software library is at the same or later version than the version installed on the specified target database. If this option is not specified, the Backup Module will be installed only if there is no existing Backup Module installed in the Oracle Home.

cloudAccount

The name of a cloud account configured under the Enterprise Manager Hybrid Cloud Setup console. All information needed to connect to the Backup Service will be obtained from the account and its associated Backup Service settings, including the service name, identity domain, username, password, and container (optional). If this argument is not specified, the global cloud account settings configured in the Database Backup Cloud Service Settings page will be used. (This argument is applicable only if the Hybrid Cloud Setup console has been used to configure accounts and Backup Service settings.). This is field should be provided with "configureCloudBackup" option.

Example- "cloudAccount":"endpoint:https://storage.oracle.com/ Storageemdev2;identityDomain:xxx;username:xxxx;password:xxxx;contai ner:xxxx"

Body3
dbTargetName

Same as -configureRABackup usage above.
dbTargetType

Same as -configureRABackup usage above.
installSoftware

Install an RMAN Backup Module in the Oracle Homes of one or more databases or install the Recovery Appliance file system backup agent on the host of one database. Any one option configureRABackup, configureCloudBackup or installSoftware have be provided. The possible value is "true".

dbHostCredName

Same as -configureRABackup usage above.
installBackupModule

Install the version of the Backup Module (of the type specified by the moduleType option) stored in the Enterprise Manager software library in the Oracle Home of the specified target database. By default, the module will be installed only if there is not an existing module in the database Oracle Home, unless the force_backup_module_install flag is specified.
moduleType

The type of RMAN backup module to be installed. Possible values:

  • ra: Recovery Appliance Backup Module
  • cloud: Oracle Database Cloud Backup Module
forceBackupModuleInstall

Used in combination with installBackupModule option. Same as -configureRABackup usage above.

Backup REST API

This section provides the details of the Backup REST API.

Table 15-7 Backup

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/backup

Request header

Authorization: basic

Content-Type: application/json

Body

Configure database to be protected by a Recovery Appliance, with the ability to send backups to the Recovery Appliance.

{
    "dbTargetName":"<database target name>",
    "dbTargetType":"oracle_database|rac_database|oracle_cloud_dbcs",
    ["dbCredName":"<database named credential>"],
    ["dbHostCredName":"<database host named credential>"],
    ["scope":"wholeDB|tablespace|datafile|archivedLog|,recoveryFilesOnDisk|cdbRoot|pluggableDbs"],
    ["scopeValue":"<comma-separated list of values>"],
    ["backupType":"full|incr0|incr1" ["incrType:"diff|cumulative"]],
    ["destinationMedia":"disk|tape|ra|cloud"],
    ["skipBackupArchivedLogs":"true|false"],
    ["deleteArchivedLogsAfterBackup":"true|false"],
    ["deleteObsolateBackups":"true|false"],
    ["maxFilesPerSet":"<numeric value>"],
    ["maxCorruptions":"<numeric value>"],
    ["sectionSize":"<numeric value>"],
    [["backupEncryptionMode":"wallet|password|both"],
    ["rmanEncryptionCredName":"<RMAN encryption named credential>"],
    ["encryptionAlogrithm":"AES128|AES192|AES256"]],
    ["cloudAccount":"<cloud storage container url with endpoint, identityDomain, username,passoword and container name>"]
}

Request method

POST

Supported Since Release

EM DB 13.3.2.0.0

Sample Body

 
{
    "dbTargetType":"oracle_database", 
    "dbTargetName":"dgprim", 
    "dbHostCredName":"GIMAN_N", 
    "dbCredName": "SYS", 
    "scope":"wholeDB", 
    "backupType":"full", 
    "backupEncryptionMode":"password",
    "encryptionAlogrithm":"AES128",
    "rmanEncryptionCredName":"WC1",
    "cloudAccount":"endpoint:https://storage.example.com/v1/Storage-emdev2;identityDomain:emdev2;username:xxxx;password:xxx;container:db19_cntr", 
    "destinationMedia":"cloud", 
    "maxFilesPerSet":2
}

Sample Response

 
{
    "status":"Succeeded",
    "submissionName":"Backup_DB_from_OMC_010919152109",
    "executionGUID":"7F044AF2D1F60905E053EB987B0A569B",
    "databaseName":"dgprim",
    "message":"Backup to Oracle Cloud deployment procedure successfully submitted."
}

Table 15-8 Backup Parameters

Parameter Description
Body1
dbTargetName

A single-instance, cluster database, or database cloud service target name for the database that will be backed up.
dbTargetType

The type of the target specified by "dbTargetName", either a single-instance database (oracle_database), a cluster database (rac_database), or a database cloud service (oracle_cloud_dbcs).
dbCredName

The name of an existing Enterprise Manager database named credential that can be used to connect the specified target database. If the operating system user specified by the "dbHostCredName" argument is a member of the operating system DBA group, the database credential can specify a Normal role user. Otherwise, the database credential must specify a SYSDBA role user. If this argument is not specified, then preferred credential will be used.
dbHostCredName

The name of an existing Enterprise Manager database host named credential that can be used to run the RMAN command on the specified target database host. If this argument is not specified, then preferred credential will be used.
scope

The scope of the backup. If this argument is not specified, the default value is wholeDB. Possible values are:

  • wholeDB: All data files in the database.
  • tablespace: One or more data files associated with the tablespace name.
  • datafile: One or more data files.
  • archivedLog: Exactly one copy of each distinct log sequence number.
  • recoveryFilesOnDisk: All recovery files on disk, whether they stored in the fast recovery area or other locations on disk.
  • cdbRoot: The data files in the whole container root.
  • pluggableDbs: The data files in one or more pluggable databases.
scopeValue

A comma-separated list of values to back up. It is required when the -scope value is tablespace|datafile|pluggableDbs.

backupType

The type of backup. If this argument is not specified, the default value is full. Possible values:

  • full: Back up all data blocks in data files being backed up.
  • incr0: Incremental level 0. Similar to a full backup, but can be used as the base of an incremental backup strategy.
  • incr1: Incremental level 1. Back up only changed blocks.
incrType

The type of incremental backup. Used in combination with -"backupType":"incr". If this argument is not specified, the default value is diff. Possible values:

  • diff: Back up blocks updated since the most recent level 0 or level 1 incremental backup.
  • cumulative: Back up all blocks changed since the most recent level 0 backup.
destinationMedia

The destination media for this backup. If this argument is not specified, the default value is disk. Possible values:

  • disk: Backup to disk (not allowed when - scope="recoveryFilesOnDisk").
  • tape: Backup to a SBT (system backup to tape) device.
  • ra: Backup to a Recovery Appliance.
  • cloud: Backup to Database Backup Cloud Service.
backupEncryptionMode

Specify to encrypt the backup using the Oracle Encryption Wallet, a user-supplied password, or both. Possible values:

  • wallet: Oracle Encryption Wallet
  • password: user-supplied password
  • both: Oracle Encryption Wallet and user-supplied password

This option can be specified when -scope="wholeDB| tablespace|datafile|archivedLog|recoveryFilesOnDisk|cdbRoot| pluggableDbs".
rmanEncryptionCredName

The name of an existing Enterprise Manager generic named credential that contains the encryption password. Required when "backupEncryptionMode":"password" is specified.
encryptionAlogrithm

The name of the encryption algorithm to use when encrypting backups. Used in combination with "backupEncryptionMode". Possible values are AES128, AES192, and AES256. If this argument is not specified, the default value is AES256.
skipBackupArchivedLogs

Do not back up all archived logs on disk that have not been backed up. The default behavior if this argument is not specified is to back up all archived logs that have not been backed up.Possible values are true|false. This option can be specified when -scope="wholeDb|tablespace|datafile| cdbRoot|pluggableDbs".
delete_Archived_Logs_After_Backup

Delete all archived logs from disk after they are successfully backed up. Ignored if "-skip_Backup_Archived_Logs" is specified. Possible values are true|false.

This option can be specified when -scope="wholeDB| tablespace|datafile|cdbRoot|pluggableDbs".

deleteObsolateBackups

Delete backups that are no longer required to satisfy the retention policy. Possible values are true|false.This option can be specified when -scope="wholeDB|tablespace| datafile|cdbRoot|pluggableDbs".
maxFilesPerSet

The maximum number of files to include in each backup set. This option can be specified when -scope="wholeDB| tablespace|datafile|archivedLog|cdbRoot|pluggableDbs".
maxCorruptions

The maximum number of physical corruptions allowed in data files. This option can be specified when -scope="datafile".
sectionSize

The size in MB of each backup section produced during a data file backup, resulting in a multi-section backup where each backup piece contains one file section. This option cannot be used if the Maximum Backup Piece Size is set in the RMAN configuration.This option can be specified when - scope="wholeDB|tablespace|datafile|archivedLog|cdbRoot| pluggableDbs".

cloudAccount

The name of a cloud account configured under the Enterprise Manager Hybrid Cloud Setup console. All information needed to connect to the Backup Service will be obtained from the account and its associated Backup Service settings, including the service name, identity domain, username, password, and container (optional). If this argument is not specified, the global cloud account settings configured in the Database Backup Cloud Service Settings page will be used. (This argument is applicable only if the Hybrid Cloud Setup console has been used to configure accounts and Backup Service settings.).

Example - "cloudAccount":"endpoint:https://storage.oracle.com/ Storageemdev2;identityDomain:xxx;username:xxxx;password:xxxx;contai ner:xxxx"