7.8 Configuring Oracle REST Data Services (ORDS)

Note:

In the current release, REST services are not supported on Microsoft Windows.

7.8.1 Using Oracle Autonomous Health Framework Compliance Over REST

Oracle ORAchk and Oracle EXAchk include full REST support allowing invocation and query over HTTPS.

7.8.1.1 check

Use GET requests to run a health check run for the specified check IDs.

Syntax

/check/{check_id1,check_id2}

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"B2PKK9RR9M7MYJPRN8", "Status":"SUBMITTED" }]

Usage Notes

Specify a profile, or a comma-delimited list of check IDs.

Example 7-17 check

-bash-4.2$ curl -i -X GET -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/check/E94589BC1AC24CFBE04312C0E50A3849

 
[{"ID":"B2PKK9RR9M7MYJPRN8","Status":"SUBMITTED"}]

7.8.1.2 checktfafaileduploads

Use GET requests to report if any Oracle Autonomous Health Framework service uploads failed.

Syntax

/checktfafaileduploads

Returns

If no collection failed to upload, then returns:

[{ "Msg":"There are no Failed collections under ORDS directory." }]

Or, prints the list of collections that failed to upload.

Usage Notes

You need not provide input to use this API.

Example 7-18 checktfafaileduploads

bash-4.1# curl -i -X GET -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/checktfafaileduploads
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:04:58 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

[{"Msg":"There are no Failed collections under ORDS directory."}]

7.8.1.3 checktfaupload

Use GET requests to report if a connection can be made to upload to Oracle Autonomous Health Framework service.

Syntax

/checktfaupload

Returns

Returns JSON similar to:

[{ "ID":"ZFZLH06WOLE3L92PQI", "Status":"SUBMITTED" }]

Usage Notes

Use the status API to query the status of the submitted job.

Use the getinfo API to view the Oracle Autonomous Health Framework upload status after the status of the submitted API is COMPLETED.

Example 7-19 getinfo

With getinfo, returns:

[{"Msg":"Environment is not set for uploading results to TFA."}]

7.8.1.4 download

Use GET requests to download the collection result for the specified job ID.

Syntax

/download/{job_id}

Returns

Returns the zip binary for the collection result.

Usage Notes

Specify the job ID for which you want to download the collection result.

If you specify a purged ID or an invalid ID, then the error message will be in the downloaded file.

Example 7-20 download

# curl -X GET -k --user tfarest:password  
https://node1.example.com:9090/ords/tfactl/orachk/download/0K5Y5MAX2SD5CPP6SH -O
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 54854    0 54854    0     0   220k      0 --:--:-- --:--:-- --:--:--  221k

# unzip -qo 0K5Y5MAX2SD5CPP6SH

# ls -l
-rw-r--r--. 1 root root 54854 Sep  3 03:30 0K5Y5MAX2SD5CPP6SH
drwxr-xr-x. 1 root root   288 Sep  3 03:30 orachk_node1_orcl2_test_090319_032952_0K5Y5MAX2SD5CPP6SH

7.8.1.5 getinfo

Use GET requests to report the status of the specified job ID.

Syntax

/getinfo/{job_id}

Returns

Returns JSON similar to if the ID does not exist:

[{ "Status":"Either the ID entered is invalid or the wallet has been purged." }]

Or, returns the repair command if the ID exists.

Usage Notes

Specify the job ID for which you want to check the status.

Example 7-21 getinfo

-bash-4.1# curl -i -X GET -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/getinfo/FJELUT7XYM3AKOE1R4 HTTP/1.1 200 OK Date: Thu, 19 Jul 2018 10:15:34 GMT 
Content-Type: text/html X-Frame-Options: SAMEORIGIN Transfer-Encoding: chunked

Repair Command:

alter database datafile '+DATAC1/RAC12C/DATAFILE/sysaux.314.936528199' autoextend on maxsize unlimited;

7.8.1.6 gettfaupload

Use GET requests to report the Oracle Autonomous Health Framework service upload settings.

Syntax

/gettfaupload

Returns

