Oracle APEXでREST APIを呼び出す方法 - APEX_WEB_SERVICE実践ガイド
はじめに
Oracle APEXで開発していると、外部システムとの連携が必要になることがよくあります。
例えば、
- 顧客管理システム(CRM)からデータ取得
- OCI Object Storageへのファイルアップロード
- SlackやTeamsへの通知
- 外部認証サービスとの連携
- 他システムへのデータ送信
このような場合、REST APIを呼び出す必要があります。
Oracle APEXには標準で APEX_WEB_SERVICE パッケージが用意されており、PL/SQLから簡単にREST APIを利用できます。
本記事では以下を紹介します。
- GET API
- POST API
- リクエストヘッダー設定
- JSONレスポンス解析
- エラーハンドリング
- 実務で役立つベストプラクティス
APEX_WEB_SERVICEとは
APEX_WEB_SERVICE はOracle APEXが提供するパッケージであり、外部のREST APIやSOAP Web Serviceを呼び出すことができます。
最もよく利用されるのが以下のメソッドです。
APEX_WEB_SERVICE.MAKE_REST_REQUEST
構文：
l_response := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
p_url => l_url,
p_http_method => 'GET'
);
戻り値はCLOBです。
GET APIを呼び出す
まずは最もシンプルなGETリクエストです。
今回はサンプルAPIとしてJSONPlaceholderを利用します。
https://jsonplaceholder.typicode.com/users/1
サンプルコード
DECLARE
l_response CLOB;
BEGIN
l_response :=
APEX_WEB_SERVICE.MAKE_REST_REQUEST(
p_url => 'https://jsonplaceholder.typicode.com/users/1',
p_http_method => 'GET'
);
DBMS_OUTPUT.PUT_LINE(l_response);
END;
/
実行結果：
{
"id":1,
"name":"Leanne Graham",
"username":"Bret"
}
HTTPステータスコードを取得する
API実行後は必ずステータスコードを確認しましょう。
DECLARE
l_response CLOB;
BEGIN
l_response :=
APEX_WEB_SERVICE.MAKE_REST_REQUEST(
p_url => 'https://jsonplaceholder.typicode.com/users/1',
p_http_method => 'GET'
);
DBMS_OUTPUT.PUT_LINE(
'Status=' || APEX_WEB_SERVICE.G_STATUS_CODE
);
END;
/
結果：
Status=200
よく利用するステータス：
| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |
リクエストヘッダーを設定する
多くのAPIでは認証トークンやContent-Typeの指定が必要です。
ヘッダーは
APEX_WEB_SERVICE.G_REQUEST_HEADERS
を使用します。
例：
BEGIN
APEX_WEB_SERVICE.G_REQUEST_HEADERS.DELETE;
APEX_WEB_SERVICE.G_REQUEST_HEADERS(1).name :=
'Authorization';
APEX_WEB_SERVICE.G_REQUEST_HEADERS(1).value :=
'Bearer xxxxxxxxx';
APEX_WEB_SERVICE.G_REQUEST_HEADERS(2).name :=
'Content-Type';
APEX_WEB_SERVICE.G_REQUEST_HEADERS(2).value :=
'application/json';
END;
/
POST APIを呼び出す
データ作成APIを呼び出す場合です。
送信JSON
{
"title":"Qiita",
"body":"Oracle APEX",
"userId":1
}
サンプルコード
DECLARE
l_response CLOB;
l_body CLOB;
BEGIN
l_body :=
'{
"title":"Qiita",
"body":"Oracle APEX",
"userId":1
}';
APEX_WEB_SERVICE.G_REQUEST_HEADERS.DELETE;
APEX_WEB_SERVICE.G_REQUEST_HEADERS(1).name :=
'Content-Type';
APEX_WEB_SERVICE.G_REQUEST_HEADERS(1).value :=
'application/json';
l_response :=
APEX_WEB_SERVICE.MAKE_REST_REQUEST(
p_url => 'https://jsonplaceholder.typicode.com/posts',
p_http_method => 'POST',
p_body => l_body
);
DBMS_OUTPUT.PUT_LINE(l_response);
END;
/
JSONレスポンスを解析する
戻り値はCLOBなので、JSON_OBJECT_Tで解析できます。
APIレスポンス：
{
"id":1,
"name":"John"
}
解析：
DECLARE
l_response CLOB;
l_json JSON_OBJECT_T;
BEGIN
l_response :=
APEX_WEB_SERVICE.MAKE_REST_REQUEST(
p_url => 'https://jsonplaceholder.typicode.com/users/1',
p_http_method => 'GET'
);
l_json := JSON_OBJECT_T.parse(l_response);
DBMS_OUTPUT.PUT_LINE(
l_json.get_string('name')
);
END;
/
結果：
John
OCI Object Storageでよく使う例
OCI Object Storageとの連携では以下のような実装になります。
APEX_WEB_SERVICE.G_REQUEST_HEADERS(1).name :=
'Authorization';
APEX_WEB_SERVICE.G_REQUEST_HEADERS(1).value :=
'Bearer ' || l_token;
ファイルアップロード：
APEX_WEB_SERVICE.MAKE_REST_REQUEST(
p_url => l_upload_url,
p_http_method => 'PUT',
p_body_blob => l_blob
);
ファイル削除：
APEX_WEB_SERVICE.MAKE_REST_REQUEST(
p_url => l_delete_url,
p_http_method => 'DELETE'
);
このあたりはOCI連携を行う際によく利用します。
エラーハンドリング
実務では必須です。
DECLARE
l_response CLOB;
BEGIN
l_response :=
APEX_WEB_SERVICE.MAKE_REST_REQUEST(
p_url => l_url,
p_http_method => 'GET'
);
IF APEX_WEB_SERVICE.G_STATUS_CODE != 200 THEN
RAISE_APPLICATION_ERROR(
-20001,
'API Error : '
|| APEX_WEB_SERVICE.G_STATUS_CODE
);
END IF;
EXCEPTION
WHEN OTHERS THEN
DBMS_OUTPUT.PUT_LINE(
SQLERRM
);
END;
/
ベストプラクティス
1. ステータスコードを必ず確認する
APEX_WEB_SERVICE.G_STATUS_CODE
をチェックする。
2. ヘッダーは毎回初期化する
APEX_WEB_SERVICE.G_REQUEST_HEADERS.DELETE;
前回実行の値が残ることがあります。
3. URLパラメータはエンコードする
ファイル名や日本語を含む場合：
UTL_URL.ESCAPE(
l_file_name,
TRUE,
'UTF-8'
)
を利用する。
4. タイムアウトを考慮する
外部APIは必ずしも高速とは限りません。
大量データ取得時はバッチ処理化を検討しましょう。
まとめ
Oracle APEXでは APEX_WEB_SERVICE を利用することで簡単にREST APIを呼び出すことができます。
よく利用する機能は以下です。
- GET
- POST
- PUT
- DELETE
- Authorization Header
- JSON Parsing
- Status Code Check
OCI Object Storageや外部サービス連携を行う際には必須の知識になるため、ぜひ活用してみてください。