2025年1月22日水曜日

Oracle APEX 24.2のRESTデータ・ソースのトークンによるページネーションのサポートを確認する

Oracle APEX 24.2のRESTデータ・ソースで新たに、ページ・サイズとページ・トークンによるページネーションがサポートされました。以前に記事「東京都のオープンデータAPIを呼び出してデータを取得する」で、PL/SQLを使って東京都が提供しているオープンデータAPIを呼び出す方法を紹介していますが、APEX 24.2からはPL/SQLのコーディングは必要なく、RESTデータ・ソースの設定だけでページネーションに対応できます。

以下より、東京都のオープンデータAPIを呼び出して文化財一覧のデータを取得し、Oracle APEXでレポートなどを表示するアプリケーションを作成してみます。

作成したAPEXアプリケーションは、以下のように動作します。


今回使用するAPIは、東京都の以下のページで紹介されています。

オープンデータAPIについて

この中のCulturalPropertyを呼び出します。

以下より、アプリケーションの作成手順を紹介します。

最初に空のAPEXアプリケーションを作成します。名前はTokyo Metropolitan Government Open Data APIとします。


アプリケーションが作成されたら、共有コンポーネントのRESTデータ・ソースを開きます。


作成済みのRESTデータ・ソースが一覧されます。作成をクリックします。


RESTデータ・ソースの作成はデフォルトの最初からのまま変更せず、次へ進みます。


東京都のオープンデータAPIのエンドポイントを設定します。

RESTデータ・ソース・タイプは簡易HTTPです。名前はTokyo Cultural Propertiesとします。URLエンドポイントの指定は以下になります。

https://api.data.metro.tokyo.lg.jp/v1/CulturalProperty

次へ進みます。


リモート・サーバーの設定に移ります。リモート・サーバーが未設定の場合は- 新規作成 -となります。自動的に検出されたベースURLやサービスURLパスは、通常は変更不要です。

次へ進みます。


東京都のオープンデータAPIのページネーションの仕組みを設定します。

東京都のオープンデータAPIは、以下の形式でレスポンスを返します。
[
    [
         { 文化財1のJSONデータ },
         { 文化財2のJSONデータ },
         ....
         { 文化財NのJSONデータ }
    ],
    {
         "endCursor": "後続のAPI呼び出しの引数cursorに与える値",
         "moreResults": "MORE_RESULTS_AFTER_LIMIT",
         ...
     }
]
よって、ページネーションとして以下の設定を行います。

ページ区切りタイプとしてページ・サイズとページ・トークンを選択します。APIの仕様よりページ・サイズURLパラメータにlimit、ページ・サイズ最大に100を設定します。設定可能な仕様上の最大値は1000です。

ページ・トークンURLパラメータはcursor、次のページ・トークン・セレクタは[1].endCursorです。REST APIのレスポンスよりセレクタ$[1].endCursor（内部で指定したセレクタの先頭に$を付けます）で取り出した値が、続けて発行されるREST APIの引数cursorに割り当てられます。

東京都のオープンデータAPIの仕様では、moreResultsの値がMORE_RESULTS_AFTER_LIMITであれば追加のデータが存在し、moreResultsがNO_MORE_RESULTSであれば、データの終了となっています。

この仕様に合わせて、その他の行セレクタとして[1].moreResultsを指定し、次の値のときのその他の行に次と等しい、その他の行属性値としてmore_results_after_limitを設定します。その他の行属性値は英小文字で記述します。現在は、大文字小文字を区別せずに一致を確認するために、取り出した文字列を一律で小文字に変換しその他の行属性値に指定した値と比較しています。そのため、その他の行属性値を小文字で指定する必要があります。製品の不具合として、将来の修正対象となっています。

ページ区切りタイプがページ・サイズとページ・トークンである場合、その仕組みより順方向のページングのみが可能です。ページ番号またはフェッチ・オフセットが引数として与えられないため、中間のデータだけが欲しい場合でも、つねにデータの先頭から順番に読み出す必要があります。そのため、多数のREST APIを発行し、何度も同じデータを取得することが起こり得ます。

この点については、Oracle APEXのRESTデータ・ソースの同期化を構成して、ローカル・データベースに取得したデータを保存することで対応することにします。

次へ進みます。


認証は不要なのでオフのままにします。そのまま検出をクリックします。


東京都のオープンデータAPIが呼び出され、文化財一覧のデータが取得されます。しかし、表示は１行だけで、UpdatedやRevisionといった、文化財とは関係ないデータが表示されます。これは、東京都のオープンデータAPIが配列の2番目の要素として返している、REST APIリクエストのメタデータです。