Lists the values of three environment variables: RAT_TFA_URL, RAT_TFA_USER, and RAT_TFA_PASSWORD.

Usage Notes

You need not provide input to use this API.

Example 7-22 gettfaupload

bash-4.1# curl -i -X GET -k -u tfarest:password
https://node1.example.com:9090/ords/tfactl/orachk/gettfaupload
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:07:24 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

RAT_TFA_URL =  https://tfa.example.com/tfa/ws/orachk/
RAT_TFA_USER =  orachkadmin
RAT_TFA_PASSWORD = ********

After unsettfaupload API, use the gettfaupload API to recheck the values:

-bash-4.1# curl -i -X GET -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/gettfaupload
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:10:10 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

RAT_TFA_URL is not set in the wallet 
RAT_TFA_USER is not set in the wallet 
RAT_TFA_PASSWORD is not set in the wallet

7.8.1.7 listcollections

Use GET requests to get the list of Oracle ORAchk collections generated through REST.

Syntax

/tfactl/orachk/listcollections

Returns

Returns the list of Oracle ORAchk collections generated through REST.

Example 7-23 listcollections

# curl -k --user tfarest:password  
https://node1.example.com:9090/ords/tfactl/orachk/listcollections | sed s/\<BR\>/\\n/g 
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   581    0   581    0     0   3906      0 --:--:-- --:--:-- --:--:--  3925
List of collections:
/u02/test-user/oracle.ahf/data/node1/tfa/rest/ords/orachk_node1_orcl2_bill_test_090319_034049_BTGP96ZYH45P5LHB86.zip
/u02/test-user/oracle.ahf/data/node1/tfa/rest/ords/orachk_node1_orcl2_bill_test_090319_032952_0K5Y5MAX2SD5CPP6SH.zip
/u02/test-user/oracle.ahf/data/node1/tfa/rest/ords/orachk_node1_orcl2_bill_test_090319_034245_WH9UWZRN9PKPDNKZCL.zip
/u02/test-user/oracle.ahf/data/node1/tfa/rest/ords/orachk_node1_orcl2_bill_test_090319_033349_L05Y28DSOTZ9N73HO0.zip

7.8.1.8 profile

Use GET requests to run a health check run for the specified profiles.

Syntax

/profile/{profile1},{profile2}

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"DMBLMBTB2M2H1QCQIS", "Status":"SUBMITTED" }]

Usage Notes

Specify a profile, or a list of profiles delimited by forward slash (/).

Example 7-24 profile

-bash-4.2$ curl -i -X GET -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/profile/asm

HTTP/1.1 200 OK Date: Thu, 05 Apr 2018 10:50:00 GMT Content-Type: text/html X-Frame-Options: 
SAMEORIGIN Transfer-Encoding: chunked Server: Jetty(9.2.z-SNAPSHOT) 
[{"ID":"DMBLMBTB2M2H1QCQIS","Status":"SUBMITTED"}]

7.8.1.9 showrepair

Use GET requests to report the showrepair command for the specified check.

Syntax

/showrepair/{check_id}

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"ZFZLH06WOLE3L92PQI", "Status":"SUBMITTED" }]

Usage Notes

Specify the check ID for which you want to report the showrepair command.

Example 7-25 showrepair

-bash-4.1# curl -i -X GET -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/showrepair/9ECBA2152E92F6B1E040E50A1EC00DFB
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:13:54 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

[{"ID":"FJELUT7XYM3AKOE1R4","Status":"SUBMITTED"}]
-bash-4.1# curl -i -X GET -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/status/FJELUT7XYM3AKOE1R4
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:15:00 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

[{"Msg":"Status of FJELUT7XYM3AKOE1R4 is  COMPLETED"}]

7.8.1.10 start_client

Use POST requests to run a diff of the specified collection results.

Syntax

/start_client

Returns

Returns JSON similar to:

[{ "ID":"ZFZLH06WOLE3L92PQI", "Status":"SUBMITTED" }]

The status API can be used to query the status of the submitted job ID. Then you can use the download API to download diff report using the same job ID.

