diff --git a/build-ords-apis-in-adb/1-create-user-and-database-objects/create-user-and-database-objects.md b/build-ords-apis-in-adb/1-create-user-and-database-objects/create-user-and-database-objects.md index 65f0bffcc..d80e412d6 100644 --- a/build-ords-apis-in-adb/1-create-user-and-database-objects/create-user-and-database-objects.md +++ b/build-ords-apis-in-adb/1-create-user-and-database-objects/create-user-and-database-objects.md @@ -4,14 +4,14 @@ In this lab you will create a new database developer user to use for the remainder of this workshop. You'll used this REST-enabled user to log into Database Actions as well as have the ability to REST-enable their own database objects. -You'll build out your schema with database objects, and AutoREST-enable a table in your Autonomous Database. Finally, you'll test the endpoint using the cURL command line tool +You'll build out your schema with database objects, and AutoREST-enable a table in your Autonomous AI Database. Finally, you'll test the endpoint using the cURL command line tool Estimated Lab Time: 20 minutes ### Objectives -- Create a new REST-enabled DB Developer user -- Create for the new user tables and various database objects +- Create a new REST-enabled Developer user +- Create tables and other database objects for this REST user - REST-enable a table for this new user ### Prerequisites @@ -23,7 +23,23 @@ Estimated Lab Time: 20 minutes ## Task 1: Create a new REST-enabled database user -1. You should still be logged in as the ADMIN user, if not, sign back in as the ADMIN and select the Administration tab from the LaunchPad. Then select the Database Users menu option. + + +1. Click **View Login Info**. + + ![Clicking the View Login Info link](./images/click-view-login-info.png " ") + +2. The Reservation Information slider will appear. Locate the DB ADMIN Password; copy it. + + ![Locating the Reservation Information Tab](./images/reservation-information-tab.png " " ) + +3. Open the SQL Worksheet link in a new tab. Login to Database Actions as the ADMIN user. + + ![entering-in-admin-info-in-landing-page](./images/entering-in-admin-info-in-landing-page.png " ") + + + +1. Complete or cancel the UI Tour. Select the Administration tab from the LaunchPad. Then select the Database Users menu option. ![Logged in as the Admin user](./images/1-launchpad-as-admin.png " ") @@ -254,25 +270,27 @@ Once complete, click the **Create User** button. ![Clicking execute script button](./images/11-build-out-schema.png " ") - 2. Click the Refresh button in the Navigator tab to refresh the Table objects. You'll see three new tables: +2. Click the Refresh button in the Navigator tab to refresh the Table objects. You'll see three new tables: + + - `DEPARTMENT` + - `EMPLOYEE` + - `PROJECT` - - `DEPARTMENT` - - `EMPLOYEE` - - `PROJECT` - - 3. Right-click on the `PROJECT` table. Select the **Open** option. A details slider will appear. +3. Right-click on the `PROJECT` table. Select the **Open** option. A details slider will appear. - ![Right click on open option in the context menu](./images/13-right-click-project-object-open.png " ") + ![Right click on open option in the context menu](./images/13-right-click-project-object-open.png " ") - 4. Click the **Data** tab to review the `PROJECT` table data. Later on, you'll insert additional data using the ORDS `BATCHLOAD` REST API. +4. Click the **Data** tab to review the `PROJECT` table data. Later on, you'll insert additional data using the ORDS `BATCHLOAD` REST API. ![Click data tab to review table data](./images/14-data-menu-review-rows.png " ") - 5. Click the **Close** button, right-click on the `PROJECT` table and select **Edit**. +5. Click the **Close** button, right-click on the `PROJECT` table and select **Edit**. ![Click the edit option on the table context menu](./images/15-edit-option-review-object-characteristics.png " ") - 6. Click the `DDL` tab, to review the fully formatted, and syntactically correct DDL for this table. When finished, click the **Close** button. +6. Click the `DDL` tab, to review the fully formatted, and syntactically correct DDL for this table. When finished, click the **Close** button. + + ![Click the edit option on the table context menu](./images/16-reviewing-object-ddl.png " ") ![Click the edit option on the table context menu](./images/16-reviewing-object-ddl.png " ") @@ -280,112 +298,148 @@ Once complete, click the **Create User** button. ## Task 4: AutoREST-enable a table - 1. Right-click on the `PROJECT` table, select **REST**, then **Enable**. - ![Click the REST > Enable option](./images/17-rest-enabling-project-table.png " ") - 2. A new REST Enable Object slider will appear. ORDS automatically generates an API endpoint for you, along with the Roles and Privileges associated with this new resource. You can select a new **Object Alias**; but for this lab keep the default Alias. You can also toggle the **Show Code** radio button to reveal the PL/SQL procedure that ORDS will execute to REST-enable this table. Once satisfied, click **Enable**. +2. A new REST Enable Object slider will appear. ORDS automatically generates an API endpoint for you, along with the Roles and Privileges associated with this new resource. You can select a new **Object Alias**; but for this lab keep the default Alias. You can also toggle the **Show Code** radio button to reveal the PL/SQL procedure that ORDS will execute to REST-enable this table. Once satisfied, click **Enable**. ![The REST Enable Object slider](./images/18-rest-enable-table-dialogue.png " ") - 3. You'll notice a new plug icon on the table, this indicates that the database object is now REST-enabled (i.e., it is associated with an URI for HTTP/S requests). Right-click on the `PROJECT` table, scroll to **REST**, and select the new **cURL command** menu item. +3. You'll notice a new plug icon on the table, this indicates that the database object is now REST-enabled (i.e., it is associated with an URI for HTTP/S requests). Right-click on the `PROJECT` table, scroll to **REST**, and select the new **cURL command** menu item. ![Selecting cURL command on the context menu](./images/19-curl-command-option.png " ") - 4. ORDS API endpoints are automatically created for you: `GET ALL`, `GET Single`, `POST`, `BATCH LOAD`, `PUT`, and `DELETE`. The definitions, and procedures for these methods/operations are all securely stored and executed on the Oracle database; nothing is saved in your application layer. Highlight or copy the URI for the `GET ALL` endpoint and open it in a new browser tab or window. +4. ORDS API endpoints are automatically created for you: + - `GET ALL` + - `GET Single` + - `POST` + - `BATCH LOAD` + - `PUT` + - `DELETE` + + The definitions, and procedures for these methods/operations are all securely stored and executed on the Oracle database; nothing is saved in your application layer. + +5. Highlight or copy the URI for the `GET ALL` endpoint and open it in a new browser tab or window. ![Opening GET ALL in a new browser tab](./images/20-go-to-address-in-new-tab.png " ") - 5. Notice the JSON payload of the `GET ALL` endpoint. The results on screen are analagous to executing something like this: +6. Notice the JSON payload of the `GET ALL` endpoint. The results on screen are analagous to executing something like this: - ```sql - SELECT * FROM PROJECT ORDER BY PROJ_ID OFFSET 0 ROWS FETCH NEXT 25 ROWS ONLY; - ``` + ```sql + SELECT * FROM PROJECT ORDER BY PROJ_ID OFFSET 0 ROWS FETCH NEXT 25 ROWS ONLY; + ``` ![Using inspect in the browser's developer tools](./images/21-inspect-browser-network-tab.png " ") - 6. Open your brower's Developer/Inspect tools, navigate to the Network tab, and adjust the page's response to view the Object Tree. In addition to `FETCHING` the first 25 rows, an ORDS AutoREST-enabled endpoint also includes links for each of the results (for an indiviual row), the total `count` (`10`) of the results of the payload (`items:Array`), the `limit` used (`25` is the ORDS default), the `offset` (`0`), and two more special properties: `hasMore` and `links:Array`. +7. Open your brower's Developer/Inspect tools, navigate to the Network tab, and adjust the page's response to view the Object Tree. In addition to `FETCHING` the first 25 rows, an ORDS AutoREST-enabled endpoint also includes links for each of the results (for an indiviual row), the total `count` (`10`) of the results of the payload (`items:Array`), the `limit` used (`25` is the ORDS default), the `offset` (`0`), and two more special properties: `hasMore` and `links:Array`. - - `hasMore: Boolean` - informs a client if more results exist past the initial 25; allowing you to programmatically scale the results using this condition plus `limit` and `offset` for finer grain control and easier pagination. - - `links:Array` - provides self-describing and self-referring links - - `first` points to the first set of results (1-25) - - larger results sets would include `next` and `previous` links too + - `hasMore: Boolean` - informs a client if more results exist past the initial 25; allowing you to programmatically scale the results using this condition plus `limit` and `offset` for finer grain control and easier pagination. + - `links:Array` - provides self-describing and self-referring links + - `first` points to the first set of results (1-25) + - larger results sets would include `next` and `previous` links too ![Reviewing the Response Object Tree](./images/22-object-tree-view.png " ") - 7. Return to the SQL Worksheet. The **cURL for the table PROJECT** slider should still be visible, if not review the instructions in Step 3 above. Click the `BATCH LOAD` tab, choose the appropriate shell environment, and copy the `BATCH LOAD` cURL command to your clipboard. +8. Return to the SQL Worksheet. The **cURL for the table PROJECT** slider should still be visible, if not review the instructions in Step 3 above. Click the `BATCH LOAD` tab, choose the appropriate shell environment, and copy the `BATCH LOAD` cURL command to your clipboard. ![Copying the BATCHLOAD URI](./images/23-prepare-for-batchload.png " ") - 8. You'll use this `BATCH LOAD` endpoint to perform a bulk insert on the `PROJECT` table via an HTTP request. +9. You'll use this `BATCHLOAD` endpoint to perform a bulk insert on the `PROJECT` table via an HTTP request. - ## Task 5: Using the ORDS BATCH LOAD endpoint +## Task 5: Using the ORDS BATCHLOAD endpoint - 1. This `BATCH LOAD` example uses cURL to simulate a client application executing/recieving HTTP requests/responses. In a text editor, paste the example `BATCHLOAD` cURL command you copied from the previous lab. +1. This `BATCHLOAD` example uses cURL to simulate a client application executing/recieving HTTP requests/responses. In a text editor, paste the example `BATCHLOAD` cURL command you copied from the previous lab. ![Copying the BATCHLOAD URI](./images/23-prepare-for-batchload.png " ") ![Unedited batchload curl command](./images/24-unedited-batchload-curl-command.png " ") - 2. Retrieve the sample payload via [this link](https://c4u04.objectstorage.us-ashburn-1.oci.customer-oci.com/p/EcTjWk2IuZPZeNnD_fYMcgUhdNDIDA6rt9gaFj_WZMiL7VvxPBNMY60837hu5hga/n/c4u04/b/livelabsfiles/o/developer-library/batchload_directory.zip) that you'll use for testing this `BATCH LOAD` endpoint. Unzip the .zip file if this did not occur automatically. +2. Retrieve the sample payload via [this link](https://c4u04.objectstorage.us-ashburn-1.oci.customer-oci.com/p/EcTjWk2IuZPZeNnD_fYMcgUhdNDIDA6rt9gaFj_WZMiL7VvxPBNMY60837hu5hga/n/c4u04/b/livelabsfiles/o/developer-library/batchload_directory.zip) that you'll use for testing this `BATCHLOAD` endpoint. Unzip the .zip file if this did not occur automatically. - 3. Once downloaded, copy the filepath details to use in the `--data-binary` option of the cURL command. In this example, the .csv file is located at: `/Users/me/Downloads/project_batchload.csv`. +3. Once downloaded, copy the filepath details to use in the `--data-binary` option of the cURL command. In this example, the .csv file is located at: `/Users/me/Downloads/project_batchload.csv`. - ```shell - - curl -v -i -X POST - -H "Content-Type: text/csv" - "https://my-ocid-db-name.adb.my-region-1.oraclecloudapps.com/ords/ords101/project/batchload" - --data-binary "@\Users\me\Downloads\project_batchload.csv" - - ``` + ```shell + + curl -v -i -X POST + -H "Content-Type: text/csv" + "https://my-ocid-db-name.adb.my-region-1.oraclecloudapps.com/ords/[your schema]/project/batchload" + --data-binary "@\Users\me\Downloads\project_batchload.csv" + + ```
Learn about the available BATCHLOAD parameters

