はじめに

今回はOracle Cloud Infrastructure（OCI）のAutonomous Databaseの
APEX機能のRESTful Servicesを使って、テーブルにAPIでデータを簡単に
登録する方法をご紹介したいと思います。

■参考
https://docs.oracle.com/ja-jp/iaas/autonomous-database/doc/create-applications-ords-autonomous-database.html#GUID-E2E921FF-2D80-4E32-9660-28506D10BADB

作成したADB（Autonomous Database）にデフォルトで付属している
APEXの機能を使ってREST APIを公開し、ローカル環境のPostmanから
json形式のデータをPostしてテーブルにデータを登録します。

■構成

■事前準備
・アカウント
ADBが使用できるOCIアカウントを準備

・ADBの作成
今回作成するADBは外部からアクセスできるようするために
「すべての場所からのセキュア・アクセス」で作成してください。

因みにADBのワークロードタイプはトランザクション系の処理が得意な
ATP（Autonomous Transaction Processing）を使用します。
※もちろん、ADW（Autonomous Data Warehouse）でも構いません。

ADBの作成方法についてはこちらを参考にします。
https://oracle-japan.github.io/ocitutorials/database/adb101-provisioning/

◆目次
1.事前データ登録
2.APEXワークスペースの作成
3.RESTful APIの設定
4.APIのアクセステスト

1.事前データ登録

APEXでAPIを公開する前に予めユーザ作成やデータの登録をしておきます。

作業の流れは以下の通りです。
①ユーザ登録・権限付与
②テーブルの作成
③データ登録

左上メニュー[Ξ]からOracle Database → Autonomous Transaction Processing
を選択します。

予め作成しておいたATPインスタンス名を選択します。

データベース・アクションボタンの中の
「すべてのデータベース・アクションを表示」を選択します。

次のようなメニューが表示されるので「SQL」を選択します。

画面が遷移するとワークシートが表示されるので以下の処理を進めていきます。
①ユーザ登録・権限付与

[ユーザ作成・権限付与SQL]
ユーザ名: testuser001
パスワード: 任意の文字列

CREATE USER testuser001 IDENTIFIED BY "<パスワード>";
GRANT CREATE SESSION TO testuser001;
GRANT CREATE TABLE TO testuser001;
GRANT UNLIMITED TABLESPACE TO testuser001;
GRANT EXECUTE ON DBMS_CRYPTO to testuser001;

※DBMS_CRYPTOはデータをハッシュ値にするためのパッケージで
後続の処理で使うため権限付与しておきます。

SQLの入力が終わったら全てのSQL文を範囲選択し、
実行ボタン（緑の矢印）をクリックします。

データが正常に登録できたら次は以下の処理を進めます。
②テーブルの作成

API登録用テーブルと認証用テーブルを作成するため、
２つ同時にCreate文を入力します。
入力が終わったら範囲選択をし、実行ボタンをクリックします。

[テーブル作成SQL]

--API登録用テーブル
CREATE TABLE testuser001.api_data (
    id NUMBER(10) primary key,
    name VARCHAR2(30)
);

--認証用テーブル
CREATE TABLE testuser001.api_users (
    username VARCHAR2(100) primary key,
    token VARCHAR2(4000)
);

最後に③データ登録としてAPI認証で使うための
認証データを登録します。

[データ登録SQL]

DECLARE
    l_token_raw VARCHAR2(4000) := 'ABCDE123';
    l_token_hash RAW(2000);
BEGIN
    l_token_hash := DBMS_CRYPTO.Hash(UTL_I18N.STRING_TO_RAW(l_token_raw, 'AL32UTF8'), DBMS_CRYPTO.HASH_SH256);
    INSERT INTO testuser001.api_users (username, token) VALUES ('u00001', l_token_hash);
    commit;
END;

今までと同様に上記SQLを範囲選択して、実行ボタンをクリックします。

＜ポイント＞
APIからADBにデータを登録する際に認証をかけるのですが、
パスワードを平文のままテーブルに格納するのはセキュリティ上よろしくないので
ここではハッシュ化したデータとして登録しています。
※前段で権限付与したDBMS_CRYPTOパッケージを使ってハッシュ化しています。

username = u00001
token = ABCDE123
というレコードを登録しておき、認証として使います。

以上で事前準備は終了です。

2.APEXワークスペースの作成

ここでは前段の処理で作成したtestuser001用のワークスペースを作成します。

データベース・アクションボタンの中の
「すべてのデータベース・アクションを表示」を選択し、
画面遷移後に「APEX」を選択します。

APEXの認証画面が表示されるので、ATP作成時に設定した
adminのパスワードを入力してサインインします。

