2. Using REST Service
  3. Configuring Oracle REST Data Services (ORDS)

6.8 Configuring Oracle REST Data Services (ORDS)

Note:

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

Parent topic: Using REST Service

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

  • check
    Use GET requests to run a health check run for the specified check IDs.
  • checktfafaileduploads
    Use GET requests to report if any Oracle Autonomous Health Framework service uploads failed.
  • download
    Use GET requests to download the collection result for the specified job ID.
  • getinfo
    Use GET requests to report the status of the specified job ID.
  • listcollections
    Use GET requests to get the list of Oracle ORAchk collections generated through REST.
  • profile
    Use GET requests to run a health check run for the specified profiles.
  • showrepair
    Use GET requests to report the showrepair command for the specified check.
  • start_client
    Use POST requests to run a diff of the specified collection results.
  • start_client
    Use GET requests to run a normal health check run.
  • start_client
    Use POST and GET requests to run a normal health check run using specific arguments.
  • status
    Use GET requests to report the status on the specified job ID.
  • uploadtfafailed
    Use GET requests to reattempt to upload all previously failed uploads to Oracle Autonomous Health Framework service.
  • version
    Use GET requests to run the version command.

Parent topic: Configuring Oracle REST Data Services (ORDS)

6.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 6-18 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"}]

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.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 6-19 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."}]

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.8.1.3 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 6-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

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.8.1.4 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 6-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;

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.8.1.5 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 6-22 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

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.8.1.6 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 6-23 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"}]

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.8.1.7 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 6-24 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"}]

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.8.1.8 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 6-25 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"}]'

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.8.1.9 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 6-26 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"}]

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.8.1.10 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 6-27 JSON input

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

Example 6-28 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"}]

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.8.1.11 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 6-29 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"}]

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.8.1.12 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 6-30 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"}]

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

6.8.1.13 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 6-31 version

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

Parent topic: Using Oracle Autonomous Health Framework Compliance Over REST

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

Parent topic: Configuring Oracle REST Data Services (ORDS)

6.8.3 Configuring REST Using an Existing ORDS Installation

  1. To add the orachkrest.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 orachkrest.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.

Related Topics

Parent topic: Configuring Oracle REST Data Services (ORDS)