レスポンス本文を開くと、実際に受信されたデータを確認できます。


受信したデータを確認したのち、データ・プロファイルを開き、不要な属性を削除します。


検出された属性のうち、セレクタに@typeを含む属性はOracle APEXで扱うことはありません。また、REST APIのメタデータに関する属性も不要です。

以下の名前の属性を削除します。

C_TYPE, 参照__TYPE, 名称__TYPE, UPDATED, REVISION, ENDCURSOR, EX_員数__TYPE, 管理者__TYPE, 管理者_種別コード__TYPE, MORERESULTS, 権利管理__TYPE, 設置地点__TYPE, 設置地点_住所__TYPE, 設置地点_連絡先__TYPE, 設置地点_地理座標__TYPE, 設置地点_利用可能時間__TYPE, メタデータ__TYPE, メタデータ_作成者__TYPE, EX_文化財指定日__TYPE




検出された52の属性から19の属性を削除し、結果として33個の属性を持ったRESTデータ・ソースを作成します。

RESTデータ・ソースの作成をクリックします。


RESTデータ・ソースTokyo Cultural Propertiesが作成されます。RESTソース名をクリックし、作成されたRESTデータ・ソースをさらに調整します。


データ・プロファイルの編集をクリックします。


列ID、EX_員数_数値、設置地点_地理座標_経度、設置地点_地理座標_緯度、メタデータ_作成者_IDのデータ型が数値になっています。実際には数値としては扱えないデータが含まれていることがあります。そのため、数値のままだとエラーが発生します。


エラーの発生を回避するため、これらの列のデータ型をすべてVarchar2に変更します。長さは4000とします。数値として扱う場合は、APEXのアプリケーション側でto_numberを呼び出して数値に変換します。


列IDは本来主キーとして設定できるはずなのですが、APIのレスポンスに空行が含まれているため、列IDの主キーをオンにするとエラーが発生します。そのため、主キー設定も行いません。

設定の行セレクタに[0]を設定します。REST APIのレスポンスとして受信したJSON配列の最初の要素（インデックスとしては０）がデータで、次の要素（インデックスとしては１）はレスポンスのメタデータであるため、最初の要素だけをデータとして限定します。

データ・プロファイルに以上の変更を実施し、変更の適用をクリックします。


リクエストの発行を節約するためにRESTデータ・ソースの同期化を使い、ローカル・データベースに文化財一覧の情報をキャッシュします。

RESTデータ・ソースの同期化の管理を開きます。


同期先として新規表を選択し、表名にEBAJ_TOKYO_CULTURAL_PROPERTIESを指定します。RESTデータ・ソースの同期化が完了すると、文化財の情報を表EBAJ_TOKYO_CULTURAL_PROPERTIESから参照できるようになります。

保存をクリックします。


REST同期化の設定画面が開きます。

同期化表が存在しません。とレポートされています。SQLの表示をクリックし、表EBAJ_TOKYO_CULTURAL_PROPERTIESを作成するDDLを確認します。


以下の列名が長すぎて、途中で名前が切れてしまっています。また、列名と型名が繋がっている部分もあります。

   ,"設置地点_利用可能時間_終了 VARCHAR2(4000)
   ,"設置地点_利用可能時間_開催 VARCHAR2(4000)
   ,"設置地点_利用可能時間_開始 VARCHAR2(4000)

そのため、この画面からは表を作成することができません。


SQLワークショップのSQLコマンドを開き、エラーが発生しないように修正した以下のDDLを実行します。

