1. Cloud Control Database Lifecycle Management Administrator's Guide
  2. Database Provisioning
  3. Fast-Start Failover REST API

16 Fast-Start Failover REST API

This chapter provides details of the REST APIs for Fast-Start Failover and Observers supported in Enterprise Manager. When Fast-Start Failover is enabled, the Data Guard broker automatically fails over to a synchronized standby site in the event of a disaster at the primary site, requiring no intervention by the DBA. In addition, applications are automatically notified of the role transition.

Fast-Start Failover Management REST API

Fast-Start Failover Management REST API

Table 16-1 Fast-Start Failover

Feature Description
URL https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/dataguard/configure/fsfo
Request header

Authorization: Basic

Content-Type: application/json
Body 
{
    "action" : "<edit | enable | disable>",
    "primary" : {
        "dbTargetName" : "<primary database target name>",
        "dbTargetType" : "oracle_database | rac_database",
        "dbCredName" : "<primary database credential name>",
        "dbHostCredName" : "<primary database host credential name>",
        "dbGIHostCredName" : "<grid infrastructure credential name>"
    },
    "candidateFSFOTargets" : [
        {
            "dbTargetName" : "<standby database target name>",
            "dbTargetType" : "oracle_database | rac_database",
            "dbCredName" : "<standby database credential name>",
            "dbHostCredName" : "<standby database host credential name>",
            "dbGIHostCredName" : "<grid infrastructure credential name>"
        }],
    "observer" : {
            "hostName" : "<observer host name>",
            "oracleHome" : "<observer oracle home>",
            "hostCredName" : "<observer host credential name>"
    },
    "alternateObserver" : {
            "hostName" : "<alternate observer host name>",
            "oracleHome" : "<alternate observer oracle home>",
            "hostCredName" : "<alternate observer host credential name>"
    },
    "failoverThreshold" : "<failover threshold>",
    "lagLimit" : "<lag limit>",
    "failoverConditions" : "<failover conditions>",
    "autoReinstatePrimary" : "Yes | No",
    "autoShutdownPrimary" : "Yes | No"
}
Notes Observers and alternate observers are optional.
Request method POST
Sample Response 
{
    "status" : "Succeeded",
    "submissionName" : "DG_FAST_START_FAIL_OVER_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment Procedure for configuring fast-start failover of the Data Guard configuration determined from the primary database <primary database name> is successfully submitted."
}
Supported Since Release EM DB 13.4

Fast-Start Failover Parameters

Parameter Description Required Value | Default Value
action Operation to be performed on the fast-start failover configuration.
  • enable : Enable fast-start failover.
  • disable : Disable fast-start failover and stop the observer.
  • edit : Change the fast-start failover target database and thresholds, and start or restart the observer process.
Required edit | enable | disable
dbTargetName Primary or standby database Enterprise Manager target names. Required N/A
dbTargetType Primary or standby database target types. Required oracle_database | rac_database
dbCredName Primary or standby database named credential for a user with SYSDBA or SYSDG role. Optional Preferred credential will be used.
dbHostCredName Primary or standby database host named credential for an operating system user who can access the database Oracle home. Optional Preferred credential will be used.
dbGIHostCredName Grid Infrastructure named credential for an operating system user who can access the grid infrastructure Oracle home of the database. Optional N/A
hostName Discovered host where Enterprise Manager will start the observer or alternate observer. Required N/A
oracleHome Oracle home on the observer or alternate host (as specified by "hostName") from which Enterprise Manager will start the observer or alternate observer.. Required N/A
observer A DGMGRL (Data Guard command line interface) client that continuously monitors the primary and target standby databases, evaluates whether failover is necessary, and initiates a fast-start failover when selected conditions occur. Required N/A
alternateObserver Enterprise Manager supports the automatic restart of an alternate observer on a different host if it detects that the observer process had failed in the earlier host. Required N/A
hostCredName Observer or alternate observer host named credential for an operating system user who can access the observer Oracle home. Required N/A
failoverThreshold Amount of time in seconds the primary database must be out of contact with the observer and the standby database before a fast-start failover is initiated. Optional 30 Seconds.
lagLimit Amount of time in seconds the standby database is allowed to fall behind the primary database, beyond which a fast-start failover will not be allowed. Optional 30 Seconds.
failoverConditions A comma separated list of failover conditions which should cause a fast-start failover if detected on the primary database.
  • 1 - Corrupted Controlfile
  • 2 - Corrupted Dictionary
  • 3 - Inaccessible Logfile
  • 4 - Stuck Archiver
  • 5 - Datafile Offline
 Optional 1, 2, 5
autoReinstatePrimary Causes the former primary database to be automatically reinstated if a fast-start failover was initiated because the primary database was either isolated or had crashed. Optional Yes | NoDefault: Yes
autoShutdownPrimary Causes the primary database to automatically shut down if fast-start failover is enabled. Optional Yes | No

Observer Management REST API

Note:

This REST API is applicable to Oracle Database version 12.2 and higher.

Configure Multiple Observers for a Data Guard Configuration

Table 16-2 Start Observers