- You may optionally pass reserved `BATCHLOAD` URL query parameters. in your `POST` request. Available parameters include: - - | Parameter | Description | URL example | Details / unencoded value | - |---|---|---|---| - | `batchesPerCommit` | Commit frequency after batches are sent to the database. Default: every 10 batches. `0` defers commit until the end of the load. Integer. | `?batchesPerCommit=10` | `10` is the literal integer value. | - | `batchRows` | Number of rows in each batch sent to the database. Default: 50. Integer. | `?batchRows=1000` | `1000` is the literal integer value. | - | `dateFormat` | Format mask used to convert input values for `DATE` columns. | `?dateFormat=YYYY-MM-DD` | Unencoded value: `YYYY-MM-DD`. | - | `delimiter` | Field delimiter for the input file. Default: comma (`,`). | `?delimiter=%2C`
`?delimiter=%7C` | `%2C` = `,` (comma); `%7C` = `|` (pipe). | - | `enclosures` | Character(s) enclosing each field. Default: double quote (`"`). One character is used for both sides; two characters specify left then right enclosures. | `?enclosures=%22`
`?enclosures=%27%22` | `%22` = `"`; both left and right enclosures are double quotes.
`%27%22` = `'"`; left is `'`, right is `"`. | - | `embeddedRightDouble` | Controls handling of two consecutive right-enclosure characters inside an enclosed field. `true` treats them as one literal enclosure; `false` treats them as an error. | `?embeddedRightDouble=true` | `true` is the literal Boolean value. | - | `encoding` | Character encoding of the input file. Default: `UTF8`. | `?encoding=UTF-8` | Unencoded value: `UTF-8`. | - | `errors` | Maximum row errors allowed before terminating the load, subject to the service-level `db.batchload.errorsMax` limit. `0` allows no errors; `UNLIMITED` / `-1` allows errors up to the service limit. | `?errors=0`
`?errors=UNLIMITED` | `0` is the literal integer value; `UNLIMITED` is the literal keyword. | - | `lineEnd` | Input record terminator. Omit it when the file uses standard `\\r`, `\\r\\n`, or `\\n` endings. | `?lineEnd=%0A`
`?lineEnd=%0D%0A` | `%0A` = line feed (`LF`, `\\n`).
`%0D%0A` = carriage return + line feed (`CRLF`, `\\r\\n`). | - | `lineMax` | Maximum line length used to recognize rows in the stream. Default: unlimited. | `?lineMax=4096`
`?lineMax=UNLIMITED` | `4096` is a literal integer; `UNLIMITED` is the literal keyword. | - | `locale` | Locale used for locale-sensitive loader parsing and formatting. | `?locale=en-US` | Unencoded value: `en-US`. | - | `responseEncoding` | Encoding of the loader response stream. | `?responseEncoding=UTF-8` | Unencoded value: `UTF-8`. | - | `responseFormat` | Format of loader messages and bad-data output. Valid values: `RAW`, `SQL`. Default: `RAW`. | `?responseFormat=RAW` | `RAW` is the literal keyword. | - | `timestampFormat` | Format mask used to convert input values for `TIMESTAMP` columns. | `?timestampFormat=YYYY-MM-DD%22T%22HH24%3AMI%3ASS` | Unencoded value: `YYYY-MM-DD"T"HH24:MI:SS`. `%22` = `"`, `%3A` = `:`. | - | `timestampTZFormat` | Format mask used to convert input values for `TIMESTAMP WITH TIME ZONE` columns. | `?timestampTZFormat=YYYY-MM-DD%22T%22HH24%3AMI%3ASSTZH%3ATZM` | Unencoded value: `YYYY-MM-DD"T"HH24:MI:SSTZH:TZM`. `%22` = `"`, `%3A` = `:`. | - | `truncate` | Whether to delete existing table rows before loading. `false` (default) retains them; `true` uses `DELETE`; `truncate` uses `TRUNCATE TABLE`. | `?truncate=true`
`?truncate=truncate` | `true` is the literal Boolean value; `truncate` is the literal keyword. |eibccddubtfcttnlbdvefekfejdcnkhdniktnddfgilr - - **A combined example** - - ```text - /ords/hr/employees/batchload?truncate=true&batchRows=1000&batchesPerCommit=10&errors=0&dateFormat=YYYY-MM-DD&encoding=UTF-8&delimiter=%2C&lineEnd=%0A&enclosures=%22&embeddedRightDouble=true - ``` - -> **Reminder:** Percent-encode URL-reserved characters; double quote → `%22`, comma → `%2C`, pipe → `%7C`, line feed → `%0A`, carriage return/line feed (CRLF) → `%0D%0A`, etc. -
-