create table "EBAJ_TOKYO_CULTURAL_PROPERTIES"(
"ID" VARCHAR2(4000)
,"備考" VARCHAR2(4000)
,"参照_参照先" VARCHAR2(4000)
,"名称_表記" CLOB
,"名称_カナ表記" VARCHAR2(4000)
,"画像" VARCHAR2(4000)
,"種別" CLOB
,"説明" CLOB
,"通称" VARCHAR2(4000)
,"EX_員数_単位" VARCHAR2(4000)
,"EX_員数_数値" VARCHAR2(4000)
,"管理者_表記" VARCHAR2(4000)
,"管理者_種別コード_種別" VARCHAR2(4000)
,"管理者_種別コード_識別値" VARCHAR2(4000)
,"権利管理_記述" VARCHAR2(4000)
,"設置地点_住所_方書" VARCHAR2(4000)
,"設置地点_住所_表記" VARCHAR2(4000)
,"設置地点_表記" VARCHAR2(4000)
,"設置地点_連絡先_内線番号" VARCHAR2(4000)
,"設置地点_連絡先_電話番号" VARCHAR2(4000)
,"設置地点_地理座標_経度" VARCHAR2(4000)
,"設置地点_地理座標_緯度" VARCHAR2(4000)
,"設置地点_利用可能時間_説明" VARCHAR2(4000)
,"設置地点_利用可能時間_終了時間" VARCHAR2(4000)
,"設置地点_利用可能時間_開催期日" VARCHAR2(4000)
,"設置地点_利用可能時間_開始時間" VARCHAR2(4000)
,"メタデータ_作成者_ID" VARCHAR2(4000)
,"メタデータ_作成者_表記" CLOB
,"EX_文化財指定日_標準型日付" VARCHAR2(4000)
,"APEX$SYNC_STEP_STATIC_ID" VARCHAR2(255)
,"APEX$ROW_SYNC_TIMESTAMP" TIMESTAMP WITH TIME ZONE
)
/
view raw ebaj_tokyo_culturalproperty.sql hosted with ❤ by GitHub


アプリケーション・ビルダーに戻り、RESTデータ・ソースの同期化の管理を開きます。同期化表EBAJ_TOKYO_CULTURAL_PROPERTIESが作成されているため、表のステータスとして「表"EBAJ_TOKYO_CULTURAL_PROPERTIES"は同期化の準備ができています」と表示されます。

初回の同期化では、同期タイプは追加または置換を選択します。データ・プロファイルに主キーが含まれていないため、マージはできません。次回以降は置換を選択します。

保存して実行をクリックすると、作成したRESTデータ・ソースを使って東京都の文化財一覧を読み出し、表EBAJ_TOKYO_CULTURAL_PROPERTIESに保存します。

RESTデータ・ソースの最後の同期化やログの情報より、REST同期化が成功したことを確認します。

ログから表EBAJ_TOKYO_CULTURAL_PROPERTIESに248行の文化財のデータが読み込まれたことが確認できます。RESTデータ・ソースのページネーションの設定ではlimitに100を設定しているため、3回のリクエストですべてのデータを読み取っています。


以上でRESTデータ・ソースの作成が完了し、データもローカル・データベースにキャッシュされました。

これから、アプリケーションにページを追加していきます。

最初に対話モード・レポートのページを追加します。

ページの作成をクリックします。


対話モード・レポートを選択します。


ページの名前は文化財一覧とします。データ・ソースとしてRESTソースを選択し、RESTデータ・ソースとしてTokyo Cultural Propertiesを選択します。

ページの作成をクリックします。


対話モード・レポートを含むページが作成されます。

ページ作成直後は、対話モード・レポートは同期化表を参照する設定になっていません。対話モード・レポートのリージョンを選択し、REST同期化のローカル表の使用をオンにします。


以上でページを実行します。

対話モード・レポートに東京都の文化財一覧が表示されます。東京都のオープンデータAPIを呼び出して取得されたデータがそのまま表示されているため、見にくい部分もあります。


オープンデータAPIから得られたデータを加工するビューEBAJ_TOKYO_CULTURAL_PROPS_Vを作成します。これから作成するファセット検索とマップのソースとして使用します。

create or replace view ebaj_tokyo_cultural_props_v as
select id, name, lon, lat, type, address, description from (
select
to_number("ID") as id
,json_value("名称_表記", '$[0]') name -- 日本語表記
,to_number("設置地点_地理座標_経度" default null on conversion error) lon
,to_number("設置地点_地理座標_緯度" default null on conversion error) lat
,"種別" type
,"設置地点_住所_表記" address
,json_value("説明", '$[0]') description
from ebaj_tokyo_cultural_properties
where id is not null
)
where lat is not null and lon is not null;
view raw ebaj_tokyo_cultural_props_v.sql hosted with ❤ by GitHub

作成したビューをソースとしたファセット検索のページを作成します。

ページの作成を実行し、ファセット検索を選択します。

ページの名前は文化財検索、データ・ソースの表/ビューの名前としてEBAJ_TOKYO_CULTURAL_PROPS_Vを選択します。

次へ進みます。


ファセットとして列TYPE（東京都の文化財一覧としては種別に当たるデータ）を選択したいのですが、これはJSON配列であるためタイプがclobとして認識されています。そのため、ファセットとして選択できません。

