顧客管理ORDSを作成しADBのOracle APEXに接続する

この記事ではORDSをインストールしたインスタンスを準備し、そのORDSインスタンスを経由してOracle APEXにアクセスする手順を示します。


# はじめに
Oracle APEX（以下APEX）は、Oracle Database上で動作するローコードのWebアプリケーション開発ソフトウェアです。ユーザーはWebブラウザからAPEXにアクセス可能で、WebリクエストはOracle REST Data Services（ORDS）を通じてデータベースに接続されます。この関係については、以下のサイト[^1] [^2]を参考にしてください。

https://apex.oracle.com/ja/platform/architecture/

https://docs.oracle.com/cd/F70953_01/htmig/about-apex-architecture.html

Autonomous Database（ADB）を利用する際にはORDSもデフォルトで準備されており、追加の設定作業なしにAPEXを使うことができます。ただし、ADBがOracleによって管理されているため、デフォルトのORDSもOracleの管理下にあり、ユーザーはORDSの設定ファイルを変更することができません。そのため、自身が管理する環境で動作するように構成したい場合には、ORDSをインストールした環境を別途用意する必要があります。[^3]


>Autonomous DatabaseでデフォルトのORDSを使用する場合、ORDSの設定オプションを変更することはできない。たとえば、デフォルトの構成では、JDBC接続プールの最大接続数は100であり、ORDSの接続はLOWデータベースサービスを使用するように事前に構成されています。Oracle REST Data Services の構成と管理を手動で制御したい場合は、カスタマ管理環境を使用します。たとえば、アプリケーションでより大きな接続プールが必要な場合や、ORDSの構成オプションをより詳細に制御する必要がある場合は、このオプションを使用します。
（DeepLにて翻訳）


ORDSはホストサーバーとして「WebLogic」「Apache Tomcat」がサポートされますが [^4])、この記事ではORDS単体で動作する、スタンドアロンモードを使用することとします。

<details><summary>参考：インスタンス環境</summary>

```: OS
$ cat /etc/os-release
NAME="Oracle Linux Server"
VERSION="8.9"
ID="ol"
ID_LIKE="fedora"
VARIANT="Server"
VARIANT_ID="server"
VERSION_ID="8.9"
PLATFORM_ID="platform:el8"
PRETTY_NAME="Oracle Linux Server 8.9"
ANSI_COLOR="0;31"
CPE_NAME="cpe:/o:oracle:linux:8:9:server"
HOME_URL="https://linux.oracle.com/"
BUG_REPORT_URL="https://github.com/oracle/oracle-linux"

ORACLE_BUGZILLA_PRODUCT="Oracle Linux 8"
ORACLE_BUGZILLA_PRODUCT_VERSION=8.9
ORACLE_SUPPORT_PRODUCT="Oracle Linux"
ORACLE_SUPPORT_PRODUCT_VERSION=8.9
```


```: カーネル
$ uname -a
Linux inst-edge01 5.15.0-205.149.5.1.el8uek.aarch64 #2 SMP Fri Apr 5 13:37:11 PDT 2024 aarch64 aarch64 aarch64 GNU/Linux
```

</details>

# ADBからウォレットをダウンロードする
OCIコンソールの[Autonomous Databaseの詳細]画面から、ウォレットをダウンロードしておきます。
[データベース接続]を選択し、
![database_connection.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3761799/801d6fd6-4bbf-33ec-0ef7-1472923c0a3f.png)

タイプは[インスタンス・ウォレット]を選び[ウォレットのダウンロード]をクリック。
![wallet_download.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3761799/8bb303c6-f61a-296a-2c38-88e7a8d0cbc1.png)

パスワードを入力し、[ダウンロード]を選択するとウォレットがダウンロードされます。
![wallet_password.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3761799/6a6db32c-6bb9-3bea-6855-5d9b2f97ff4f.png)

ダウンロードしたウォレットは、ORDSインスタンスへ転送しておきます。oracleユーザーで設定を行うので、以下`/home/oracle`にウォレット`Wallet_orcl.zip`があるものとします。

