Protocol

Overview（概要）

本プロトコルでは、エンドポイントとプロセス制御、データ転送を担い、各レイヤの結節点としてトランザクションを成立させる機能を提供する。 また、本プロトコルのコアコンポーネント群であるトランザクションコンポーネントはODPを構成する各プロトコルの結節点であり、各レイヤ/パースペクティブ（Fundamental Protocols, Complementary Protocols）との通信を行う。

本プロトコルは、以下のトランザクションマネジメントを定義する。

• データ転送

  データ利用者からの要求に応じて、データストアのエンドポイントからデータを転送する機能。 データ構造（構造化/非構造化）および処理方式（同期/非同期）のデータ転送を実現するために、下記の4つのデータプレーンモジュールに分類されている。

  • Web API転送モジュール 同期処理の構造化データ（Web API等）の転送に特化したデータプレーンモジュール。

  • ストリーム転送モジュール 非同期処理の構造化データ（ストリームデータ）の転送に特化したデータプレーンモジュール。

  • ファイル/バルク転送モジュール 同期処理の非構造化データ（大規模なファイルやバルクデータ）の転送に特化したデータプレーンモジュール。

  • メディアストリーム転送モジュール 非同期処理の非構造化データ（ビデオや音声などのリアルタイムストリーミングデータ）の転送に特化したデータプレーンモジュール。

• 認証認可連携 クレデンシャル発行サービスおよびアイデンティティコンポーネント(L3)と連携し、リクエスト単位で認証認可制御を行う機能。

• ロギング ロギング(Common Functionalities)と連携し、来歴情報およびクリアリング・ペイメント(DCS)で必要となる情報を記録する機能。

Abstract Normative Specification（抽象仕様）

Concepts and Roles（概念および役割）

本プロトコルに必要な概念は以下である。

概念	説明
Data Provider（データ提供者）	データ利用者に対してデータストアに格納されたデータを送信する主体
Data Consumer（データ利用者）	データ提供者からデータを受信する主体

Scope（適用範囲）

本仕様はWeb API転送モジュールを最小実装例として定義する。

Normative Requirements（規定要件）

• shall: Open Dataspacesにおけるデータ転送は、データプレーンモジュールを介して行わなければならない。

  • Rationale: Open Dataspacesにおける信頼性、相互運用性を確保するため。

• should: 複数のデータ構造および転送方式に対応可能な拡張性を持つことを原則とする。

  • Rationale: Open Dataspacesにおけるデータ流通では、構造化/非構造化、同期/非同期など多様なユースケースが存在し、単一方式では相互運用性と実装容易性を確保できないため。

• may: データプレーンモジュールは、コントロールプレーンオーケストレータを用いずに直接利用されてもよい。

  • Rationale: 導入容易性や段階的展開を可能にし、実装・運用の選択肢を確保するため。

Non-functional / Cross-layer Requirements

• should: アイデンティティコンポーネント(L3)と連携し、リクエスト単位での認証および認可制御を行うことを原則とする。

  • Rationale: Open Dataspaces横断での一貫したアクセス制御を実現し、セキュリティと相互運用性を確保するため。

• should: データスペースコンプリメンタリサービス（DCS）が必要とする最低限のデータを記録できることを原則とする。

  • Rationale: DCSとの情報連携を可能にするため。

Message Types（メッセージ種類）

プロトコルが扱うメッセージの種類を以下に示します。

種類	送信元 ⇒ 送信先	説明
リクエスト	・データ利用者 ⇒ Web API転送モジュール ・Web API転送モジュール ⇒ Identity & Trust（L3） ・Web API転送モジュール ⇒ データ提供者	送信元がデータを操作するための要求や認証・認可を要求するために送信先に対して送信するメッセージ。リクエストに必要なヘッダ情報や要求パラメータを含む。
レスポンス	・Identity & Trust（L3） ⇒ Web API転送モジュール ・データ提供者 ⇒ Web API転送モジュール ・Web API転送モジュール ⇒ データ利用者	リクエストの送信先が送信元に対してリクエストに対する結果を送信するメッセージ。データの操作結果や認証・認可の検証結果、トークン、エラー情報などを含む。

Message Format（メッセージ形式）

本プロトコルで送受信されるメッセージは、以下の要素で構成されている。

要素	説明
Header	メッセージの先頭に存在し、通信制御情報に必要なメタデータを保持する。
Payload	メッセージの中央部に存在し、業務データ本体を保持する。

Protocol Flow（プロトコルフロー）

通信の流れ

各通信の詳細

