Quick Start

Prerequisite

The REST API for Embedded R Execution functions require that you specify the name of a script in the Oracle Machine Learning for R (OML4R) script repository in your Oracle Autonomous AI Database service. A script contains a user-defined R function. For information on creating a script and saving it to the script repository, see About Embedded R Execution and the Script Repository.

Obtain Account Information

The account creation email from Oracle contains the identity domain name, user name, and password for your Oracle Autonomous AI Database service. If you do not have this information, then contact your service administrator.

You also need the following URLs that you can obtain from the Oracle Autonomous AI Database that is provisioned.

Sign into your Oracle Cloud Infrastructure account. You will need your OCI user name and password.
Click the hamburger menu and select Autonomous Database instance that is provisioned. For more information on provisioning an Autonomous Database, see: Provision an Oracle Autonomous Database.
Click Database Actions.
Scroll down the Database Action page, and click Oracle Machine Learning RESTful Services under the Related services tile. The Oracle Machine Learning RESTful Services dialog opens. Click Copy to obtain the following URLs for:
- Obtaining the REST authentication token for REST APIs provided by OML:
```
<oml-cloud-service-location-url>/omlusers/
```
- All embedded R REST APIs:
```
<oml-cloud-service-location-url>/oml/
```
The URL <oml-cloud-service-location-url> includes the tenancy ID, location, and database name. For example, https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com
In this example,
- qtraya2braestch is the tenancy ID
- omldb is the database name
- us-sanjose-1 is the datacenter region
- oraclecloudapps.com is the root domain.

Install cURL

The examples in this publication use the cURL command-line tool to demonstrate how to access the REST API for Embedded R Execution.

The following procedure demonstrates how to install cURL on a Windows 64-bit system.

In your browser, navigate to the cURL home page at http://curl.haxx.se and click Download at the upper left.
On the cURL Releases and Downloads page, locate the SSL-enabled version of the cURL software that corresponds to your operating system, click the link to download the ZIP file, and install the software.

To connect securely to the server, you must install a version of cURL that supports SSL.

Run cURL and specify one or more of the command-line options defined in the following table, as required:

cURL Option	Description
`-d, --data @file.json`	Identifies the file that contains the request body, in JSON format, on the local machine. Alternatively, you can pass the request body with `-d`. For example,`-d '{"input":"IRIS", "parameters":"{\"ore.drop\":false}", "parallelFlag":true}'`.
`-H, --header`	Defines one or both of the following: Authorization header containing the credentials to authenticate a user with the server. Content type of the request document. Accept header used to specify certain media types that are acceptable for the response.
`-i, --include`	Include the HTTP header in the output.
`-X`	Indicates the type of request (for example, GET, POST).

Obtain an Authentication Token

Obtain an authentication token as described in Authenticate.

Send a Request

After you set up your REST client, you can send a request to ensure that your connection works. For example, the following cURL command lists the R scripts available to you in the OML4R script repository:

curl -i -X GET --header "Authorization: Bearer ${token}" 
<oml-cloud-service-location-url>/oml/api/r-scripts/v1/scripts

Note:

This call needs authentication. The $token represents an environmental variable that is assigned to the token obtained through the Authorization API.

The <oml-cloud-service-location-url> URL includes the tenancy ID, location, and database name. For example, https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com

In this example,

qtraya2braestch is the tenancy ID
omldb is the database name
us-sanjose-1 is the datacenter region
oraclecloudapps.com is the root domain

If the request is successful, then you should receive a 200 response header with a body such as the following:

HTTP/1.1 200 OK
Date: Thu, 13 Jan 2022 08:36:42 GMT
Content-Type: application/json
Content-Length: 13
Connection: keep-alive
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1;mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
Content-Security-Policy: frame-ancestors 'none'
Set-Cookie: JSESSIONID=node0zdh3s4o3x13ua24jd16y44ro111.node0; Path=/oml; Secure; HttpOnly
Expires: Thu, 01 Jan 1970 00:00:00 GMT

The response body in JSON format is the following:

{"result":[
{"OWNER":"RQSYS","SCRIPT":"function (index) \n{\n    set.seed(index)\n    x <- rnorm(10)\n    res <- mean(x)\n    res\n}","NAME":"compute.randomMean"},
{"OWNER":"RQSYS","SCRIPT":"function (dat) \n{\n    res <- aggregate(dat, by = list(dat$Species), FUN = length)\n    colnames(res)[1] <- \"Species\"\n    res\n}","NAME":"group.count"},
{"OWNER":"RQSYS","SCRIPT":"function (dat) \n{\n    ore.load(name = \"ds_regr\")\n    pred = cbind(PRED = predict(regr, newdata = dat, supplemental.cols = \"Sepal.Length\"), dat[\"Sepal.Length\"])\n    pred\n}","NAME":"my.predict"},
{"OWNER":"OMLUSER","SCRIPT":"function (divisor = 100) \n{\n    id <- 1:10\n    plot(1:100, rnorm(100), pch = 21, bg = \"red\", cex = 2)\n  data.frame(id = id, val = id/divisor)\n}","NAME":"RandomRedDots"}]}