1. SQLワークショップ・ガイド
  2. RESTfulサービスを使用したデータ交換の有効化
  3. Oracle APEXのOracle RESTfulサービスについて

7.1 Oracle APEXのOracle RESTfulサービスについて

この項では、Oracle REST Data Services (ORDS)によって実装されるRESTfulサービスを紹介します。また、APEX内やその他のOracleツール内で使用される、RESTfulサービスを構成する様々なコンポーネントを示す用語を説明します。

Oracle REST Data Services (ORDS)によって実装されるRESTfulサービスを構成するには、リソース・モジュール、リソース・テンプレートおよびリソース・ハンドラを使用します。

  • RESTfulサービスの構成要件
    RESTfulサービスを外部システムに公開するための構成要件です。
  • RESTサービスとRESTfulサービス
    Representational State Transfer (REST)は、インターネット上でのコンピュータ・システム間の相互運用性を実現する方法です。RESTfulサービスを定義すると、基礎となるデータ・ストアに直接アクセスすることなく、データを問い合せて操作できます。
  • リソース・モジュール
    リソース・モジュールは、関連する一連のRESTfulサービスをグループ化するコンテナです。
  • リソース・テンプレート
    リソース・テンプレートは、呼び出すことができる個々のサービスを定義します。リソース・テンプレートは、リソース・モジュールに含まれています。
  • リソース・ハンドラ
    各リソース・ハンドラでは、1つのHTTP操作のみを実装します。リソース・ハンドラの実装が従来の作成、読取り、更新、削除(CRUD)操作にどのようにマップされるかを理解することが重要です。
  • RESTfulサービスの例
    リソース・モジュール、リソース・テンプレートおよびリソース・ハンドラを使用して、Oracle REST Data Services (ORDS)によって実装されるRESTfulサービスを構成します。
  • RESTfulサービスの用語
    Oracle APEX内やその他のOracleツール内で使用される、RESTfulサービスを構成する様々なコンポーネントを示す用語です。

親トピック: RESTfulサービスを使用したデータ交換の有効化

7.1.1 RESTfulサービスの構成要件

RESTfulサービスを外部システムに公開するための構成要件です。

RESTfulサービス・ユーティリティを使用可能にし機能させるには、次の要件を満たしている必要があります。

以前のリリースからの存在するRESTfulサービスのサポート

APEXリリース18.1より前は、APEXベースのRESTfulサービスのメタデータは、コアAPEXメタデータ・リポジトリで定義されていました。APEXベースのRESTサービスは、APEXリリース22.1でサポートされなくなりました。ORDSリリース21.4.2以降には、残りのAPEXベースのRESTサービスをORDSベースのサービスにアップグレードできる移行スクリプトが含まれています。詳細は、『Oracle REST Data Servicesリリース・ノート』のOracle APEX Restfulサービス・モジュールの移行に関する項を参照してください。

関連項目:

Oracle REST Data Servicesインストレーションおよび構成ガイドのOracle REST Data Servicesのダウンロード、構成およびインストールに関する項

親トピック: Oracle APEXのOracle RESTfulサービスについて

7.1.2 RESTサービスとRESTfulサービス

Representational State Transfer (REST)とは、インターネット経由でコンピュータ・システム間の相互運用性を実現する方法のことです。RESTfulサービスを定義すると、基礎となるデータ・ストアに直接アクセスすることなく、データを問い合せて操作できます。

RESTの原則に準拠するサービスは、RESTfulと呼ばれます。RESTの詳しい説明はこのマニュアルの対象外ですが、次に、RESTfulサービスの特性を示します。

  • RESTfulサービスは、リソースのセットとしてモデル化されます。これらのリソースは、URLによって識別され、httpまたはhttps Webプロトコルを介してアクセスされます。

  • リソースの操作には、小さな操作セットが使用されます(PUT、POST、GET、DELETEなど)。

  • RESTfulサービスはステートレスです。クライアントとサービス提供コンピュータ・システムとの接続は維持されず、リクエスト間でクライアント・コンテキストは格納されません。

  • RESTfulサービスへのリクエストは、常にレスポンスを引き起こします。このレスポンスは、XML、JSON、HTMLまたは他の定義済の形式になります。

  • レスポンスでは、操作に応じて、基礎となるデータに対する変更、エラー・メッセージ、および関連する他のリソースへのハイパーテキスト・リンクについて、詳細が示されます。

RESTリソースでは、標準操作にステートレス・プロトコルが使用されるため、RESTの実行中でもシステムに影響を与えずに管理および更新できる、再利用可能な、基礎となるコンポーネントを作成できます。

RESTfulサービスの消費では標準のHTTP操作を使用しますが、RESTfulサービスから返されるデータの処理は様々です。

親トピック: Oracle APEXのOracle RESTfulサービスについて

7.1.3 リソース・モジュール

リソース・モジュールは、関連する一連のRESTfulサービスをグループ化するコンテナです。

リソース・モジュールは、グループを一意に識別する方法を提供するだけでなく、モジュール内に定義されているサービス・セットにアクセスするためのURLで使用される一意のベース・パスも定義します。

ほとんどの場合、自分のアプリケーションで提供する必要があるRESTfulサービスごとにリソース・モジュールと子リソース・テンプレートを構成する必要があります。同じリソース・テンプレートに関連付けられているメソッドごとにリソース・ハンドラを定義する必要もあります。たとえば、データを返すメソッドとデータを格納するメソッドを指定するには、それぞれの操作に対してリソース・ハンドラを定義する必要があります。

例7-1 リソース・モジュール

