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.
|
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.
|
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 |
|
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 |
|
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 |
|
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 |
|
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.
|
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] |