+ You may optionally pass reserved `BATCHLOAD` URL query parameters. in your `POST` request. Available parameters include: + + | Parameter | Description | URL example | Details / unencoded value | + |---|---|---|---| + | `batchesPerCommit` | Commit frequency after batches are sent to the database. Default: every 10 batches. `0` defers commit until the end of the load. Integer. | `?batchesPerCommit=10` | `10` is the literal integer value. | + | `batchRows` | Number of rows in each batch sent to the database. Default: 50. Integer. | `?batchRows=1000` | `1000` is the literal integer value. | + | `dateFormat` | Format mask used to convert input values for `DATE` columns. | `?dateFormat=YYYY-MM-DD` | Unencoded value: `YYYY-MM-DD`. | + | `delimiter` | Field delimiter for the input file. Default: comma (`,`). | `?delimiter=%2C`
`?delimiter=%7C` | `%2C` = `,` (comma); `%7C` = `|` (pipe). | + | `enclosures` | Character(s) enclosing each field. Default: double quote (`"`). One character is used for both sides; two characters specify left then right enclosures. | `?enclosures=%22`
`?enclosures=%27%22` | `%22` = `"`; both left and right enclosures are double quotes.
`%27%22` = `'"`; left is `'`, right is `"`. | + | `embeddedRightDouble` | Controls handling of two consecutive right-enclosure characters inside an enclosed field. `true` treats them as one literal enclosure; `false` treats them as an error. | `?embeddedRightDouble=true` | `true` is the literal Boolean value. | + | `encoding` | Character encoding of the input file. Default: `UTF8`. | `?encoding=UTF-8` | Unencoded value: `UTF-8`. | + | `errors` | Maximum row errors allowed before terminating the load, subject to the service-level `db.batchload.errorsMax` limit. `0` allows no errors; `UNLIMITED` / `-1` allows errors up to the service limit. | `?errors=0`
`?errors=UNLIMITED` | `0` is the literal integer value; `UNLIMITED` is the literal keyword. | + | `lineEnd` | Input record terminator. Omit it when the file uses standard `\\r`, `\\r\\n`, or `\\n` endings. | `?lineEnd=%0A`
`?lineEnd=%0D%0A` | `%0A` = line feed (`LF`, `\\n`).
`%0D%0A` = carriage return + line feed (`CRLF`, `\\r\\n`). | + | `lineMax` | Maximum line length used to recognize rows in the stream. Default: unlimited. | `?lineMax=4096`
`?lineMax=UNLIMITED` | `4096` is a literal integer; `UNLIMITED` is the literal keyword. | + | `locale` | Locale used for locale-sensitive loader parsing and formatting. | `?locale=en-US` | Unencoded value: `en-US`. | + | `responseEncoding` | Encoding of the loader response stream. | `?responseEncoding=UTF-8` | Unencoded value: `UTF-8`. | + | `responseFormat` | Format of loader messages and bad-data output. Valid values: `RAW`, `SQL`. Default: `RAW`. | `?responseFormat=RAW` | `RAW` is the literal keyword. | + | `timestampFormat` | Format mask used to convert input values for `TIMESTAMP` columns. | `?timestampFormat=YYYY-MM-DD%22T%22HH24%3AMI%3ASS` | Unencoded value: `YYYY-MM-DD"T"HH24:MI:SS`. `%22` = `"`, `%3A` = `:`. | + | `timestampTZFormat` | Format mask used to convert input values for `TIMESTAMP WITH TIME ZONE` columns. | `?timestampTZFormat=YYYY-MM-DD%22T%22HH24%3AMI%3ASSTZH%3ATZM` | Unencoded value: `YYYY-MM-DD"T"HH24:MI:SSTZH:TZM`. `%22` = `"`, `%3A` = `:`. | + | `truncate` | Whether to delete existing table rows before loading. `false` (default) retains them; `true` uses `DELETE`; `truncate` uses `TRUNCATE TABLE`. | `?truncate=true`
`?truncate=truncate` | `true` is the literal Boolean value; `truncate` is the literal keyword. |eibccddubtfcttnlbdvefekfejdcnkhdniktnddfgilr + + **A combined example** + + ```sh + /ords/[schema]/employees/batchload?truncate=true&batchRows=1000&batchesPerCommit=10&errors=0&dateFormat=YYYY-MM-DD&encoding=UTF-8&delimiter=%2C&lineEnd=%0A&enclosures=%22&embeddedRightDouble=true + ``` + + > **Reminder:** Percent-encode URL-reserved characters; double quote → `%22`, comma → `%2C`, pipe → `%7C`, line feed → `%0A`, carriage return/line feed (CRLF) → `%0D%0A`, etc. + +