# ORDSの導入
ORDSの動作のためにはJavaが必要になりますので、両者のインストール手順を含めます。
インストールするバージョンは以下の通りです。
- ORDS 24.1
- Java 17

## Javaのインストール
ORDS 24.1はJava 11か17を準備する必要があるため [^4]、今回はJDK17をインストールします。


利用可能なパッケージにJava 17があるかを検索します。
```
sudo dnf search openjdk
```
上記コマンド結果にバージョン17があれば、以下のコマンドでインストールします。
```
sudo dnf install java-17-openjdk
```

```
$ sudo dnf -y install java-17-openjdk
Last metadata expiration check: 0:26:15 ago on Sun 12 May 2024 03:57:16 AM GMT.
Dependencies resolved.
================================================================================
 Package                  Arch    Version                  Repository      Size
================================================================================
Installing:
 java-17-openjdk          aarch64 1:17.0.11.0.9-2.0.1.el8  ol8_appstream  444 k
Installing dependencies:
 adwaita-cursor-theme     noarch  3.28.0-3.el8             ol8_appstream  647 k
 adwaita-icon-theme       noarch  3.28.0-3.el8             ol8_appstream   11 M
...
  xorg-x11-font-utils-1:7.5-41.el8.aarch64
  xorg-x11-fonts-Type1-7.5-19.el8.noarch

Complete!
```
<br>

これでJavaのインストールは完了です。一応確認しておきます。
```
$ java --version
openjdk 17.0.11 2024-04-16 LTS
OpenJDK Runtime Environment (Red_Hat-17.0.11.0.9-3.0.1) (build 17.0.11+9-LTS)
OpenJDK 64-Bit Server VM (Red_Hat-17.0.11.0.9-3.0.1) (build 17.0.11+9-LTS, mixed mode, sharing)
```