Usage Notes

JSON input:

[{ "-diff":"collection_zip_1 collection_zip_2" }]

Example 7-26 start_client

-bash-4.2$ curl -i -X POST -H "Content-Type: application/json" -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/start_client -d '[{"-diff":"orachk_myhost69_apxcmupg_062118_025029_N1O498NX877LYO5FE3.zip 
orachk_myhost69_apxcmupg_062118_030527_ICMOWECU1UKF0R0VTO.zip"}]'

7.8.1.11 start_client

Use GET requests to run a normal health check run.

Syntax

/start_client

Returns

Returns JSON showing the job ID similar to:

[{
"ID":"UCTW5MLN7O1V1HPG8U",
"Status":"SUBMITTED"
}]

Usage Notes

You need not provide input to use this API.

Example 7-27 start_client

-bash-4.2$ curl -i -X GET -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/start_client

HTTP/1.1 200 OK Date: Thu, 05 Apr 2018 11:53:14 GMT Content-Type: text/html X-Frame-Options: 
SAMEORIGIN Transfer-Encoding: chunked Server: Jetty(9.2.z-SNAPSHOT) 
[{"ID":"UCTW5MLN7O1V1HPG8U","Status":"SUBMITTED"}]

7.8.1.12 start_client

Use POST and GET requests to run a normal health check run using specific arguments.

Syntax

/start_client

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"UCTW5MLN7O1V1HPG8U", "Status":"SUBMITTED" }]

Usage Notes

Specify any Oracle ORAchk or Oracle EXAchk arguments and their corresponding values.

Example 7-28 JSON input

[{
"-clusternodes":"busm1c1,busm1c2",
"-ibswitches":"busm1sw-ibs0,busm1sw-iba0,busm1sw-ibb0"
}]

Example 7-29 start_client

# curl -i -X POST -H "Content-Type: application/json" -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/start_client -d '[{"-clusternodes":"busm1c1,busm1c2","-ibswitches":"busm1sw-ibs0,busm1sw-iba0,busm1sw-ibb0"}]
# curl -X POST -k --user tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/start_client -d '{"-check": "81586F6DEC0DB43CE053D398EB0AF1EA", "-showpass", ""}'
[{"ID":"0K5Y5MAX2SD5CPP6SH","Status":"SUBMITTED"}]
# curl -X GET -k --user tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/check/81586F6DEC0DB43CE053D398EB0AF1EA
[{"ID":"BTGP96ZYH45P5LHB86","Status":"SUBMITTED"}]
# curl -X GET -k --user tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/profile/asm
[{"ID":"WH9UWZRN9PKPDNKZCL","Status":"SUBMITTED"}]

7.8.1.13 status

Use GET requests to report the status on the specified job ID.

Syntax

/status/{job_id}

Returns

Returns JSON showing the job ID similar to:

[{ "Status of DMBLMBTB2M2H1QCQIS is SUBMITTED" }]

The status moves from SUBMITTED to RUNNING to COMPLETED.

Usage Notes

Specify the job ID for which you want to find the status.

Example 7-30 status

# curl -i -X GET -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/status/DMBLMBTB2M2H1QCQIS

HTTP/1.1 200 OK Date: Thu, 05 Apr 2018 10:51:16 GMT Content-Type: text/html X-Frame-Options: 
SAMEORIGIN Transfer-Encoding: chunked Server: Jetty(9.2.z-SNAPSHOT) 
[{"Status of DMBLMBTB2M2H1QCQIS is SUBMITTED"}]
# curl -X GET -k --user tfarest:password  
https://node1.example.com:9090/ords/tfactl/orachk/status/0K5Y5MAX2SD5CPP6SH
[{"Msg":"Status of 0K5Y5MAX2SD5CPP6SH is RUNNING"}]
# curl -X GET -k --user tfarest:password  
https://node1.example.com:9090/ords/tfactl/orachk/status/0K5Y5MAX2SD5CPP6SH
[{"Msg":"Status of 0K5Y5MAX2SD5CPP6SH is COMPLETED"}]
# curl -X GET -k --user tfarest:password  
https://node1.example.com:9090/ords/tfactl/orachk/status/0K5Y5MAX2SD5CPP6SH
[{"Msg":"Status of 0K5Y5MAX2SD5CPP6SH is COMPLETED"}]

