202503 JDCAT Requirements

Author: KL-YAMADA

docs/spec/base/API_02_OAIPMH.md

@@ -278,16 +278,6 @@ https://\[host\]/oai?verb=「値」&「verbのパラメータ」=「値」&「 v
 
       - > noMetadataFormats：指定したアイテムで利用可能なメタデータフォーマットではない場合。
 
-
-  - > ListRecordの応答速度の改善
-
-        ListRecord の応答内容を事前にファイルへ出力することで、レスポンスを高速化する事が可能。
-        高速化機能を利用する場合、以下のコンフィグ値を設定する必要がある。
-        １．OAISERVER_FILE_BATCH_ENABLE : ファイルからレスポンスを作成する機能のON/OFFフラグ
-        ２．OAISERVER_FILE_BATCH_FORMATS : ファイル作成するフォーマット。
-        ３．CELERY_BEAT_SCHEDULE : ファイル作成をする実行間隔。
-        ４．OAISERVER_FILE_BATCH_STORAGE_LOACTION : ファイルを保存するストレージのロケーション。
-
 <!-- end list -->
 
   - > 関連モジュール
@@ -296,6 +286,198 @@ https://\[host\]/oai?verb=「値」&「verbのパラメータ」=「値」&「 v
 
   - > Invenio\_oaiserver
 