No.	名称	送信元	送信先	フィールド	説明
①	利用者リクエスト	データ利用者	Web API転送モジュール	リクエストフィールドは転送先システムの仕様に依るため、該当するデータ提供者が公開する仕様を参照すること。	データ利用者がWeb API転送モジュールに対し、特定の操作や情報の要求を行うために送信されるメッセージ。認証情報や要求パラメータを含む。
②	認証・認可リクエスト	Web API転送モジュール	Identity & Trust（L3）	リクエストフィールドはIdentity & Trust（L3）の仕様に依るため、Identity & Trust（L3）を参照すること。	Web API転送モジュールがIdentity & Trust（L3）に対し、認証や認可の要求を行うために送信されるメッセージ。認証情報や要求パラメータを含む。
③	認証・認可レスポンス	Identity & Trust（L3）	Web API転送モジュール	レスポンスフィールドはIdentity & Trust（L3）の仕様に依るため、Identity & Trust（L3）を参照すること。	Identity & Trust（L3）がリクエストに応じてWeb API転送モジュールに送信する結果メッセージ。認証・認可結果、トークン、エラー情報などを含む。
④	転送リクエスト	Web API転送モジュール	データ提供者	リクエストフィールドは転送先システムの仕様に依るため、データ提供者が公開する仕様を参照すること。	Web API転送モジュールがデータ提供者に対し、特定の操作や情報の要求を行うために送信されるメッセージ。データ提供者側のAPIの認証情報(APIキー)や要求パラメータを含む。
⑤	提供者レスポンス	データ提供者	Web API転送モジュール	データ提供者から返却された正常系レスポンス、もしくはエラーレスポンスを受け取る。仕様については、データ提供者が公開する仕様を参照すること。	データ提供者がリクエストに応じてWeb API転送モジュールに送信する結果メッセージ。API実行結果、エラー情報などを含む。
⑥	利用者レスポンス	Web API転送モジュール	データ利用者	データ提供者から返却された正常系レスポンス、もしくはエラーレスポンスを原則としてそのまま透過する。仕様については、データ提供者が公開する仕様を参照すること。	Web API転送モジュールがリクエストに応じてデータ利用者に送信する結果メッセージ。API実行結果、エラー情報などを含む。

State Machine（状態遷移）

本プロトコルで扱う状態について記す。

States（状態）

状態	説明
Idle	リクエスト待機
Receiving	リクエスト受信
Authenticating	認証
Authorizing	認可
Processing	接続先システムへのルーティング・プロキシング
Rejecting	認証 or 認可失敗時のエラー生成
Responding	クライアントにレスポンス返却（成功／エラー）
Idle（戻り）	次のリクエスト待ち状態へ

State Machine Diagram（状態遷移図）

Error Handling（エラー処理）

本プロトコルで使用されるエラー処理について記す。

エラー種別	説明	発生タイミング	エラー発生時の対応
外部システムエラー（連携先応答透過）	連携先システムが返却した 4xx/5xx 等のエラー（外部サービス固有のエラー）	Web API転送モジュール ⇒ 連携先システム	連携先システムのレスポンスをそのまま返却する。
リクエスト不正	必須ヘッダー欠落、値不正などクライアント起因で成立しないリクエスト	クライアント（データ利用者） ⇒ Web API転送モジュール	リクエスト検証を行い、不正な場合はエラーレスポンスを生成して返却する。
API-Key 関連エラー	API-Key の検証に失敗	クライアント（データ利用者） ⇒ Web API転送モジュール	Web API転送モジュール内で API-Key を検証し、不正な場合はエラーレスポンスを生成して返却する。
API-Key 関連エラー（L3側）	Identity & Trust（L3） 側で API-Key 検証に失敗	Web API転送モジュール ⇒ Identity & Trust（L3）	Identity & Trust（L3） のレスポンスをそのまま返却する。
トークン関連エラー（認証）	アクセストークン無効／期限切れ等によりトークン検証に失敗	Web API転送モジュール ⇒ Identity & Trust（L3）	トークン検証結果に基づき、無効／期限切れの場合はエラーレスポンスをそのまま返却する。
権限不足エラー（認可）	認可判定によりアクセスが拒否された	Web API転送モジュール ⇒ Identity & Trust（L3）	認可判定結果に基づき、認可エラーとしてエラーレスポンスをそのまま返却する。
ルーティング／エンドポイント不正	ルート未登録、パス／メソッド不一致等により転送先が決定できない	Web API転送モジュール ⇒ 連携先システム	ルーティングの結果としてエラーとなる場合、エラーレスポンスを生成して返却する。
外部接続エラー（疎通不可／無効応答）	L3 または連携先に接続できない、無効な応答が返る等、外部通信が成立しない	Web API転送モジュール ⇒ Identity & Trust（L3） / 連携先システム	外部接続失敗／無効応答を検知した場合、エラーレスポンスを生成して返却する。
タイムアウト	L3 または連携先からの応答が規定時間内に得られない	Web API転送モジュール ⇒ Identity & Trust（L3） / 連携先システム	タイムアウトを検知した場合、エラーレスポンスを生成して返却する。
内部処理失敗	Web API転送モジュール内部の例外等により処理できない	Web API転送モジュール	例外を捕捉し、エラーレスポンスを生成して返却する。