# 配置 Oracle Rest Data Services（ORDS）
<a name="Appendix.Oracle.Options.APEX.ORDSConf"></a>

以下主题列出了 ORDS 21 和 22 的配置选项：

**Topics**
+ [安装并配置 ORDS 21 及更低版本](#Appendix.Oracle.Options.APEX.ORDS)
+ [安装和配置 ORDS 22 及更高版本](#Appendix.Oracle.Options.APEX.ORDS22)

## 安装并配置 ORDS 21 及更低版本
<a name="Appendix.Oracle.Options.APEX.ORDS"></a>

现在一切就绪，可以安装和配置用于 Oracle APEX 的 Oracle Rest Data Services (ORDS) 了。对于 Oracle APEX 版本 5.0 及更高版本，请使用 ORDS 版本 19.1 到 21。要了解如何安装 ORDS 22 及更高版本，请参阅[安装和配置 ORDS 22 及更高版本](#Appendix.Oracle.Options.APEX.ORDS22)。

将侦听器安装在单独的主机上，例如 Amazon EC2 实例、公司的本地服务器或您的台式计算机。对于本节中的示例，我们假定您的主机的名称为 `myapexhost.example.com`，并且您的主机运行的是 Linux。

**安装并配置 ORDS 21 及更低版本以与 Oracle APEX 结合使用**

1. 转至 [Oracle REST Data Services](https://www.oracle.com/database/technologies/appdev/rest-data-services-downloads-212.html)，查看自述文件。确保安装了所需的 Java 版本。

1. 为 ORDS 安装创建一个新目录。

   ```
   mkdir /home/apexuser/ORDS
   cd /home/apexuser/ORDS
   ```

1. 从 [Oracle REST data services](https://www.oracle.com/database/technologies/appdev/rest-data-services-downloads-212.html) 下载文件 `ords.version.number.zip`。

1. 将该文件解压缩到 `/home/apexuser/ORDS` 目录中。

1. 如果要将 ORDS 安装到多租户数据库中，请将如下命令行添加到文件 `/home/apexuser/ORDS/params/ords_params.properties`：

   ```
   pdb.disable.lockdown=false
   ```

1. 为主用户授予所需的权限以安装 ORDS。

   在安装 Oracle APEX 的选项后，为主用户提供所需的权限以安装 ORDS 架构。您可以连接到数据库并运行以下命令以完成该操作。将 `MASTER_USER` 替换为主用户的大写名称。
**重要**  
输入用户名时，除非您使用区分大小写的标识符创建了用户，否则请使用大写字母。例如，如果您运行 `CREATE USER myuser` 或 `CREATE USER MYUSER`，则数据字典将存储 `MYUSER`。但是，如果您在 `CREATE USER "MyUser"` 中使用双引号，则数据字典将存储 `MyUser`。有关更多信息，请参阅“[向 SYS 对象授予 SELECT 或 EXECUTE 权限](Appendix.Oracle.CommonDBATasks.TransferPrivileges.md)”。

   ```
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_OBJECTS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_ROLE_PRIVS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_TAB_COLUMNS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_CONS_COLUMNS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_CONSTRAINTS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_OBJECTS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_PROCEDURES', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_TAB_COLUMNS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_TABLES', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_VIEWS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('WPIUTL', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_SESSION', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_UTILITY', 'MASTER_USER', 'EXECUTE', true);
   ```
**注意**  
这些命令适用于 ORDS 版本 19.1 和更高版本。

1. 使用下载的 ords.war 文件安装 ORDS 架构。

   ```
   java -jar ords.war install advanced
   ```

   程序会提示您输入以下信息。括号中为默认值。有关更多信息，请参阅 Oracle 文档中的 [Oracle REST Data Services 简介](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/20.2/aelig/installing-REST-data-services.html#GUID-6F7B4E61-B730-4E73-80B8-F53299123730)。
   + 输入用于存储配置数据的位置：

     输入 */apexuser/ORDS*。这是 ORDS 配置文件的位置。
   + 指定要使用的数据库连接类型。输入 [1] 基本 [2] TNS [3] 自定义 URL [1] 的编号：

     选择所需的连接类型。
   + 输入数据库服务器 [localhost] 的名称：*DB\$1instance\$1endpoint*

     选择默认值或输入正确的值。
   + 输入数据库侦听器端口 [1521]：*DB\$1instance\$1port*

     选择默认值或输入正确的值。
   + 输入 1 以指定数据库服务名称，或输入 2 以指定数据库 SID [1]：

     选择 `2` 以指定数据库 SID。
   + 数据库 SID [xe]

     选择默认值或输入正确的值。
   + 如果要验证/安装 Oracle REST Data Services 架构，请输入 1，或输入 2 以跳过此步骤 [1]：

     选择 `1`。此步骤将创建名为 ORDS\$1PUB\$1USER 的 Oracle REST Data Services 代理用户。
   + 输入 ORDS\$1PUBLIC\$1USER 的数据库密码：

     输入密码，然后确认。
   + 要求使用管理员权限登录以验证 Oracle REST Data Services 架构。

     输入管理员用户名：*master\$1user*

     输入 *master\$1user* 的数据库密码：*master\$1user\$1password*

     确认该密码：*master\$1user\$1password*
**注意**  
作为安全最佳实践，请指定除此处所示提示以外的密码。
   + 输入 ORDS\$1METADATA [SYSAUX] 的默认表空间。

     输入 ORDS\$1METADATA [TEMP] 的临时表空间。

     输入 ORDS\$1PUBLIC\$1USER [USERS] 的默认表空间。

     输入 ORDS\$1PUBLIC\$1USER [TEMP] 的临时表空间。
   + 如果要使用 PL/SQL 网关，请输入 1，或者输入 2 以跳过该步骤。如果使用 Oracle Application Express 或从 mod\$1plsql 迁移，您必须输入 1 [1]。

     选择默认值。
   + 输入 PL/SQL 网关数据库用户名 [APEX\$1PUBLIC\$1USER]

     选择默认值。
   + 输入 APEX\$1PUBLIC\$1USER 的数据库密码：

     输入密码，然后确认。
   + 输入 1 以指定 Application Express RESTful Services 数据库用户（APEX\$1LISTENER、APEX\$1REST\$1PUBLIC\$1USER）的密码，或输入 2 以跳过此步骤 [1]：

     为 APEX 4.1.1.V1 选择 `2`；为所有其他 APEX 版本选择 `1`。
   + [对于 APEX 4.1.1.v1 不需要] APEX\$1LISTENER 的数据库密码

     输入密码（如果需要），然后确认。
   + [对于 APEX 4.1.1.v1 不需要] APEX\$1REST\$1PUBLIC\$1USER 的数据库密码

     输入密码（如果需要），然后确认。
   + 输入一个数字以选择要启用的特征：

     输入 `1` 以启用所有特征：SQL 开发人员 Web、启用 REST 的 SQL 和数据库 API。
   + 如果您希望在独立模式下启动，请输入 1；或输入 2 退出 [1]：

     输入 `1`。
   + 输入 APEX 静态资源位置：

     如果已将 APEX 安装文件解压缩到 `/home/apexuser` 中，请输入 `/home/apexuser/apex/images`。否则，请输入 `unzip_path/apex/images`，其中 *unzip\$1path* 是解压缩文件的目录。
   + 如果使用 HTTP，则输入 1；如果使用 HTTPS，则输入 2 [1]：

     如果您输入 `1`，请指定 HTTP 端口。如果您输入 `2`，请指定 HTTPS 端口和 SSL 主机名。HTTPS 选项提示您指定提供证书的方式：
     + 输入 `1` 以使用自签名证书。
     + 输入 `2` 以提供您自己的证书。如果输入 `2`，请指定 SSL 证书的路径和 SSL 证书私有密钥的路径。

1. 为 APEX `admin` 用户设置密码。为此，请使用 SQL\$1Plus 以主用户身份连接到数据库实例，然后运行以下命令。

   ```
   1. EXEC rdsadmin.rdsadmin_util.grant_apex_admin_role;
   2. grant APEX_ADMINISTRATOR_ROLE to master;
   3. @/home/apexuser/apex/apxchpwd.sql
   ```

   使用主用户名替换 `master`。在 `apxchpwd.sql` 脚本提示您时，输入新的 `admin` 密码。

1. 启动 ORDS 侦听器。运行以下代码。

   ```
   java -jar ords.war
   ```

   首次启动 ORDS 时，系统会提示您提供 APEX 静态资源的位置。此映像文件夹位于 APEX 安装目录下的 `/apex/images` 目录中。

1. 返回浏览器中的 Oracle APEX 管理窗口，然后选择**管理**。接下来选择 **Application Express Internal Administration**。在提示您输入凭证时，请输入以下信息：
   + **用户名** – `admin` 
   + **密码** – 使用 `apxchpwd.sql` 脚本设置的密码 

   选择 **Login**，然后设置 `admin` 用户的新密码。

您的侦听器现在已可以使用。

## 安装和配置 ORDS 22 及更高版本
<a name="Appendix.Oracle.Options.APEX.ORDS22"></a>

现在一切就绪，可以安装和配置用于 Oracle APEX 的 Oracle Rest Data Services (ORDS) 了。对于本节中的示例，我们假定单独主机的名称为 `myapexhost.example.com`，并且主机运行的是 Linux。ORDS 22 的说明与先前版本的说明不同。

**安装并配置 ORDS 22 及更高版本以与 Oracle APEX 结合使用**

1. 转至 [Oracle REST Data Services](http://www.oracle.com/technetwork/developer-tools/rest-data-services/downloads/index.html)，查看您计划下载的 ORDS 版本的自述文件。确保安装了所需的 Java 版本。

1. 为 ORDS 安装创建一个新目录。

   ```
   mkdir /home/apexuser/ORDS
   cd /home/apexuser/ORDS
   ```

1. 从 [Oracle REST Data Services](http://www.oracle.com/technetwork/developer-tools/rest-data-services/downloads/index.html) 下载文件 `ords.version.number.zip` 或 `ords-latest.zip`。

1. 将该文件解压缩到 `/home/apexuser/ORDS` 目录中。

1. 为主用户授予所需的权限以安装 ORDS。

   在安装 `APEX` 选项后，为主用户提供所需的权限以安装 ORDS 架构。您可以登录到数据库并运行以下命令来完成该操作。将 `MASTER_USER` 替换为主用户的大写名称。
**重要**  
输入用户名时，除非您使用区分大小写的标识符创建了用户，否则请使用大写字母。例如，如果您运行 `CREATE USER myuser` 或 `CREATE USER MYUSER`，则数据字典将存储 `MYUSER`。但是，如果您在 `CREATE USER "MyUser"` 中使用双引号，则数据字典将存储 `MyUser`。有关更多信息，请参阅 [向 SYS 对象授予 SELECT 或 EXECUTE 权限](Appendix.Oracle.CommonDBATasks.TransferPrivileges.md)。

   ```
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_OBJECTS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_ROLE_PRIVS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_TAB_COLUMNS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_CONS_COLUMNS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_CONSTRAINTS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_OBJECTS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_PROCEDURES', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_TAB_COLUMNS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_TABLES', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('USER_VIEWS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('WPIUTL', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_SESSION', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_UTILITY', 'MASTER_USER', 'EXECUTE', true);
   
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_LOB', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_ASSERT', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_OUTPUT', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_SCHEDULER', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('HTP', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('OWA', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('WPG_DOCLOAD', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_CRYPTO', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_METADATA', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_SQL', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('UTL_SMTP', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_NETWORK_ACL_ADMIN', 'MASTER_USER', 'EXECUTE', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('SESSION_PRIVS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_USERS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_NETWORK_ACL_PRIVILEGES', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_NETWORK_ACLS', 'MASTER_USER', 'SELECT', true);
   exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_REGISTRY', 'MASTER_USER', 'SELECT', true);
   ```
**注意**  
上述命令适用于 ORDS 22 及更高版本。

1. 使用下载的 `ords` 脚本安装 ORDS 架构。指定要包含配置文件和日志文件的目录。Oracle Corporation 建议不要将这些目录放在包含 ORDS 产品软件的目录中。

   ```
   mkdir -p /home/apexuser/ords_config /home/apexuser/ords_logs
   
   /home/apexuser/ORDS/bin/ords \
     --config /home/apexuser/ords_config \
     install --interactive --log-folder /home/apexuser/ords_logs
   ```

   对于运行容器数据库（CDB）架构的数据库实例，请使用 ORDS 23.3 及更高版本，并在安装 ORDS 时传递 `--pdb-skip-disable-lockdown` 参数。

   ```
   /home/apexuser/ORDS/bin/ords \
     --config /home/apexuser/ords_config \
     install --interactive --log-folder /home/apexuser/ords_logs --pdb-skip-disable-lockdown
   ```

   程序会提示您输入以下信息。括号中为默认值。有关更多信息，请参阅 Oracle 文档中的 [Oracle REST Data Services 简介](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/20.2/aelig/installing-REST-data-services.html#GUID-6F7B4E61-B730-4E73-80B8-F53299123730)。
   + `Choose the type of installation:`

     选择 **2** 可在数据库中安装 ORDS 架构，并在本地 ORDS 配置文件中创建数据库连接池。
   + `Specify the database connection type to use. Enter number for [1] Basic [2] TNS [3] Custom URL:`

     选择所需的连接类型。此示例假设您选择 **1**。
   + `Enter the name of the database server [localhost]:` ***DB\$1instance\$1endpoint***

     选择默认值或输入正确的值。
   + `Enter the database listener port [1521]:` ***DB\$1instance\$1port***

     选择默认值 **1521** 或输入正确的值。
   + `Enter the database service name [orcl]:`

     输入 RDS for Oracle 数据库实例所使用的数据库名称。
   + `Provide database user name with administrator privileges`

      输入 RDS for Oracle 数据库实例的主用户名。
   + `Enter the database password for [username]:`

     输入 RDS for Oracle 数据库实例的主用户密码。
   + `Enter the default tablespace for ORDS_METADATA and ORDS_PUBLIC_USER [SYSAUX]:`
   + `Enter the temporary tablespace for ORDS_METADATA [TEMP]. Enter the default tablespace for ORDS_PUBLIC_USER [USERS]. Enter the temporary tablespace for ORDS_PUBLIC_USER [TEMP].`
   + `Enter a number to select additional feature(s) to enable [1]:`
   + `Enter a number to configure and start ORDS in standalone mode [1]: `

      选择 **2** 可在独立模式下立即跳过启动 ORDS。
   + `Enter a number to select the protocol [1] HTTP`
   + `Enter the HTTP port [8080]:`
   + `Enter the APEX static resources location:`

     输入 Oracle APEX 安装文件的路径（`/home/apexuser/apex/images`）。

1. 为 Oracle APEX `admin` 用户设置密码。为此，请使用 SQL\$1Plus 以主用户身份连接到数据库实例，然后运行以下命令。

   ```
   1. EXEC rdsadmin.rdsadmin_util.grant_apex_admin_role;
   2. grant APEX_ADMINISTRATOR_ROLE to master;
   3. @/home/apexuser/apex/apxchpwd.sql
   ```

   使用主用户名替换 `master`。在 `apxchpwd.sql` 脚本提示您时，输入新的 `admin` 密码。

1. 使用带有 `serve` 命令的 `ords` 脚本在独立模式下运行 ORDS。对于生产部署，可以考虑使用支持的 Java EE 应用程序服务器，例如 Apache Tomcat 或 Oracle WebLogic 服务器。有关更多信息，请参阅 Oracle 数据库文档中的 [Deploying and Monitoring Oracle REST Data Services](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/23.1/ordig/deploying-and-monitoring-oracle-rest-data-services.html#GUID-6791F5DF-AC67-4885-BFFA-B80964C17EC9)。

   ```
   /home/apexuser/ORDS/bin/ords \
     --config /home/apexuser/ords_config serve \
     --port 8193 \
     --apex-images /home/apexuser/apex/images
   ```

   如果 ORDS 正在运行但无法访问 Oracle APEX 安装，您可能会看到以下错误，尤其是在非 CDB 实例上。

   ```
   The procedure named apex_admin could not be accessed, it may not be declared, or the user executing this request may not have been granted execute privilege on the procedure, or a function specified by security.requestValidationFunction configuration property has prevented access.
   ```

   要修复此错误，请通过运行带有 `config` 命令的 `ords` 脚本来更改 ORDS 使用的请求验证函数。默认情况下，ORDS 使用 `ords_util.authorize_plsql_gateway` 程序包，只有 CDB 实例支持该程序包。对于非 CDB 实例，您可以将此程序包更改为 `wwv_flow_epg_include_modules.authorize` 软件包。有关为您的用例配置正确的请求验证函数的最佳实践，请参阅 Oracle 数据库文档和 Oracle Support。

1. 返回浏览器中的 Oracle APEX 管理窗口，然后选择**管理**。接下来选择 **Application Express Internal Administration**。在提示您输入凭证时，请输入以下信息：
   + **用户名** – `admin` 
   + **密码** – 使用 `apxchpwd.sql` 脚本设置的密码 

   选择 **Login**，然后设置 `admin` 用户的新密码。

您的侦听器现在已可以使用。