表示形式にレポートを選択し、ファセットとしては何も選択しません。ページの作成後に列TYPEをファセットとして追加します。

以上でページの作成をクリックします。


ページが作成されたら、レンダリング・ツリーのファセット上でコンテキスト・メニューを表示し、ファセットの作成を実行します。


作成したファセットの識別の名前はP3_TYPEとします。タイプはチェック・ボックス・グループです。

ラベルは本来の名前である種別、LOVのタイプは個別値を選択します。アクション・メニューのフィルタとチャートは不要なのでオフとします。ソースのデータベース列はTYPE、データ型はVARCHAR2です。複数の値のタイプにJSON配列を選択し、フィルタの結合にAND(論理積)を選択します。

ページを作成するウィザードでは列TYPEの型がClobと認識されていましたが、実際にはVARCHAR2です。また、複数の値のタイプにJSON配列を選択するにはVARCHAR2である必要があります。


検索結果のレポートに含まれる列LONおよびLATはそれぞれ経度と緯度の数値で、列TYPEはファセットとして使用しているため、レポートに表示する必要はありません。

列LON、LATおよびTYPEを選択し、タイプを非表示に変更します。


以上でファセット検索のページは完成です。ページの保存と実行を行い、動作を確認します。


最後に、地図上に文化財の位置を表示するページを作成します。

ページの作成を実行し、マップを選択します。

ページの名前は文化財の場所、データ・ソースの表/ビューの名前としてEBAJ_TOKYO_CULTURAL_PROPS_Vを選択します。

次へ進みます。


 マップ・スタイルとしてポイントを選択します。

マップ属性のジオメトリ列タイプとして２つの数値列を選択し、経度列はLON(Number)、緯度列はLAT(Number)とします。ツールチップ列にNAME(Varchar2)を選択します。

ファセット検索ページの作成はオンにします。

以上でページの作成をクリックします。



マップを含んだページが作成されます。

最初に先ほど作成した文化財検索のページと同様に、種別のファセットを作成します。

レンダリング・ツリーのファセット上でコンテキスト・メニューを表示し、ファセットの同期化を実行します。

ファセットの同期化ではなくファセットの作成を実行して作成したファセットは、なぜかマップ・リージョンと連動しませんでした。ファセットの同期化であればマップ・リージョンと連動するファセットが作成されるため、こちらの実行をお勧めします。


ビューEBAJ_TOKYO_CULTURAL_PROPS_Vに含まれるすべての列がファセットとして追加されます。ファセットP4_SEARCHとP4_TYPEを除き、その他のファセットを削除します。


 ファセットP4_TYPEは、文化財検索のファセットP3_TYPEと同じ設定にします。


マップの表示を少し調整します。レイヤー文化財の場所を選択します。

行のマッピングの主キー列としてIDを選択します。

ツールチップの拡張フォーマットをオンにし、HTML式に以下を記述します。ツールチップに文化財の名前を太字、その下に住所を表示します。

<b>&NAME.</b>
<br>
&ADDRESS.

 情報ウィンドウのタイトル列にNAME、本体列にDESCRIPTIONを指定します。

 ファセット検索が付いた文化財の場所を表示する地図のページが作成できました。

以上で、東京都が提供しているオープンデータAPIを活用したAPEXアプリケーションは完成です。

Oracle APEX 24.2のRESTデータ・ソースの新機能としてトークンによるページネーションがサポートされたため、ほぼノーコードでアプリケーションを作成することができました。

さて、Oracle Databaseに東京都が提供しているオープンデータが保存されています。

以前の記事「Oracle Databaseに接続するMCPサーバーを作成しClaudeから問い合わせる」で紹介しているClaudeのデスクトップ・アプリケーションに組み込んだMCPサーバーからオープンデータを保存しているスキーマに接続することにより、AIによる問い合わせも可能です。

 Claude 3.5 Sonnetに、作成した表EBAJ_TOKYO_CULTURAL_PROPERTIESを認識させてから、東京の名勝を一覧してもらいました。10件の名勝が一覧されました。


ファセット検索でも、東京都の文化財として登録されている名勝は10件でした。


今回の記事は以上になります。

今回作成したAPEXアプリケーションのエクスポートを以下に置きました。
https://github.com/ujnak/apexapps/blob/master/exports/rest-token-pagination-with-tokyo-opendata.zip

Oracle APEXのアプリケーション作成の参考になれば幸いです。

完
投稿者 時刻:
ラベル: