1. REST API for Embedded Python ExecutionREST API for Embedded Python Execution
  2. Quick Start

Quick Start

Set up your environment and use the REST API for Embedded Python Execution to create your first Embedded Python Execution job by performing the following tasks.

Prerequisite

The REST API for Embedded Python Execution functions require that you specify the name of a script in the Oracle Machine Learning for Python (OML4Py) script repository in your Oracle Autonomous Database service. A script contains a user-defined Python function. For information on creating a script and saving it to the script repository, see About Embedded Python 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 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 Database that is provisioned.
  1. Sign into your Oracle Cloud Infrastructure account. You will need your OCI user name and password.
  2. 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.
  3. Click Database Actions.
  4. 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 Python 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 Python Execution.

The following procedure demonstrates how to install cURL on a Windows 64-bit system.
  1. In your browser, navigate to the cURL home page at http://curl.haxx.se and click Download at the upper left.
  2. 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":"select * from IRIS", "parameters":"{\"oml_input_type\":\"pandas.DataFrame\"}", "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 a Rest API 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 Python scripts available to you in the OML4Py script repository:

curl -i -X GET --header "Authorization: Bearer ${token}" 
<oml-cloud-service-location-url>/oml/api/py-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":"OML_USER","date":"2020-08-27T15:53:56.000Z","name":"return_df","description":null,"script":"def return_df(num, scale):\n    import pandas as pd\n    id = list(range(0, int(num)))\n    res = [i/scale for i in id]\n    return pd.DataFrame({\"ID\":id, \"RES\":res})"},
{"owner":"OML_USER","date":"2020-08-27T16:09:17.000Z","name":"RandomRedDots","description":null,"script":"def RandomRedDots (num_dots_1=100, num_dots_2=10):\n  import numpy as np\n  import pandas as pd\n  import matplotlib.pyplot as plt  \n  d = {'id': range(1,10), 'val': [x/100 for x in range(1,10)]}\n  df = pd.DataFrame(data=d)\n  fig = plt.figure(1)\n  ax = fig.add_subplot(111)\n  ax.scatter(range(0,int(num_dots_1)), np.random.rand(int(num_dots_1)),c='r')\n  fig.suptitle(\"Random Red Dots\")\n  fig2 = plt.figure(2)\n  ax2 = fig2.add_subplot(111)\n  ax2.scatter(range(0,int(num_dots_2)), np.random.rand(int(num_dots_2)),c='r')\n  fig2.suptitle(\"Random Red Dots\")\n  return df"},
{"owner":"OML_USER","date":"2020-08-26T20:38:57.000Z","name":"compute_random_mean","description":null,"script":"def compute_random_mean(index):\n    import numpy as np\n    import scipy\n    from statistics import mean \n    np.random.seed(index)\n    res = np.random.random((100,1))*10\n    return mean(res[1])"},
{"owner":"OML_USER","date":"2020-08-18T21:35:06.000Z","name":"group_count","description":null,"script":"def group_count(dat):\n  import oml\n  import pandas as pd\n  return pd.DataFrame([(dat[\"SPECIES\"][0], dat[\"SEPAL_LENGTH\"][0], dat.shape[0])],   columns = [\"SPECIES\",\"SEPAL_LENGTH\", \"COUNT\"])"},
{"owner":"OML_USER","date":"2020-08-21T18:22:38.000Z","name":"my_predict","description":null,"script":"def my_predict(dat):\n    import pandas as pd\n    import oml\n    obj_dict = oml.ds.load(name=\"ds_regr\", to_globals=False)  \n    regr = obj_dict[\"regr\"] \n    pred = regr.predict(dat[['Sepal_Length', \n                             'Sepal_Width',\n                             'Petal_Length']])\n    return pd.concat([dat[['Species', 'Petal_Width']], \n                     pd.DataFrame(pred, \n                                  columns=['Pred_Petal_Width'])], \n                                  axis=1)"},
]}