+### OAI-PMH ListRecordの応答速度の改善
+
+  - > 概要
+
+      - 機能概要
+
+        ListRecord の応答内容を事前のバッチ処理でファイルへ出力することで、レスポンスを高速化する事が可能。
+
+      ![FileCreate Image 1](media/media/API_02_OAIPMH_image_01.png)
+
+      - 前提条件
+
+        - ファイルは最大2世代とし、3世代分のファイルは持たない事とする。
+        - ハーベスト時にどのファイルを参照するかは、ファイル作成バッチがファイル書き込み終了時に設定する。
+        - ハーベスト実行状況をファイル作成バッチ側は把握できない。
+        - 作成したファイルの削除は2世代先のファイル作成直前にファイル作成バッチ処理にて実施する。
+          ※本来はファイル作成バッチ実行中に動作しているハーベスト処理で、最も遅く終了したハーベスト処理の直後にファイルを削除する事が望ましい。
+        - resumptionTokenの有効期限は、取得対象となるファイルが削除される時間を設定する。
+        - ファイル保存先はWEKO3のファイル管理と連動出来るように対応する。
+        - OAI-PMHの仕様として、ハーベスト時に返す情報は任意タイミングの断面でなければならない。
+
+
+      - 運用に関する制約
+
+        - ハーベスターの処理時間を24時間と仮定し、ファイル作成バッチ起動間隔はそれより長く設定すること。
+        - 複数インスタンスを運用する場合、ファイル保存先を同一にしない。
+
+
+      - バッチ処理の実施タイミング
+
+        本バッチ処理はceleryにより、コンフィグで指定された実行間隔で実施される。<br><br>
+        例 2月1日より1週間に1回（土曜日の0：00 ～ 実施）ファイル作成するケース
+
+      ![FileCreate Image 2](media/media/API_02_OAIPMH_image_02.png)
+
+
+      - バッチ処理の異常終了時の対応
+
+        本バッチは以下の場合にエラーで異常終了となる。
+        | # | エラーコード | エラー発生条件 |
+        |----|----|----|
+        | 1 | ERR_IOS-001 | WEKOのファイル管理のLocationが特定できない場合 |
+        | 2 | ERR_IOS-002 | ファイルの入出力エラーが発生した場合 |
+        | 3 | -           | 既存処理の部分に関するエラー処理については、既存処理に準拠します |
+
+        エラー発生時の対応について
+        - エラー発生時にはエラーログを出力する。 
+
+        異常終了時のリランについて
+
+        - 手動でリラン出来る方法を用意し、必要に応じてリランを実施する。
+        - 手動リランはFlaskのコマンドライン・インタフェースを利用する。コマンド実行される処理にて、Celeryタスクを即実行するように設定する。
+
+            ~~~
+            # flask oaipmh_file_create create_file
+            ~~~
+
+
+        １． : ファイルからレスポンスを作成する機能のON/OFFフラグ
+        ２． : ファイル作成するフォーマット。
+        ３． : ファイル作成をする実行間隔。
+        ４． : ファイルを保存するストレージのロケーション。
+
+
+  - > バッチ処理の入出力
+
+      - コンフィグ
+
+        本バッチにより利用されるinstance.cfg値
+        | # | 項目名 | エラー発生条件 |
+        |---|--------|----|
+        | 1 | OAISERVER_FILE_BATCH_ENABLE           | ファイルからレスポンスを作成する機能のON/OFFフラグ |
+        | 2 | OAISERVER_FILE_BATCH_FORMATS          | ファイル作成するフォーマット |
+        | 3 | CELERY_BEAT_SCHEDULE                  | ファイル作成をする実行間隔 |
+        | 4 | OAISERVER_FILE_BATCH_STORAGE_LOACTION | ファイルを保存するストレージのロケーション |
+
+        CELERY_BEAT_SCHEDULE に追記する内容
+
+        ~~~
+        #: Beat schedule
+        CELERY_BEAT_SCHEDULE = {
+            ・・・ 既存のタスク定義
+            # OAI-PMH Data create
+            'oaiserver': {
+                'task': 'invenio_oaiserver.tasks.create_data',
+                'schedule': crontab(hour=2, minute=30, day_of_week='sunday'),
+                'args': [],
+            },
+        }
+        ~~~
+
+      - データ構造
+
+        このバッチで保存されるファイル構造は下図の構造となる。
+
+      ![FileCreate Image 3](media/media/API_02_OAIPMH_image_03.png)
+
+      - data.json
+
+        本バッチにより作成された情報が定義されているjsonファイル。<br><br>
+        ファイルの内容例
+
+        ~~~
+        {
+            'current_data': ''20250215000001849',
+            'datas': [
+                {'id': '20250208000001256', 'create_time': '2025/02/08 00:00:01.256', 'expired_time': '2025/02/15 00:00:01.256'},
+                {'id': '20250215000001849', 'create_time': '2025/02/15 00:00:01.849', 'expired_time': '2025/02/22 00:00:01.849'}
+            ]
+        }
+        ~~~
+
+        項目定義
+        | # | 項目名 | 説明 |
+        |---|--------|----|
+        | 1 | current_data | オンラインで参照する最新のファイル情報群 |
+        | 2 | datas        | バッチ実行によって作成されたファイルの情報群<br>1回のバッチ実行で1つの情報が作成されれ、最大2つまでの情報しか作成されない |
+        | 3 | id           | バッチ実行によって作成されたファイル情報群の識別子<br>バッチ実行時間のタイムスタンプの値を利用する |
+        | 4 | create_time  | ファイル情報群が作成された時間<br>バッチ実行時間が設定される |
+        | 5 | expired_time | ファイル情報群の有効期間<br>create_time にコンフィグ値「OAISERVER_FILE_BATCH_FILE_EXPIRY」の値を加えた時刻が設定される |
+
+      - index.json
+
+        各アイテムごとの情報が定義されているjsonファイル。<br><br>
+        ファイルの内容例
+
+        ~~~
+        {
+            'items': [
+                {
+                    'identifier': 'oai:invenio:00000069',
+                    'datestamp': '2024-04-02T09:58:48Z',
+                    'setSpec': '1616224532673:169890635083',
+                    'file_name': 'oai_invenio_00000069.xml'
+                },
+                {
+                    'identifier': 'oai:invenio:00000070',
+                    'datestamp': '2024-04-02T09:59:24Z',
+                    'setSpec': '1616224532673:1698906350832',
+                    'file_name': 'oai_invenio_00000070.xml'
+                },
+                ・・・・
+        }
+        ~~~
+
+        項目定義
+        | # | 項目名 | 説明 |
+        |---|--------|----|
+        | 1 | items      | 各アイテムに関する情報<br>1アイテムにつき1つの情報が作成される |
+        | 2 | identifier | アイテムの識別子<br>アイテムのheader情報から取得する |
+        | 3 | datestamp  | アイテムの更新時間<br>アイテムのheader情報から取得する |
+        | 4 | setSpec    | アイテムのset（絞込み条件）<br>アイテムのheader情報から取得する |
+        | 5 | file_name  | このアイテムの内容が保存されているファイル名<br>Identifierの区切り文字を_に変更した名前とする |
+
+      - 各アイテムのXML
+
+        既存のOAI-PMH ListRecordsのレスポンス作成処理（invenio-oaiserver.response.listrecords）で取得したXMLをアイテムごとにファイルに保存する。
+
+
+  - > 処理内容
+
+      - バッチ処理フロー
+
+        ![FileCreate Image 4](media/media/API_02_OAIPMH_image_04.png)
+
+
+      - オンライン処理フロー
+
+        OAI-PMH の オンラインでListRecord を返す処理において、処理冒頭に以下の①②の内容を追加する。
+
+        ![FileCreate Image 5](media/media/API_02_OAIPMH_image_05.png)
+
+      - オンライン処理でのファイルの利用有無について
+
+        - ハーベスターからの要求が2回目以降の継続要求だった場合
+
+            初回のレスポンスがファイルから作成された場合、ファイルを利用する。
+            初回のレスポンスがオンラインで作成された場合、ファイルは利用しない。
+
+        - ハーベスターからの要求が初回要求だった場合
+
+            下表の条件に一致する場合、ファイルは利用しない。全ての条件に該当しない場合はファイルを利用する。
+
+            | # | 条件 |
+            |---|--------|
+            | 1 | コンフィグ「OAISERVER_FILE_BATCH_ENABLE」にFalseが設定されていて、ファイル利用が無効になっている場合 |
+            | 2 | 関数 2.3.1.2を利用してファイル管理のLocation情報が取得出来ない場合 |
+            | 3 | URLパラメータ「metadataPrefix」 で定義されているフォーマットが、コンフィグ「OAISERVER_FILE_BATCH_FORMATS」に定義されていない場合 |
+            | 4 | data.json が存在しない場合 |
+            | 5 | 入出力エラーが発生した場合 |
+
+
 <!-- end list -->
 
   - > 更新履歴