## ORDSのインストール
OL7とOL8リポジトリがdnf(yum)の構成に入っている場合、`dnf`を利用してダウンロードができます。この記事では`dnf`でインストールを行います。インストールされるバージョンは24.1です。
```
$ sudo dnf -y  install ords
...
Installed:
  ords-24.1.1-4.el8.noarch

Complete!
```
ほかのインストール方法についての詳細は[Oracleのドキュメント](https://docs.oracle.com/cd/F87063_01/ordig/installing-and-configuring-oracle-rest-data-services.html#GUID-A12A1E26-3AE1-4DB9-901B-2168613D467A)[^3]を参照ください。



# ADBへの接続設定
## CDNの設定
APEXで用いる静的リソースの設定を行う必要があるのですが、OracleはCDNを使用することを推奨しています。[^3]
    そのためまずは、その設定パラメータである置換文字列`IMAGE_PREFIX`[^5]に現在設定されている値を確認します。

ADB詳細画面から[データベース・アクション]から[SQL]を選択し、SQLの実行環境にアクセス。
![databaseaction_SQL.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3761799/95668456-0e05-c48a-15e5-f831fdc817e3.png)

以下のSQLを実行します。（APEX_INSTANCE_ADMIN.GET_PARAMETERファンクションについては[こちら](https://docs.oracle.com/en/database/oracle/apex/23.2/aeapi/GET_PARAMETER-Function.html#GUID-6BA9A60E-9B0A-4AE5-98DB-68E229008CE0)）[^6]
```: 'IMAGE_PREFIX'を確認する
SELECT APEX_INSTANCE_ADMIN.GET_PARAMETER(p_parameter => 'IMAGE_PREFIX') 
FROM dual;
```


また、APEXのバージョンについては以下のSQLでも確認できます。
```: APEXのバージョンを確認する
SELECT * FROM APEX_RELEASE;
```

出力結果から出たバージョンを参考に、以下のPL/SQL文で`https://static.oracle.com/cdn/apex/<version>/`へと書き換えます。[^7])今回は`https://static.oracle.com/cdn/apex/23.2.3/`に設定します。[^8]
```
begin
    apex_instance_admin.set_parameter(
        p_parameter => 'IMAGE_PREFIX',
        p_value     => 'https://static.oracle.com/cdn/apex/23.2.3/' );
    commit;
end;
```

`SELECT APEX_INSTANCE_ADMIN.GET_PARAMETER(p_parameter => 'IMAGE_PREFIX') 
FROM dual;`で設定が正しく反映されたかを確認しておきます。URLに`/i/`が入っていないかにも注意しておきましょう。（一敗）

## ORDSの設定
oracleユーザーに切り替えたのち、ordsコマンドにて、設定を行います。ADBのウォレットのパスは`/home/oracle/Wallet_orcl.zip`としています。

```
ords install adb --interactive --prompt-password
```

プロンプトにて入力を求められる項目については[Oracleのドキュメント](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/24.1/ordig/installing-and-configuring-customer-managed-ords-autonomous-database.html#GUID-FE64CE0E-1BEE-406A-AA41-00D3BAC2A988)[^3])を参考にしてください。 [^9]
```
$ sudo su - oracle
$ ords install adb --interactive --prompt-password
2024-05-12T06:35:09Z INFO       ORDS has not detected the option '--config' and this will be set up to the default directory.

ORDS: Release 24.1 Production on Sun May 12 06:35:12 2024

Copyright (c) 2010, 2024, Oracle.

Configuration:
  /etc/ords/config

The configuration folder /etc/ords/config does not contain any configuration files.

Oracle REST Data Services - Interactive Customer Managed ORDS for Autonomous Database

  Enter the Autonomous Database Wallet path: /home/oracle/Wallet_orcl.zip
  Enter a number to select the TNS Network alias to use
    [1] ORCL_LOW     SERVICE_NAME=xxxxxxxxxx_orcl_low.adb.oraclecloud.com
    [2] ORCL_MEDIUM  SERVICE_NAME=xxxxxxxxxx_orcl_medium.adb.oraclecloud.com
    [3] ORCL_HIGH    SERVICE_NAME=xxxxxxxxxx_orcl_high.adb.oraclecloud.com
    [4] ORCL_TP      SERVICE_NAME=xxxxxxxxxx_orcl_tp.adb.oraclecloud.com
    [5] ORCL_TPURGENT SERVICE_NAME=xxxxxxxxxx_orcl_tpurgent.adb.oracleclou...
  Choose [1]:
  Provide database user name with administrator privileges.
    Enter the administrator username [ADMIN]:
  Enter the database password for ADMIN:
Connecting to Autonomous database user: ADMIN TNS Service: ORCL_LOW
  Enter the ORDS runtime database username [ORDS_PUBLIC_USER2]:
  Enter the database password for ORDS_PUBLIC_USER2:
Confirm password:
  Enter the PL/SQL Gateway database username: ORDS_PLSQL_GATEWAY2
  Enter the database password for ORDS_PLSQL_GATEWAY2:
Confirm password:
Retrieving information
Checking Autonomous database user: ORDS_PUBLIC_USER2 TNS Service: ORCL_LOW
  Enter a number to select additional feature(s) to enable:
    [1] Database Actions  (Enables all features)
    [2] REST Enabled SQL and Database API
    [3] REST Enabled SQL
    [4] Database API
    [5] None
  Choose [1]:
  Enter a number to configure and start ORDS in standalone mode
    [1] Configure and start ORDS in standalone mode
    [2] Skip
  Choose [1]:
  Enter a number to select the protocol
    [1] HTTP
    [2] HTTPS
  Choose [1]:
  Enter the HTTP port [8080]: 8080
...
Mapped local pools from /etc/ords/config/databases:
  /ords/                              => default                        => VALID

2024-05-12T07:00:51.321Z INFO        Oracle REST Data Services initialized
Oracle REST Data Services version : 24.1.1.r1201228
Oracle REST Data Services server info: jetty/10.0.20
Oracle REST Data Services java info: OpenJDK 64-Bit Server VM 17.0.11+9-LTS
```

# ORDSに接続
先ほど選択したプロトコルによって手順が変わります。
```
  Enter a number to select the protocol
    [1] HTTP
    [2] HTTPS
  Choose [1]:
  Enter the HTTP port [8080]: 8080
  ```
## HTTPで接続
8080番ポートを開放し、ordsを起動します。
```
# firewall-cmd --zone=public --add-port=8080/tcp --permanent
success
# firewall-cmd --reload
success
```
```
# systemctl start ords
```
その後、Webブラウザにて`http://<hostname>:8080/ords`に接続すると、以下のような画面に接続できます。
![ords.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3761799/3356ff19-c24c-86f6-ae88-311e359eea69.png)

HTTP通信を使用している状況で、Oracle APEXの「実行」オプションを選択すると`ERR_SSL_PROTOCOL_ERROR`エラーが発生することがあります。この問題は、ORDSからAPEXへの接続がHTTPSに設定されているために起こるため、別の手段でAPEXにアクセスし設定を変える必要があります。

ADBの場合、OCIコンソール上からAPEXへのリンクを取得できます。
![apex_link.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3761799/64e0a14c-161c-8142-a88e-6555438c13f2.png)

取得したURLから管理者コンソールにログインし、[インスタンスの管理]→[セキュリティ]→[HTTPプロトコル]と遷移し、[HTTPSが必要]項目を変更することによって解決します。詳しくは[こちら](https://docs.oracle.com/en/database/oracle/apex/23.2/aeadm/configuring-http-attributes.html#GUID-80DE2314-038F-4B7C-8EFD-F99F3E326E82)[^10])を参照ください。

![apex_http_protcol.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3761799/82ad1c8b-52a8-e0f7-97c2-3ebe2f5474d9.png)


## HTTPSで接続
HTTPS接続の場合、秘密鍵の生成と証明書の設定が別途必要になります。具体的な手順については、別の記事に記載する予定です。


# 引用・参考
記事で使用したバージョンとドキュメントのバージョンが異なる場合があります。ご注意ください。

[^1]: "APEX アーキテクチャ", https://apex.oracle.com/ja/platform/architecture/

[^2]: "Oracle APEXアーキテクチャについて", https://docs.oracle.com/cd/F70953_01/htmig/about-apex-architecture.html

[^3]: "Installing and Configuring Customer Managed ORDS on Autonomous Database", https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/24.1/ordig/installing-and-configuring-customer-managed-ords-autonomous-database.html#GUID-DE69D4CB-A2EF-49BD-B283-76CB255489C0

[^4]: "Oracle REST Data Services Installation Checklist", 
https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/24.1/ordig/installing-REST-data-services.html#GUID-F6A4F94A-D62F-4A35-A471-6306332DF522

[^5]: "置換文字列の使用（3.9.4.28 IMAGE_PREFIX）", https://docs.oracle.com/cd/F39413_01/htmdb/understanding-substitution-strings.html#GUID-2903142F-17A1-4DF4-956C-1CC0A238A4E4

[^6]: "GET_PARAMETER Function", https://docs.oracle.com/en/database/oracle/apex/23.2/aeapi/GET_PARAMETER-Function.html#GUID-6BA9A60E-9B0A-4AE5-98DB-68E229008CE0

[^7]: "Announcing Oracle APEX Static Resources on Content Delivery Network", https://blogs.oracle.com/apex/post/announcing-oracle-apex-static-resources-on-content-delivery-network

[^8]: "Running Customer Managed ORDS on Autonomous Database? Here's how to get ready for APEX 21.1 Upgrade", https://blogs.oracle.com/apex/post/running-customer-managed-ords-on-autonomous-database-heres-how-to-get-ready-for-apex-211-upgrade

[^9]: "Customer Managed ORDSの構成(1) - インストールと構成", https://apexugj.blogspot.com/2022/11/customer-managed-ords-1-install.html

[^10]: "Configuring HTTP Protocol Attributes", https://docs.oracle.com/en/database/oracle/apex/23.2/aeadm/configuring-http-attributes.html#GUID-80DE2314-038F-4B7C-8EFD-F99F3E326E82