Feature Description

URL

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

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "action" : "start",
    "primary" : {
        "dbTargetName" : "<primary database target name>",
        "dbTargetType" : "oracle_database | rac_database",
        "dbCredName" : "<primary database credential name>",
        "dbHostCredName" : "<primary database host credential name>"
    },
    "observers" : [
        {
            "name" : "<observer name>",
            "hostName" : "<host name>",
            "oracleHome" : "<oracle home location>",
            "hostCredName" : "<host credential name>",
            "hostWalletCredName" : "<oracle wallet credential name>",
            "isMaster" : "Y | N",
            "runTimeDataFile" : "<runtime data file path>",
            "logFile" : "<observer log file path>"
        }
    ]
}
Notes A maximum of 3 observers can be assigned.

Sample Response

 
{
    "status" : "Succeeded",
    "submissionName": "ConfigureObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to start the observer(s) for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
                 
}

Request method

POST

Supported Since Release

EM DB 13.4

Table 16-3 Delete, Show, or Stop All Observers

Feature Description

URL

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

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "action" : "<delete_alternate_observer | show | stopall>",
    "primary" : {
        "dbTargetName" : "<primary database target name>",
        "dbTargetType" : "oracle_database | rac_database",
        "dbCredName" : "<primary database credential name>",
        "dbHostCredName" : "<primary database host credential name>"
    }
}

Sample Response

Show

{
    "status": "Succeeded",
    "submissionName" : "ShowObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to list the observer(s) for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
}

Delete Alternate Observer

{
    "status" : "Succeeded",
    "submissionName" : "DeleteAlternateObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to delete the alternate observer for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
}

Stop All

{
    "status" : "Succeeded",
    "submissionName" : "StopObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to stop the observer(s) for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
}

Request method

POST

Supported Since Release

EM DB 13.4

Table 16-4 Stop Observers

Feature Description

URL

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

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "action" : "stop",
    "primary" : {
        "dbTargetName" : "<primary database target name>",
        "dbTargetType" : "oracle_database | rac_database",
        "dbCredName" : "<primary database credential name>",
        "dbHostCredName" : "<primary database host credential name>"
    }
    "observers" : [
        {"name" : "<observer 1 name>"},
        {"name" : "<observer 2 name>"},
        {"name" : "<observer 3 name>"}
    ]
}

Sample Response

 
{
    "status" : "Succeeded",
    "submissionName": "StopObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to stop the observer(s) for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
}

Request method

POST

Supported Since Release

EM DB 13.4

Table 16-5 Set Master Observer

Feature Description

URL

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

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "action" : "setMaster",
    "primary" : {
        "dbTargetName" : "<primary database target name>",
        "dbTargetType" : "oracle_database | rac_database",
        "dbCredName" : "<primary database credential name>",
        "dbHostCredName" : "<primary database host credential name>"
    }
    "masterObserver" : "<master observer name>"
}

Sample Response

 
{
    "status" : "Succeeded",
    "submissionName": "SetMasterObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to set the master observer for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
}

Request method

POST

Supported Since Release

EM DB 13.4

Table 16-6 Observer Parameters

Parameter Description Required Value | Default Value
action
The action the API will execute. All the operations are mutually exclusive. They can't be combined and must be executed separately.
  • start : Starts one or more fast-start failover observers on the specified hosts and Oracle homes for the Data Guard configuration associated with the specified primary database.
  • delete_alternate_observer : Deletes the Enterprise Manager alternate observer and its associated corrective action job. The Enterprise Manager alternate observer feature is not supported for Oracle Database version 12.2 and higher.
  • show : Displays the list of observers configured for a Data Guard configuration associated with the specified primary database.
  • stop : Stops the respective observer(s) for a Data Guard configuration associated with the specified primary database.
  • stopall : Stops all the observers.
  • setMaster : Configures the master observer for a Data Guard configuration associated with the specified primary database.
Required start | delete_alternate_observer | show | stop | stopall | setMaster
dbTargetName Primary database Enterprise Manager target name. Required  
dbTargetType

Primary database target type.

 Required oracle_database | rac_database
dbCredName

Primary database named credential for a user with SYSDBA or SYSDG role.

 [OPTIONAL] Preferred credentials will be used.
dbHostCredName

Primary database host named credential for an operating system user who can access the primary database Oracle home.

[OPTIONAL] Preferred credentials will be used.
name Observer name. Required  
hostName Host name where observer will be started. Required  
oracleHome Oracle home location on the host where the observer will be started. Required  
hostCredName Host named credential for user who can access the observer Oracle home. Required  
hostWalletCredName Named credential of the Oracle wallet configured in the observer Oracle home. Required  
isMaster

Defines if the observer is master.

 [OPTIONAL] Y | N
masterObserver

Required for Set Master Observer

Defines the master observer.

 [OPTIONAL]  
runTimeDataFile

Runtime data file path and name for the observer. If not specified, the file fsfo.dat will be created under the Oracle base.

 [OPTIONAL]  
logFile

The full path of the observer log file.

 [OPTIONAL]