-4. In your text editor replace `` with `text/csv` and `--data-binary @` with your own file path. Optionally you may include other cURL options like those in the example. +4. In your text editor replace `` with `text/csv` and `--data-binary @` with your own file path. Optionally you may include other cURL options like those in the examples above. ![Edited batchload curl command](./images/25-batchload-curl-command-with-edits.png " ") > **NOTE:** Your `BATCHLOAD` URI will differ as well. File paths for macOS/Linux and Windows differ; double check your complete cURL command. -5. Execute the `BATCH LOAD` request. After a few moments the results of the operation will appear in your terminal. +
+ Optional Progress Meter with cURL + + Optionally, you can output a progress meter for the `BATCHLOAD` operation. Assuming you have created a `/tmp` directory using a cURL command like this: + + ```sh + + mkdir tmp && cd tmp + + ``` + + ```sh + + curl --location -o ./output.txt -# --request POST \ + --header "Content-Type: text/csv" \ + --data-binary @[your filepath to]/project_batchload.csv \ + 'https://[your ADB-S].oraclecloudapps.com/ords/[your schema]/project/batchload' \ + && cat ./output.txt && rm ./output.txt + + ``` + + ![Optional progress bar, mid loading.](./images/optional-progress-bar-mid-load.png " ") + + ![Optional progress bar, completed.](./images/optional-progress-bar-complete.png " ") + +
+