サインイン後に次のような画面となるので、
「Create Workspace」をクリックします。

※上部のManage WorkspacesからでもCreate Workspaceを実行できます。

この画面では「Existing Schema」を選択します。

次の画面ではユーザ等を入力する画面となっているため
任意の文字列を入力します。

ここでは以下のように入力しています。
Database User: TESTUSER001
Workspace Name: TESTUSER001
Workspace UserName: TESTUSER001
Workspace Password: <任意の文字列>

次のような画面になれば正常に処理は終了です。

以上でAPEXワークスペースの作成は終了です。

3.RESTful APIの設定

続いてRESTful APIの設定に進みますので、再度APEXに入り直します。

APEXを起動するとサインイン画面が前回とは少し変わっていますので、
そのままワークスペースにサインインします。
（ワークスペースができるとデフォルトがワークスペース用サインインとなります）

※adminでサインインする場合は最下部のAdministration Servicesを選択します。

サインインは前段で登録した以下の情報です。
Workspace: TESTUSER001
Database UserName: TESTUSER001
Workspace Password: <任意の文字列>

サインインすると次の画面となるため、「SQL Workshop」を選択します。

次に「RESTful Services」を選択します。

続いてORDSの有効化をします。

デフォルトのまま「Save Schema Attributes」を選択します。

これで初期設定ができました。

次は「Modules」→「Create Module」を選択します。

「Module Name」と「Base Path」を入力して「Create Module」を選択します。

ここでは以下のようにしています。
Module Name = md_api_insert
Base Path = md_api_insert

Moduleが作成されると次のようになります。

そのまま下にスクロールすると「Create Template」が表示されているので
それを選択します。

「URI Template」を入力して、「Create Template」を選択します。

ここでは以下を設定しています。
URI Template = api_data

Templateが作成されると次のようになります。

続いて下にスクロールすると「Create Handler」が表示されるので
それを選択します。

HandlerではMethodでPOSTを選択します。

下にスクロールするとSource入力欄が表示されるので
ここにコード・SQLを入力します。

DECLARE
    l_authorization VARCHAR2(4000);
    l_token_raw VARCHAR2(4000);
    l_token_hash RAW(2000);
    l_user_exists NUMBER;
BEGIN
    -- HTTPヘッダーから認証情報を取得
    l_authorization := owa_util.get_cgi_env('AUTHORIZATION');

    -- Bearer認証情報を取得（形式：Bearer <Token>）
    IF l_authorization IS NOT NULL AND l_authorization LIKE 'Bearer %' THEN
        l_token_raw := substr(l_authorization, 8);

        -- トークンをハッシュ化
        l_token_hash := DBMS_CRYPTO.Hash(UTL_I18N.STRING_TO_RAW(l_token_raw, 'AL32UTF8'), DBMS_CRYPTO.HASH_SH256);

        -- データベースでハッシュ値を検証
        SELECT COUNT(*) INTO l_user_exists FROM api_users WHERE token = l_token_hash;
        IF l_user_exists = 0 THEN
            -- 認証失敗
            htp.print('{"status": "failure", "message": "Unauthorized"}');
            RETURN;
        END IF;
    ELSE
        -- 認証情報がない場合はエラー
        htp.print('{"status": "failure", "message": "No Authorization header"}');
        RETURN;
    END IF;

    -- データの挿入を試みる
    BEGIN
        INSERT INTO api_data (id, name) VALUES (:id, :name);
        -- 挿入成功
        htp.print('{"status": "success", "message": "Data inserted successfully"}');
    EXCEPTION
        WHEN OTHERS THEN
            -- 挿入失敗
            htp.print('{"status": "failure", "message": "Data insertion failed"}');
    END;
END;

入力が終わったら上部の「Create Handler」を実行します。

正常に登録が完了すると次のような画面となります。
Full URLはAPIのエンドポイントとなるため保存しておきます。

以上でRESTful APIの設定は終了です。

4.APIのアクセステスト

最後にAPEX RESTful APIのアクセステストを実施してみます。

Postmanを起動したら以下情報を入力します。

[Method] POST
[Endpoint] APEX Restful APIで設定したFull URL
[Header]
Content-Type: application/json
Authorization: Bearer ABCDE123
[Body]
{
　　"id": 1,
　　"name": "APIテスト"
}

データ登録が正常に処理されると以下のような
メッセージが返ってきます。

SQLでも登録されていることが確認できます。

因みにわざと認証を間違えるとUnauthorizedとなるようになっています。

おわり

以上、ADBに付属しているAPEXのRESTful APIの機能を使って
簡単にデータを登録することができました。