従業員に関する情報にアクセスできるリソース・モジュールの名前がoracle.example.hrである場合、サービスのベース・パス値は/hr/です。

親トピック: Oracle APEXのOracle RESTfulサービスについて

7.1.4 リソース・テンプレート

リソース・テンプレートは、呼び出すことができる個々のサービスを定義します。リソース・テンプレートは、リソース・モジュールに含まれています。

各リソース・テンプレートでは、到達できるURIパターンを定義し、1つ以上のリソース・ハンドラを実装します。リソース・テンプレートは、リソース・ハンドラの各タイプ(GET、POST、PUT、DELETE)のいずれか1つのみ実装できますが、すべてを実装しないように構成することもできます。

親トピック: Oracle APEXのOracle RESTfulサービスについて

7.1.5 リソース・ハンドラ

各リソース・ハンドラでは、1つのHTTP操作のみを実装します。リソース・ハンドラの実装が従来の作成、読取り、更新、削除(CRUD)操作にどのようにマップされるかを理解することが重要です。

GET
リソースの表現を取得します(SQLのSELECT文に相当します)。
POST
新しいリソースを作成するか、コレクションにリソースを追加します(SQLのINSERT文に相当します)。
PUT
既存のリソースの値を更新します(SQLのUPDATE文に相当します)。
DELETE
既存のリソースを削除します(SQLのDELETE文に相当します)。

親トピック: Oracle APEXのOracle RESTfulサービスについて

7.1.6 RESTfulサービスの例

リソース・モジュール、リソース・テンプレートおよびリソース・ハンドラを使用して、Oracle REST Data Services (ORDS)によって実装されるRESTfulサービスを構成します。

例7-2 完成したリソース・テンプレート

http://server.com/ords/anyco/hr/employees/7978

説明:


http://server_URL/ords_alias/schema_alias/base_path/module_base_path/URI_template/:bind_variable

機能的に完成したリソース・テンプレートは、従業員IDを渡すことによって特定の従業員の詳細を取得するという機能を実装しています。このリソース・テンプレートのURIパターンは、employees/:idです。リソース・ハンドラは、GET操作および次のロジックを使用して実装されます。 

select empno, ename, dept from emp where empno = :id

RESTfulサービスをコールするときには、次のように、サーバー・パス、ベース・パスおよびURIテンプレートを使用し、従業員IDの静的値を指定することで、サービスにアクセスします。 

http://server.com/ords/anyco/hr/employees/7978
サーバー・パス
http://server.com/
ORDS別名
/ords/
スキーマ別名
/anyco/
ベース・パス
/hr/
URIテンプレート
employees/7978

HTTP GETを使用してこの特定のURLをコールすると、サービスは前述のSQL文の結果を返します。データがどのような形式で返されるかは、リソース・ハンドラの詳細な定義によって異なります。

ノート:

少なくとも1つのリソース・ハンドラを実装していない場合、リソース・テンプレートは機能的に不完全であるとみなされます。

関連項目:

親トピック: Oracle APEXのOracle RESTfulサービスについて

7.1.7 RESTfulサービスの用語

Oracle APEX内やその他のOracleツール内で使用される、RESTfulサービスを構成する様々なコンポーネントを示す用語です。

ベース・パス
RESTfulサービスへのアクセスに使用する大/小文字が区別されるベース・パス。モジュールのこのベース・パスは、サーバー・パスおよび基礎となるOracleスキーマのスキーマ別名に追加されます。ベース・パスは、スキーマ内で一意である必要があります。
HTTP操作
HyperText Transport Protocol (HTTP)には、リソースで実行できる標準のメソッド(GET、POST、PUTおよびDELETE)が定義されています。
リソース・ハンドラ
特定のリソース・テンプレートで特定のHTTP操作のサービスを行うために必要なロジックを提供します。
リソース・モジュール
関連するRESTfulサービスをグループ化するために使用されるコンテナ。
リソース・テンプレート
一部のUniversal Resource Identifier (URI)のセットにサービス・リクエストを行える個別のRESTfulサービス。リソース・テンプレートのURIパターンでは、URIのセットを定義します。
RESTfulサービス
RESTfulアーキテクチャ・スタイルの原則に準拠したHTTP Webサービス。
スキーマ別名
RESTfulサービスとともに使用するOracleスキーマを使用可能にする場合は、別名を指定する必要があります。大/小文字が区別されるスキーマ別名は、URLを形成するために使用され、ベース・パスおよびURIパターンより前のサーバー・パスに追加されます。
URIパターン

特定のリソースにアクセスするために使用される、大/小文字が区別されるパス。ルート・パターンまたはURIテンプレートのどちらでもかまいません。リソースのURIパターンは、サーバー・パスおよびリソース・モジュール・ベース・パスに追加されます。URIパターンは、スラッシュの後に追加したバインド変数にも含めることができます。これにより、値をURIの一部としてサービスに渡すことができます。バインド変数構文では、変数名に接頭辞としてコロン(:)が付けられます。

  • ルート・パターン - URIのパス部分をコンポーネント・パーツに分解することに重点をおくパターン。たとえば、/:object/:id?のパターンは/emp/101と一致し(101のidでempリソースにあるアイテムのリクエストと一致)、/emp/とも一致します(:idパラメータには?修飾子の注釈が付き、これはidパラメータがオプションであることを示すため、empリソースのリクエストとも一致します)。

  • URIテンプレート - 指定されたリソース・テンプレートで処理可能な特定のURIパターンを定義する簡単な構文。たとえば、employees/:idというパターンは、パスがemployees/で始まる任意のURI (employees/2560など)に一致します。

親トピック: Oracle APEXのOracle RESTfulサービスについて