はじめに
今回はOracle Cloud Infrastructure（OCI）のAutonomous Databaseの
APEX機能のRESTful Servicesを使って、テーブルにAPIでデータを簡単に
登録する方法をご紹介したいと思います。
作成した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の機能を使って
簡単にデータを登録することができました。