+ +5. Execute the `BATCHLOAD` request. After a few moments the results of the operation will appear in your terminal. ![Unedited batchload curl command](./images/26-completed-batchload-command.png " ") -6. You've just inserted an additional 5,000,000 records into the Project table using this ORDS `BATCH LOAD` API. Execute a `Select count(*) from PROJECT;` query to review the new total entries in the `PROJECT` table. +6. You've just inserted an additional 5,000,000 records into the Project table using this ORDS `BATCHLOAD` API. Execute a `Select count(*) from PROJECT;` query to review the new total entries in the `PROJECT` table. ```sql @@ -404,7 +458,7 @@ You may now [proceed to the next lab](#next). ### Author - Jeff "el jefe" Smith, Distinguished Product Manager -- Chris Hoina, Senior Product Manager +- Chris Hoina, Lead Principal Product Manager ### Last Updated By/Date diff --git a/build-ords-apis-in-adb/1-create-user-and-database-objects/images/click-view-login-info.png b/build-ords-apis-in-adb/1-create-user-and-database-objects/images/click-view-login-info.png new file mode 100644 index 000000000..8ff690bcf Binary files /dev/null and b/build-ords-apis-in-adb/1-create-user-and-database-objects/images/click-view-login-info.png differ diff --git a/build-ords-apis-in-adb/1-create-user-and-database-objects/images/entering-in-admin-info-in-landing-page.png b/build-ords-apis-in-adb/1-create-user-and-database-objects/images/entering-in-admin-info-in-landing-page.png new file mode 100644 index 000000000..6b0f8ad4b Binary files /dev/null and b/build-ords-apis-in-adb/1-create-user-and-database-objects/images/entering-in-admin-info-in-landing-page.png differ diff --git a/build-ords-apis-in-adb/1-create-user-and-database-objects/images/optional-progress-bar-complete.png b/build-ords-apis-in-adb/1-create-user-and-database-objects/images/optional-progress-bar-complete.png new file mode 100644 index 000000000..47a2bcb63 Binary files /dev/null and b/build-ords-apis-in-adb/1-create-user-and-database-objects/images/optional-progress-bar-complete.png differ diff --git a/build-ords-apis-in-adb/1-create-user-and-database-objects/images/optional-progress-bar-mid-load.png b/build-ords-apis-in-adb/1-create-user-and-database-objects/images/optional-progress-bar-mid-load.png new file mode 100644 index 000000000..89fe21e60 Binary files /dev/null and b/build-ords-apis-in-adb/1-create-user-and-database-objects/images/optional-progress-bar-mid-load.png differ diff --git a/build-ords-apis-in-adb/1-create-user-and-database-objects/images/reservation-information-tab.png b/build-ords-apis-in-adb/1-create-user-and-database-objects/images/reservation-information-tab.png new file mode 100644 index 000000000..b63352cbf Binary files /dev/null and b/build-ords-apis-in-adb/1-create-user-and-database-objects/images/reservation-information-tab.png differ diff --git a/build-ords-apis-in-adb/2-build-ords-apis/build-ords-apis.md b/build-ords-apis-in-adb/2-build-ords-apis/build-ords-apis.md index aa35c630f..fd27d63af 100644 --- a/build-ords-apis-in-adb/2-build-ords-apis/build-ords-apis.md +++ b/build-ords-apis-in-adb/2-build-ords-apis/build-ords-apis.md @@ -45,7 +45,7 @@ Estimated Lab Time: 25 minutes 6. The definiton for the PL/SQL procedure will be visible in the SQL Worksheet. This produre expects the following parameters: `p_emp_name`, `p_dept_code` (associated with a `dept_id`), and `comments`. It then inserts these values into the `Employee` table. - ![Reviewing the PLSQL Procedure in the worksheet](./images/5-plsql-definition-in-sql-worksheet.png " ") + ![Reviewing the PLSQL Procedure in the worksheet](./images/5-plsql-procedure-definition-in-sql-worksheet.png " ") 7. Next, you'll insert a new row into the `Employee` table, using this procedure. Take note of one of the available, valid Department Codes: `EN003, FN002, HR001, IT007, LG006, LG009, MK005, OP010, SA004, SP008`. @@ -81,7 +81,7 @@ Estimated Lab Time: 25 minutes ![Click hamburger then rest](./images/11-click-hamburger-then-rest.png " ") -2. You are now in the **REST** Workshop. Here is where you build and test your ORDS APIs. Click the **AUTOREST** card. +2. Welcome to the **REST** Workshop. Click the **AUTOREST** card. ![Click the autorest card](./images/12-click-the-autorest-card.png " ") @@ -89,7 +89,7 @@ Estimated Lab Time: 25 minutes ![Export OpenAPI on the project table](./images/13-autorest-table-project-export-open-api.png " ") -4. You'll see a downloadable version of your API in the OpenAPI specification. This makes it easy for you to review, and share definitions. +4. You'll see a downloadable version of your API in the OpenAPI specification. This makes it easy for you to review, and share your API definitions. ![The downloadable OpenAPI Export](./images/14-open-api-export-download.png " ") @@ -97,7 +97,7 @@ Estimated Lab Time: 25 minutes ![The OpenAPI view on Project table](./images/15-openapi-view-on-project.png " ") -6. You will see an in-browser testing dashboard based on the OpenAPI specification. Here you can test your APIs without having to log into, or open a separate application. When satisfied, click the **Modules** tab at the top of the REST Workshop page. +6. You'll see an in-browser testing dashboard based on the OpenAPI specification. Here you can test your APIs without having to log into, or open a separate application. When satisfied, click the **Modules** tab at the top of the REST Workshop page. ![OpenAPI view dashboard](./images/16-open-api-view-dashboard.png " ") @@ -205,8 +205,8 @@ Estimated Lab Time: 25 minutes DECLARE L_SQLCODE PLS_INTEGER; - BEGIN - DEMO_USER.PR_ADD_AND_ASSIGN_EMPLOYEE( + BEGIN -- Optionally use a fully-qualified name like [SCHEMA].PR_ADD_AND_ASSIGN_EMPLOYEE(); + PR_ADD_AND_ASSIGN_EMPLOYEE( P_EMP_NAME => :EMP_NAME, P_DEPT_CODE => :DEPT_CODE, P_COMMENTS => :COMMENTS @@ -272,15 +272,17 @@ Estimated Lab Time: 25 minutes > **NOTE:** The values have already been included in the sample Anonymous Block snippet, but simply clicking the Handler Parameter name will place the parameter value at the current location of your cursor. -8. Now, you can test this new POST API. From the Handler's kebab menu, select **Get cURL command**, then the **+ plus** button of the curl Command modal. A Substitutions modal will appear. Enter in values for `EMP_NAME`, `DEPT_CODE`, `COMMENTS`, and check Null for the `response_status` and `response_message`. Be sure to review and select valid values for the `DEPT_CODE`. Once finished, click **OK**. +8. Now, you can test this new POST API. From the Handler's kebab menu, select **Get cURL command**, then the **+ plus** button of the curl Command modal. ![Retrieving the curl command](./images/42-getting-the-post-curl.png " ") ![clicking the plus button](./images/27-press-plus-button-get.png " ") +9. A Substitutions modal will appear. Enter in values for `EMP_NAME`, `DEPT_CODE`, `COMMENTS`, and check Null for the `response_status` and `response_message`. Be sure to review and select valid values for the `DEPT_CODE` (Valid values: `EN003`, `FN002`, `HR001`, `IT007`, `LG006`, `LG009`, `MK005`, `OP010`, `SA004`, `SP008`). Once finished, click **OK**. + ![Adding substitution details](./images/43-entering-substitution-details.png " ") -9. Copy the curl command into a clipboard, and remove the `response_status` and `response_message` key:value pairs, and the no-longer-required comma. Then, paste the updated command in a Terminal window and execute the curl command. +10. Copy the curl command into a clipboard, and remove the `response_status` and `response_message` key:value pairs, and the no-longer-required comma. Then, paste the updated command in a Terminal window and execute the curl command. ![Copying the post request](./images/44-clicking-copy-for-post.png " ") @@ -288,11 +290,11 @@ Estimated Lab Time: 25 minutes ![Empty key value pairs removed](./images/44-2-key-value-pairs-removed.png " ") -10. You should see the success response message in your terminal. +11. You should see the success response message in your terminal. ![Reviewing the response in terminal](./images/45-response-in-terminal.png " ") -11. You can also perform a simple query to review that latest INSERT using the following code snippet: +12. You can also perform a simple query to review that latest INSERT using the following code snippet: ```sql Select * from Employee where emp_name='The name you used in the POST request'; @@ -300,7 +302,7 @@ Estimated Lab Time: 25 minutes ![Querying the latest insert in sql worksheet](./images/46-querying-latest-post-in-sql-worksheet.png " ") -12. And that's it, you've just successfully created your first two custom ORDS APIs. But you've probably noticed, no security? Continue to the next lab to learn more about securing your ORDS APIs. +13. And that's it, you've just successfully created your first two custom ORDS APIs. But you've probably noticed, no security? Continue to the next lab to learn more about securing your ORDS APIs. You may now [proceed to the next lab](#next). @@ -309,7 +311,7 @@ You may now [proceed to the next lab](#next). ### Author - Jeff "el jefe" Smith, Distinguished Product Manager -- Chris Hoina, Senior Product Manager +- Chris Hoina, Lead Principal Product Manager ### Last Updated By/Date diff --git a/build-ords-apis-in-adb/2-build-ords-apis/images/5-plsql-procedure-definition-in-sql-worksheet.png b/build-ords-apis-in-adb/2-build-ords-apis/images/5-plsql-procedure-definition-in-sql-worksheet.png new file mode 100644 index 000000000..aef0722a4 Binary files /dev/null and b/build-ords-apis-in-adb/2-build-ords-apis/images/5-plsql-procedure-definition-in-sql-worksheet.png differ diff --git a/build-ords-apis-in-adb/3-secure-endpoints/secure-endpoints.md b/build-ords-apis-in-adb/3-secure-endpoints/secure-endpoints.md index f39e21d14..041c897aa 100644 --- a/build-ords-apis-in-adb/3-secure-endpoints/secure-endpoints.md +++ b/build-ords-apis-in-adb/3-secure-endpoints/secure-endpoints.md @@ -91,26 +91,21 @@ Estimated Lab Time: 10 minutes ![Description Field](./images/11-create-oauth-client-definition.png " ") -4. Previously you created a Privilege, which includes (enumerates) a Role. Here, you can optionally assign the OAuth Client either the `my.test.role` role, the `my.test.priv` privilege, or both (although in this case, a bit redundant). +4. **Roles** Select the previously created role: `my.test.role` (or your unique role, if it differs). - Selecting *only* the Role is acceptable, since the Privilege you created includes this Role. Since your `records.module` is protected by the same Privilege, this is a valid approach. + ![choose-roles-tB](./images/12-create-oauth-client-roles.png " ") - **Roles** - - **Roles:** `my.test.role` (or your unique role, if it differs) +5. **Privileges** Next, choose the privilege: `my.test.priv` (or your unique privilege, if it differs). + + ![choose-ouath-privs](./images/13-create-oauth-client-privs.png " ") - ![choose-roles-tB](./images/12-create-oauth-client-roles.png " ") +5. Click the **Create** button when complete. Alternatively, you can simply assign the Privilege directly. And since that Privilege enumerates the Role, this is valid as well. **Privileges** - **Roles:** `my.test.role` (or your unique role, if it differs) - ![choose-ouath-privs](./images/13-create-oauth-client-privs.png " ") - -5. Choose an approach, and click the **Create** button when complete. - -## Task 4: Testing the OAuth2.0 client - 1. After clicking **Create**, a Client Secret modal will appear. Copy the Secret Client value to your clipboard or a text editor. ![Copy my client secret](./images/14-my-oauth-client-secret.png " ") @@ -142,7 +137,7 @@ Estimated Lab Time: 10 minutes > ![Obtaining-the-bearer-token-part-one](./images/17-obtaining-the-bearer-token-part-one.png " ") -4. Execute your cURL command; you will recieve a valid Access Token. In this example, you can use the `GET` endpoint that you created in **Lab 2, Task 3: Building an ORDS GET API** as your target endpoint. +4. Execute your cURL command; you will receive a valid Access Token. In this example, you can use the `GET` endpoint that you created in **Lab 2, Task 3: Building an ORDS GET API** as your target endpoint. ![Obtaining-the-bearer-token-part-two](./images/18-obtaining-the-bearer-token-part-two.png " ") @@ -171,7 +166,7 @@ You may now [proceed to the next lab](#next). ### Author - Jeff Smith, Distinguished Product Manager -- Chris Hoina, Senior Product Manager +- Chris Hoina, Lead Principal Product Manager ### Last Updated By/Date diff --git a/build-ords-apis-in-adb/4-workshop-scripts/create_department_table.sql b/build-ords-apis-in-adb/4-workshop-scripts/create_department_table.sql index 2d28d5d36..14dd93ee8 100644 --- a/build-ords-apis-in-adb/4-workshop-scripts/create_department_table.sql +++ b/build-ords-apis-in-adb/4-workshop-scripts/create_department_table.sql @@ -1,23 +1,23 @@ -CREATE TABLE "DEMO_USER"."DEPARTMENT" +CREATE TABLE "DEPARTMENT" ( "DEPT_ID" NUMBER GENERATED BY DEFAULT AS IDENTITY MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 1 CACHE 20 NOORDER NOCYCLE NOKEEP NOSCALE , "DEPT_CODE" VARCHAR2(5 BYTE) COLLATE "USING_NLS_COMP", "ESTABLISHED" DATE, "DETAILS" JSON ) DEFAULT COLLATION "USING_NLS_COMP" ; -CREATE UNIQUE INDEX "DEMO_USER"."DEPT_CODE_UK" ON "DEMO_USER"."DEPARTMENT" ("DEPT_CODE") +CREATE UNIQUE INDEX "DEPT_CODE_UK" ON "DEPARTMENT" ("DEPT_CODE") ; -CREATE UNIQUE INDEX "DEMO_USER"."DEPT_ID_PK" ON "DEMO_USER"."DEPARTMENT" ("DEPT_ID") +CREATE UNIQUE INDEX "DEPT_ID_PK" ON "DEPARTMENT" ("DEPT_ID") ; -CREATE UNIQUE INDEX "DEMO_USER"."DEPARTMENT_DEPT_CODE_UQ" ON "DEMO_USER"."DEPARTMENT" (UPPER("DEPT_CODE")) +CREATE UNIQUE INDEX "DEPARTMENT_DEPT_CODE_UQ" ON "DEPARTMENT" (UPPER("DEPT_CODE")) ; -ALTER TABLE "DEMO_USER"."DEPARTMENT" MODIFY ("DEPT_ID" NOT NULL ENABLE); +ALTER TABLE "DEPARTMENT" MODIFY ("DEPT_ID" NOT NULL ENABLE); -ALTER TABLE "DEMO_USER"."DEPARTMENT" MODIFY ("DEPT_CODE" CONSTRAINT "DEPT_CODE_NN" NOT NULL ENABLE); +ALTER TABLE "DEPARTMENT" MODIFY ("DEPT_CODE" CONSTRAINT "DEPT_CODE_NN" NOT NULL ENABLE); -ALTER TABLE "DEMO_USER"."DEPARTMENT" ADD CONSTRAINT "DEPT_ID_PK" PRIMARY KEY ("DEPT_ID") +ALTER TABLE "DEPARTMENT" ADD CONSTRAINT "DEPT_ID_PK" PRIMARY KEY ("DEPT_ID") USING INDEX ENABLE; diff --git a/build-ords-apis-in-adb/4-workshop-scripts/create_employee_table.sql b/build-ords-apis-in-adb/4-workshop-scripts/create_employee_table.sql index 67973646c..038b30941 100644 --- a/build-ords-apis-in-adb/4-workshop-scripts/create_employee_table.sql +++ b/build-ords-apis-in-adb/4-workshop-scripts/create_employee_table.sql @@ -1,25 +1,25 @@ -CREATE TABLE "DEMO_USER"."EMPLOYEE" +CREATE TABLE "EMPLOYEE" ( "EMP_ID" NUMBER GENERATED BY DEFAULT AS IDENTITY MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 1 CACHE 20 NOORDER NOCYCLE NOKEEP NOSCALE , "EMP_NAME" VARCHAR2(100 BYTE) COLLATE "USING_NLS_COMP", "DEPT_ID" NUMBER, "COMMENTS" CLOB COLLATE "USING_NLS_COMP" ) DEFAULT COLLATION "USING_NLS_COMP" ; -CREATE UNIQUE INDEX "DEMO_USER"."EMP_ID_PK" ON "DEMO_USER"."EMPLOYEE" ("EMP_ID") +CREATE UNIQUE INDEX "EMP_ID_PK" ON "EMPLOYEE" ("EMP_ID") ; -CREATE INDEX "DEMO_USER"."EMP_DEPARTMENT_IX" ON "DEMO_USER"."EMPLOYEE" ("DEPT_ID") +CREATE INDEX "EMP_DEPARTMENT_IX" ON "EMPLOYEE" ("DEPT_ID") ; -ALTER TABLE "DEMO_USER"."EMPLOYEE" MODIFY ("EMP_ID" NOT NULL ENABLE); +ALTER TABLE "EMPLOYEE" MODIFY ("EMP_ID" NOT NULL ENABLE); -ALTER TABLE "DEMO_USER"."EMPLOYEE" MODIFY ("EMP_NAME" CONSTRAINT "EMP_NAME_NN" NOT NULL ENABLE); +ALTER TABLE "EMPLOYEE" MODIFY ("EMP_NAME" CONSTRAINT "EMP_NAME_NN" NOT NULL ENABLE); -ALTER TABLE "DEMO_USER"."EMPLOYEE" MODIFY ("DEPT_ID" CONSTRAINT "EMP_DEPT_ID_NN" NOT NULL ENABLE); +ALTER TABLE "EMPLOYEE" MODIFY ("DEPT_ID" CONSTRAINT "EMP_DEPT_ID_NN" NOT NULL ENABLE); -ALTER TABLE "DEMO_USER"."EMPLOYEE" ADD CONSTRAINT "EMP_ID_PK" PRIMARY KEY ("EMP_ID") +ALTER TABLE "EMPLOYEE" ADD CONSTRAINT "EMP_ID_PK" PRIMARY KEY ("EMP_ID") USING INDEX ENABLE; -ALTER TABLE "DEMO_USER"."EMPLOYEE" ADD CONSTRAINT "FK_EMPLOYEE_DEPT" FOREIGN KEY ("DEPT_ID") - REFERENCES "DEMO_USER"."DEPARTMENT" ("DEPT_ID") ENABLE; +ALTER TABLE "EMPLOYEE" ADD CONSTRAINT "FK_EMPLOYEE_DEPT" FOREIGN KEY ("DEPT_ID") + REFERENCES "DEPARTMENT" ("DEPT_ID") ENABLE; diff --git a/build-ords-apis-in-adb/4-workshop-scripts/create_procedure.sql b/build-ords-apis-in-adb/4-workshop-scripts/create_procedure.sql index fd7c4ec4a..0e11c154f 100644 --- a/build-ords-apis-in-adb/4-workshop-scripts/create_procedure.sql +++ b/build-ords-apis-in-adb/4-workshop-scripts/create_procedure.sql @@ -1,4 +1,4 @@ -CREATE OR REPLACE EDITIONABLE PROCEDURE "DEMO_USER"."PR_ADD_AND_ASSIGN_EMPLOYEE" ( +CREATE OR REPLACE EDITIONABLE PROCEDURE "PR_ADD_AND_ASSIGN_EMPLOYEE" ( p_emp_name IN VARCHAR2, p_dept_code IN VARCHAR2, p_comments IN CLOB diff --git a/build-ords-apis-in-adb/4-workshop-scripts/create_project_table.sql b/build-ords-apis-in-adb/4-workshop-scripts/create_project_table.sql index 2d4e7a2d7..34ea36158 100644 --- a/build-ords-apis-in-adb/4-workshop-scripts/create_project_table.sql +++ b/build-ords-apis-in-adb/4-workshop-scripts/create_project_table.sql @@ -1,25 +1,25 @@ -CREATE TABLE "DEMO_USER"."PROJECT" +CREATE TABLE "PROJECT" ( "PROJ_ID" NUMBER GENERATED BY DEFAULT AS IDENTITY MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 1 CACHE 20 NOORDER NOCYCLE NOKEEP NOSCALE , "PROJ_NAME" VARCHAR2(100 BYTE) COLLATE "USING_NLS_COMP", "DEPT_ID" NUMBER, "IS_ACTIVE" BOOLEAN ) DEFAULT COLLATION "USING_NLS_COMP" ; -CREATE UNIQUE INDEX "DEMO_USER"."PROJ_ID_PK" ON "DEMO_USER"."PROJECT" ("PROJ_ID") +CREATE UNIQUE INDEX "PROJ_ID_PK" ON "PROJECT" ("PROJ_ID") ; -CREATE INDEX "DEMO_USER"."PROJ_DEPARTMENT_IX" ON "DEMO_USER"."PROJECT" ("DEPT_ID") +CREATE INDEX "PROJ_DEPARTMENT_IX" ON "PROJECT" ("DEPT_ID") ; -ALTER TABLE "DEMO_USER"."PROJECT" MODIFY ("PROJ_ID" NOT NULL ENABLE); +ALTER TABLE "PROJECT" MODIFY ("PROJ_ID" NOT NULL ENABLE); -ALTER TABLE "DEMO_USER"."PROJECT" MODIFY ("PROJ_NAME" CONSTRAINT "PROJ_NAME_NN" NOT NULL ENABLE); +ALTER TABLE "PROJECT" MODIFY ("PROJ_NAME" CONSTRAINT "PROJ_NAME_NN" NOT NULL ENABLE); -ALTER TABLE "DEMO_USER"."PROJECT" MODIFY ("DEPT_ID" CONSTRAINT "PROJ_DEPT_ID_NN" NOT NULL ENABLE); +ALTER TABLE "PROJECT" MODIFY ("DEPT_ID" CONSTRAINT "PROJ_DEPT_ID_NN" NOT NULL ENABLE); -ALTER TABLE "DEMO_USER"."PROJECT" ADD CONSTRAINT "PROJ_ID_PK" PRIMARY KEY ("PROJ_ID") +ALTER TABLE "PROJECT" ADD CONSTRAINT "PROJ_ID_PK" PRIMARY KEY ("PROJ_ID") USING INDEX ENABLE; -ALTER TABLE "DEMO_USER"."PROJECT" ADD CONSTRAINT "FK_PROJECT_DEPT" FOREIGN KEY ("DEPT_ID") - REFERENCES "DEMO_USER"."DEPARTMENT" ("DEPT_ID") ENABLE; +ALTER TABLE "PROJECT" ADD CONSTRAINT "FK_PROJECT_DEPT" FOREIGN KEY ("DEPT_ID") + REFERENCES "DEPARTMENT" ("DEPT_ID") ENABLE; diff --git a/build-ords-apis-in-adb/4-workshop-scripts/oauth_client.sql b/build-ords-apis-in-adb/4-workshop-scripts/oauth_client.sql index af61ed7ab..84a77f01f 100644 --- a/build-ords-apis-in-adb/4-workshop-scripts/oauth_client.sql +++ b/build-ords-apis-in-adb/4-workshop-scripts/oauth_client.sql @@ -1,5 +1,6 @@ + -- Generated by ORDS REST Data Services 26.2.3.r2371104 --- Schema: DEMO_USER Date: Thu Sep 17 07:11:13 2026 +-- Schema: ORDSDEMO Date: Tue Sep 29 08:10:52 2026 -- DECLARE @@ -14,24 +15,39 @@ BEGIN ORDS.CREATE_ROLE( p_role_name=> 'my.test.role'); + l_roles(1) := 'my.test.role'; + + ORDS.DEFINE_PRIVILEGE( + p_privilege_name => 'my.test.priv', + p_roles => l_roles, + p_patterns => l_patterns, + p_modules => l_modules, + p_label => 'my.test.priv', + p_description => 'my.test.priv', + p_comments => NULL); + + l_roles.DELETE; + l_modules.DELETE; + l_patterns.DELETE; + ORDS_SECURITY.IMPORT_CLIENT( - p_name => 'my_test_oauth_client', - p_client_id => 'rP9btP7w5Md72r6iEK3Tog..', + p_name => 'my.oauth.client', + p_client_id => 'qMdpq2WHzkzd1aPHawTmvw..', p_grant_type => 'client_credentials', - p_owner => 'DEMO_USER', - p_description => 'my_test_oauth_client', + p_owner => 'ORDSDEMO', + p_description => 'my.oauth.client', p_origins_allowed => NULL, p_redirect_uri => NULL, - p_support_email => 'my_email@example.com', - p_support_uri => 'https://www.my-company.com/support', + p_support_email => 'test@email.com', + p_support_uri => 'https://example.com', p_token_duration => NULL, p_refresh_duration => NULL, p_code_duration => NULL, - p_privilege_names => NULL); + p_privilege_names => 'my.test.priv'); ORDS_SECURITY.GRANT_CLIENT_ROLE( - p_client_name => 'my_test_oauth_client', + p_client_name => 'my.oauth.client', p_role_name => 'my.test.role'); COMMIT; EXCEPTION diff --git a/build-ords-apis-in-adb/4-workshop-scripts/rest_modules.sql b/build-ords-apis-in-adb/4-workshop-scripts/rest_modules.sql index 9a9be8564..c0da96273 100644 --- a/build-ords-apis-in-adb/4-workshop-scripts/rest_modules.sql +++ b/build-ords-apis-in-adb/4-workshop-scripts/rest_modules.sql @@ -1,6 +1,6 @@ -- Generated by ORDS REST Data Services 26.2.3.r2371104 --- Schema: DEMO_USER Date: Thu Sep 17 07:10:41 2026 +-- Schema: ORDSDEMO Date: Tue Sep 29 08:11:27 2026 -- DECLARE @@ -13,15 +13,15 @@ BEGIN ORDS.ENABLE_SCHEMA( p_enabled => TRUE, p_url_mapping_type => 'BASE_PATH', - p_url_mapping_pattern => 'demo_user', - p_auto_rest_auth => TRUE); + p_url_mapping_pattern => 'ordsdemo', + p_auto_rest_auth => FALSE); ORDS.DEFINE_MODULE( p_module_name => 'records.module', p_base_path => '/v1/', p_items_per_page => 25, p_status => 'PUBLISHED', - p_comments => 'An employee records management module consisting of various templates and handlers for performing operations on the following target tables: Department, Project, Employee.'); + p_comments => NULL); ORDS.DEFINE_TEMPLATE( p_module_name => 'records.module', @@ -29,7 +29,7 @@ BEGIN p_priority => 0, p_etag_type => 'HASH', p_etag_query => NULL, - p_comments => 'An example template that will accept the query parameters dept_id and is_active. Relies on ORDS Automatic Binding to take the path parameters and use them in the provided handler code.'); + p_comments => NULL); ORDS.DEFINE_HANDLER( p_module_name => 'records.module', @@ -40,17 +40,7 @@ BEGIN p_mimes_allowed => NULL, p_comments => NULL, p_source => -'SELECT - PROJ_ID, - PROJ_NAME, - DEPT_ID, - IS_ACTIVE -FROM - PROJECT -WHERE - DEPT_ID = :dept_id - AND ( :is_active IS NULL - OR IS_ACTIVE = :is_active )'); +'SELECT PROJ_ID, PROJ_NAME, DEPT_ID, IS_ACTIVE FROM PROJECT WHERE DEPT_ID = :dept_id AND (:is_active IS NULL OR IS_ACTIVE = :is_active)'); ORDS.DEFINE_TEMPLATE( p_module_name => 'records.module', @@ -65,36 +55,35 @@ WHERE p_pattern => 'emp_recs', p_method => 'POST', p_source_type => 'plsql/block', - p_items_per_page => 25, p_mimes_allowed => NULL, p_comments => NULL, p_source => 'DECLARE L_SQLCODE PLS_INTEGER; BEGIN - DEMO_USER.PR_ADD_AND_ASSIGN_EMPLOYEE( + PR_ADD_AND_ASSIGN_EMPLOYEE( P_EMP_NAME => :EMP_NAME, P_DEPT_CODE => :DEPT_CODE, P_COMMENTS => :COMMENTS ); COMMIT; - :STATUS_CODE := 201; - :RESPONSE_STATUS := ''success''; - :RESPONSE_MESSAGE := ''Employee added.''; + :status_code := 201; + :response_status := ''success''; + :response_message := ''Employee added.''; EXCEPTION WHEN OTHERS THEN L_SQLCODE := SQLCODE; ROLLBACK; - :STATUS_CODE := + :status_code := CASE WHEN L_SQLCODE = - 20001 THEN 400 ELSE 500 END; - :RESPONSE_STATUS := ''error''; - :RESPONSE_MESSAGE := + :response_status := ''error''; + :response_message := CASE WHEN L_SQLCODE = - 20001 THEN ''Department code not found.'' @@ -107,8 +96,8 @@ END;'); p_module_name => 'records.module', p_pattern => 'emp_recs', p_method => 'POST', - p_name => 'response_message', - p_bind_variable_name => 'response_message', + p_name => 'response_status', + p_bind_variable_name => 'response_status', p_source_type => 'RESPONSE', p_param_type => 'STRING', p_access_method => 'OUT', @@ -118,8 +107,8 @@ END;'); p_module_name => 'records.module', p_pattern => 'emp_recs', p_method => 'POST', - p_name => 'response_status', - p_bind_variable_name => 'response_status', + p_name => 'response_message', + p_bind_variable_name => 'response_message', p_source_type => 'RESPONSE', p_param_type => 'STRING', p_access_method => 'OUT', @@ -131,11 +120,11 @@ END;'); l_modules(1) := 'records.module'; ORDS.DEFINE_PRIVILEGE( - p_privilege_name => 'my.test.privilege', + p_privilege_name => 'my.test.priv', p_roles => l_roles, p_patterns => l_patterns, p_modules => l_modules, - p_label => 'my.test.privilege', + p_label => 'my.test.priv', p_description => 'my.test.priv', p_comments => NULL); diff --git a/build-ords-apis-in-adb/intro/intro.md b/build-ords-apis-in-adb/intro/intro.md index 405554074..0417b7362 100644 --- a/build-ords-apis-in-adb/intro/intro.md +++ b/build-ords-apis-in-adb/intro/intro.md @@ -4,21 +4,22 @@ In this lab, you will learn about Oracle REST Data Services (ORDS). ORDS makes i You'll discover how easy ORDS makes it to turn your business logic and Create, Read, Update, and Delete (CRUD) operations into APIs. ORDS stores all definitions and metadata in the Oracle database; so operations are highly secure and responsive. ORDS even has its own OAuth2.0 capabilities as well; you'll learn about ORDS Roles, Privileges, and the supported OAuth2.0 Grant Types. -In this lab, you'll perform much of your work in the browser-based UI SQL Developer Web. This lab assumes you have access to an Oracle Autonomous Database 23ai, but ORDS ships automatically in OCI, and is avilable for download for your on-prem, hybrid, and containerized deployments too. +In this lab, you'll perform much of your work in the browser-based UI SQL Developer Web. This lab assumes you have access to an Oracle Autonomous AI Database *Serverless*; where ORDS ships automatically. ORDS is available for download for your on-prem, hybrid, and containerized deployments too. ## About this Workshop In this lab, you will: -- Explore ORDS' SQL Developer Web and the REST Workshop -- Connect to your Autonomous Database 23ai and create new database objects +- Explore SQL Developer Web and the REST Workshop +- Connect to your Autonomous AI Database and create new database objects - Explore automatic and customizable ORDS REST APIs Estimated Workshop Time: 90 minutes ## Objectives - + - Create an Autonomous Database and Connect to your Autonomous Database 23ai + - Create and Auto-REST enable tables - Insert data into the database - Publish ORDS APIs for `GET` and `POST` operations @@ -28,7 +29,7 @@ Estimated Workshop Time: 90 minutes ### About ORDS -Oracle REST Data Services (ORDS) brings the power of REST to your Oracle Database. ORDS, which is included automatically in the Autonomous Database, is highlighted by the following interfaces and capabilities: +Oracle REST Data Services (ORDS) brings the power of REST to your Oracle Database. ORDS, which is included automatically in the Autonomous AI Database, is highlighted by the following interfaces and capabilities: - SQL Developer Web - a browser-based UI for the Oracle database - PL/SQL Gateway - for directe execution of PL/SQL Stored Procedures @@ -42,7 +43,7 @@ Oracle REST Data Services (ORDS) brings the power of REST to your Oracle Databas #### Flexiblity -ORDS ships automatically with the Autonomous Database, but is free to download and deploy. ORDS, a Java EE application, can be deployed to connect to any of your Oracle databases. With a self-managed ORDS deployment you can take advantage of a command-line-based configuration, enhanced security, file caching, JDBC and pool configuration, and enhanced customization for your ORDS RESTful APIs. +ORDS ships automatically with the Autonomous AI Database, but is free to download and deploy. ORDS, a Java EE application, can be deployed to connect to any of your Oracle databases. With a self-managed ORDS deployment you can take advantage of a command-line-based configuration, enhanced security, file caching, JDBC and pool configuration, and enhanced customization for your ORDS RESTful APIs. Oracle REST Data Services can be deployed in a number of ways: - Oracle WebLogic Server @@ -67,8 +68,8 @@ You may now [proceed to the next lab](#next). ### Authors - Jeff Smith, Distinguished Product Manager -- Chris Hoina, Senior Product Manager +- Chris Hoina, Lead Principal Product Manager ## Last Updated By/Date -- Chris Hoina, August 2026 +- Chris Hoina, September 2026 diff --git a/build-ords-apis-in-adb/workshops/desktop/manifest.json b/build-ords-apis-in-adb/workshops/desktop/manifest.json index e1ac19697..9e14c0ce1 100644 --- a/build-ords-apis-in-adb/workshops/desktop/manifest.json +++ b/build-ords-apis-in-adb/workshops/desktop/manifest.json @@ -9,6 +9,7 @@ }, { "title": "Lab 1: Create a user, AutoREST-enable a table, test with cURL", + "type": "desktop", "description": "Modern App Dev with Oracle REST Data Services", "filename": "../../1-create-user-and-database-objects/create-user-and-database-objects.md" },