7.8.1.14 unsettfaupload

Use GET requests to unset all of the Oracle Autonomous Health Framework service upload settings, or a particular setting.

Syntax

/unsettfaupload/all
/unsettfaupload/RAT_TFA_USER

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"ZFZLH06WOLE3L92PQI", "Status":"SUBMITTED" }]

Usage Notes

Specify all to unset all of the three environment variables, RAT_TFA_URL, RAT_TFA_USER, and RAT_TFA_PASSWORD or, just specify an environment variable to unset it.

Example 7-31 unsettfaupload

-bash-4.1# curl -i -X GET -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/unsettfaupload/all
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:08:30 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

[{"ID":"Z8P9DHA8VV3PUOVQTV","Status":"SUBMITTED"}]

7.8.1.15 uploadtfafailed

Use GET requests to reattempt to upload all previously failed uploads to Oracle Autonomous Health Framework service.

Syntax

/uploadtfafailed/all

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"ZFZLH06WOLE3L92PQI", "Status":"SUBMITTED" }]

Usage Notes

You need not provide input to use this API.

Example 7-32 uploadtfafailed

-bash-4.1# curl -i -X GET -k -u tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/uploadtfafailed/all
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:09:18 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

[{"ID":"0B9O04CKSYZNUZCYZD","Status":"SUBMITTED"}]

7.8.1.16 version

Use GET requests to run the version command.

Syntax

/tfactl/orachk/version

Returns

Runs the version command and returns the version of the Oracle ORAchk daemon.

Example 7-33 version

# curl -k --user tfarest:password 
https://node1.example.com:9090/ords/tfactl/orachk/version
{"VERSION":"ORACHK  VERSION: 19.3.0_20190902"}

7.8.2 Configuring REST Using the Included ORDS

Override default ORDS configuration by setting the shell environment variables.

  • By default, Oracle REST Data Services (ORDS) uses whichever port is available in the range 7080-7085. If no port in this range is available, then ORDS exits and prompts you to set the RAT_ORDS_PORT environment variable. If RAT_ORDS_PORT is already set, then ORDS uses the port specified in the RAT_ORDS_PORT environment variable.

  • By default, ORDS is setup with the administrator user ordsadmin. You can override this by specifying a different user in the RAT_ORDSADMIN_USER environment variable.

  • Depending on Oracle ORAchk and Oracle EXAchk, ORDS is started as a nologin user named either ordsorachk or ordsexachk. If you use the ORDS, which is already running, then the user is as same as who is running ORDS.

  • If Oracle Trace File Analyzer is installed, then ORDS picks JAVA_HOME from TFA_HOME. If Oracle Trace File Analyzer is not installed, then ORDS picks the default JAVA_HOME. It is a requirement that you use JDK8. However, you can override by setting the RAT_JAVAEXE environment variable.

7.8.3 Configuring REST Using an Existing ORDS Installation

  1. To add the orachk.jar file to the existing ords.war file:
    orachk -ordssetup ords_war_dir -configdir config_dir
    exachk -ordssetup ords_war_dir -configdir config_dir

    where,

    ords_war_dir is the directory that contains the ords.war file

    config_dir is an optional directory that you can specify to store the ORDS configuration files. If you do not specify the optional directory, then the configuration files are stored in the orda_war_dir directory.

    Stopping and restarting ORDS after running the -ordssetup command:
    • Adds the orachk.jar file to the existing ords.war file

    • Adds the user ordsadmin to the ords.war file, and grants ORAchk admin privileges to ordsadmin

  2. To start the Oracle ORAchk or Oracle EXAchk daemon:
    orachk -d start -ords ords_war_dir
    exachk -d start -ords ords_war_dir
After completion, open the ords_war_dir/log/ords_setup.log file to view the REST URL details.