22 ADF RESTful Webサービスの消費
この章の内容は次のとおりです。
ADF RESTフレームワークについて
ADF RESTフレームワークは、Fusion Webアプリケーション開発者がRESTアーキテクチャ・スタイルに基づくWeb APIを公開できるようにするADFモデル・フレームワークです。フレームワーク自体はWeb APIを構成しませんが、ADFビジネス・コンポーネントのビジネス・オブジェクトに基づくリソースやRESTful Webサービスの作成およびそれらとの対話をサポートしています。RESTfulである結果、REST APIが使用され、このAPIにより、クライアント・アプリケーション開発者は公開されたビジネス・オブジェクトと対話できます。
Fusion Webアプリケーションにおいては、RESTful Webサービスによって操作されるADF RESTリソースは、ADFビジネス・コンポーネント・モデル・プロジェクトのデータ・モデルで公開されるビュー・オブジェクト・インスタンスが基礎となっています。ADFモデル・プロジェクトで作業するADFビジネス・コンポーネント開発者は、基礎となるビュー・オブジェクトから公開する属性のセット、CRUD操作を使用可能にするアクションおよび結果として生成されたリソースを保存するビュー・リンク関係を決定できます。
ADFビジネス・コンポーネント開発者による設計時の選択内容は、RESTリソース定義XMLファイルで取得されます。Webサービス・クライアント開発者は、ADF RESTランタイム・フレームワークでサポートされているREST APIを介してこれらのリソース定義と対話できます。これにより、使用するサービス・クライアントはCRUD操作を起動して、RESTリソースおよびADFビジネス・オブジェクトと対話できます。データは、親子関係はそのままで、リソースの基礎となるビュー・オブジェクト・インスタンスによって形成されます。
ADF RESTリソースのユースケースと例
ADFモデル・プロジェクトで作業するADFビジネス・コンポーネント開発者は、ADF RESTリソースを公開し、Fusion Webアプリケーションに提供できます。
クライアントとサーバーによるリソース情報の交換をサポートするADF RESTフレームワークの固有のランタイム機能には、次のものがあります。
-
RESTリソースとの対話は、リソース、アクション実行、およびアクション実行の結果に対して、個別のJSONベース・メディア・タイプ構造によってサポートされています。
-
カスタム・ヘッダーを渡して、リクエストの処理に使用するREST APIフレームワークのバージョンを指定します。バージョン・ヘッダーにより、Webアプリケーションによって定義されたデフォルトのバージョン宣言をオーバーライドできます。REST APIフレームワーク・バージョンを指定することで、Webアプリケーション開発者は、オラクル社のフレームワーク拡張機能を選択できます。
-
GET、POST、PATCH、DELETEなどの標準HTTPリクエスト・メソッドを使用してRESTリクエストと対話します。
-
クライアントでの制限によりRESTリソースとの対話に標準HTTPメソッドを使用できない場合は、POSTリクエスト・メソッドを使用する
X-HTTP-Method-Overrideヘッダーを使用してHTTPメソッドを実行します。 -
POSTメソッドと、trueに設定した
Upsert-Modeヘッダーを組み合せて使用して、ペイロード・コンテンツをRESTリソースとマージします。このアクションによって、作成(レコードが存在しない場合)または更新(レコードが存在する場合)が実装されます。 -
RESTリソース・アイテム(特定の従業員など)やリソース・コレクション(すべての従業員のコレクションなど)の特定は、ADFビジネス・コンポーネント・モデル・プロジェクトで定義されているリソース名に基づくREST準拠のURIパス名によってサポートされます。
-
RESTリソースの記述(リソース・コレクション属性および使用可能なアクションなど)の取得は、特定のメディア・タイプとdescribeアクションでサポートされています。
-
ADF RESTフレームワーク・バージョン4以降が有効になっている場合、JSONペイロード形式のエラー・レスポンスと例外の詳細を取得します。フレームワーク・バージョン3以前では、エラー・レスポンスの形式は単純なメッセージ文字列です。
-
正規RESTリソースへのリンクは、更新可能エンティティのスーパーセットを持つリソースが定義されている場合にサポートされます。正規のリンクでは、基礎となるビュー・オブジェクトの代替リンクがサポートされます。
-
RESTリソースのフィルタ処理は、クライアントが特定のリソースにアクセスするために指定されたURIの問合せ文字列パラメータによりサポートされています。
-
圧縮および解凍を有効化するために、エンコーディング形式がRESTリソースでサポートされています。
-
RESTリソースにより公開されるBLOB属性とCLOB属性のコンテンツのストリーミングは、ADF RESTフレームワークでサポートされています。
-
RESTful Webサービス起動時のデータ整合性チェックの実行は、ADF RESTフレームワークでサポートされています。この機能では、データベースのバージョン履歴を使用して、クライアントがリソース自体の更新に応じてHTTPペイロードを管理できるようにします。
-
カスタム・ヘッダーを渡して、ADF RESTランタイムでリクエストの処理に使用するADF RESTフレームワーク・バージョン(バージョン2など)を指定します。ADF RESTフレームワーク・バージョンを使用すると、サービス・クライアントでは、Oracle JDeveloperの後続リリースで作成されたフレームワークの拡張機能を選択できます。
-
ユーザーに対するRESTリソースへのアクセスの認可は、ADFセキュリティ権限の付与によって有効化されます。
ランタイム機能の可用性に影響を与えるADF RESTフレームワークの固有のデザインタイム機能には、次のものがあります。
-
RESTリソースのバージョニングをサポートするために、RESTリソースをアプリケーション固有のリソース・バージョン名(または番号)で登録します。RESTリソース・バージョンは、アプリケーションの
adf-config.xmlファイルに指定されます。 -
特定のADF RESTフレームワーク・バージョンで提供される機能を使用してADF RESTランタイムでリクエストが実行されるように、個々のRESTリソースに対してデフォルトのADF RESTフレームワーク・バージョンを宣言します。特定のフレームワーク・バージョンを宣言すると、サービス・クライアントでは、Oracle JDeveloperの後続リリースで作成されたフレームワークの拡張機能を選択できます。デフォルトのADF RESTフレームワーク・バージョンは、アプリケーションの
adf-config.xmlファイルで宣言されます。JDeveloperでは、リリース12.2.1.2.0以降、バージョン1、2および3が存在します。12.2.1.4.0以降のリリースには、バージョン1、2、3、4、5、6および7が存在します。 -
URLリソース・パスのLOVアクセッサ・リンクを公開するために、リソースの基礎となるビュー・オブジェクトで値リスト(LOV)属性を定義します。
-
URLリソース・パスの行検索キー値を使用してリソースを検索するために、行検索を定義します。
-
URLリソース・パスの正規のリンクを公開するために、更新可能属性のスーパーセットを使用してアプリケーション・データ・モデルのビュー・インスタンスを定義します。
-
サーバーのリソースにアクセスするリクエストを行う場合にデータ整合性チェックを有効化するために、リソースの基礎となるエンティティ・オブジェクトで更新識別子属性を構成します。
-
リソースで公開されているリンクを使用するコンテンツ・ストリーミングをサポートするために、リソースの基礎となるビュー・オブジェクトのBLOB属性またはCLOB属性でカスタム・コンテンツ・タイプを構成します。
-
リソースへのアクセスを許可する前にユーザーを認証するために、セキュリティを構成します。
RESTful Webサービスの追加機能
RESTful Webサービスを使用する前に、関連するOracle ADF機能を理解しておくと役立つ場合があります。次に、関連するサポート機能へのリンクを示します。
-
ADFビジネス・コンポーネント、およびADFビジネス・コンポーネント・モデル・プロジェクトの作成の詳細は、「ADFビジネス・コンポーネントのスタート・ガイド」を参照してください。
-
ADFビジネス・コンポーネント・プロジェクトでのRESTful Webサービスの作成(LOVリンク、行検索、正規リソース、更新識別子、LOB属性のカスタム・コンテンツ・タイプ、セキュリティの有効化を含む)の詳細は、「アプリケーション・モジュールによるADF RESTful Webサービスの作成」を参照してください。
-
ADF RESTデータ・コントロールを使用したユーザー・インタフェースの設計の詳細は、「ADF RESTful WebサービスからのADF RESTデータ・コントロールの作成」を参照してください。
この章のリソース・サンプルについて
この章では、ADF RESTリソースとの対話およびADF RESTリソースの操作の一般的なユースケースについて説明します。すべてのサンプルは、Oracle HRスキーマのDEPARTMENTS表、EMPLOYEES表、JOBHISTORY表およびJOBS表に基づきます。図22-1は、ADFビジネス・コンポーネント・モデル・プロジェクトのこれらの表から生成されるビュー・オブジェクトを示しています。
図22-1 RESTサンプル・プロジェクト - ADFビジネス・コンポーネントのビュー・インスタンス
「図22-1 RESTサンプル・プロジェクト - ADFビジネス・コンポーネントのビュー・インスタンス」の説明
サンプル・プロジェクト・ファイルとデータ・モデル
サンプル・プロジェクト・リソースとリソース・バージョン識別子
図22-4に示すように、アプリケーションでは3つのバージョン・リリース名を定義します。各ADF RESTリソースは、これらのバージョン識別子のいずれかに割り当てられ、実行時にバージョン・リリース名でアクセスされます。たとえば、複数バージョンのEmployeesリソースが作成された場合、1つのバージョンではサポートされる操作セットが限定されており、もう一方のバージョンではより完全な操作セットが提供されます。
バージョン識別子の順序によりバージョンの順序が決まり、最新バージョンがリストの最上位に表示されることに注意してください。RESTサンプルでは、複数バージョンのEmployeesリソースが存在する場合、リリース名11.2が最新バージョンとして識別されます。
図22-3に示すように、アプリケーション・モジュールは、作成されたリソースを、それらに割り当てられたバージョン・リリース名で編成します。Employeesリソースは、最初にバージョン11.0で作成され、それ以降のバージョン11.1および11.2では新しい必須属性を追加して改訂されます。11.1で追加されたJobsリソースでは、LOV有効属性を含むEmployeesリソースに対する作成操作がサポートされています。
図22-6に示すように、DepartmentsリソースはDepartmentsViewビュー・オブジェクトが基礎となっており、子リソースEmployeesとJobHistoryが有効化されています。
子リソースEmployeesの名前はビュー・リンク定義のリンク先ビュー・インスタンス名から導出されることに注意してください。このサンプルでは、リンク先ビュー・インスタンスの名前がEmployeesView1からEmployeesに変更されています。これにより、デフォルト名EmployeesView1ではなく名前EmployeesをURLリソース・パスで使用して子リソースにアクセスできます。
図22-7に示すように、バージョン11.0のEmployeesルート・リソースは、EmployeesViewビュー・オブジェクトが基礎となっています。Employeesはルート・リソースとして作成されているため、子リソース・アクセッサを持ちません。
図22-8に示すように、EmployeesViewビュー・オブジェクトには、バージョン11.0のEmployeesルート・リソースで定義された複数のリソースがあります。HREmployeesリソースとBenefitsEmployeesリソースは、一意のビュー・オブジェクト形成定義が基礎となっており、これらの各リソースによりEmployeesリソースが正規リソースとして定義されます。
図22-8 RESTサンプル・プロジェクト - 正規Employeeリソース・バージョン11.0
「図22-8 RESTサンプル・プロジェクト - 正規Employeeリソース・バージョン11.0」の説明
図22-9に示すように、バージョン11.1のEmployeesルート・リソースでは、LOVが有効なEmployeesView属性JobIdのJobsリソースを使用したリソース・アイテムの作成を有効にするCreate操作などの機能が追加されています。実行時に、Jobsリソースは、行のコンテキストを必要とせずに、LOV有効属性JobIdの値を指定します。このバージョンでは、Employeesリソース・コレクションでのサブタイプの使用も有効化されています(JobId属性がサブタイプ・リソースの識別子として機能します)。実行時に、Employeesリソースは、ジョブIDがSA_REP (販売責任者)の従業員のコミッション属性を表示します。
図22-10に示すように、バージョン11.2のEmployeesルート・リソースは、EmpByEmailFinder行検索を追加して、従業員を電子メール・アドレスで検索できるようにしています。
図22-10 RESTサンプル・プロジェクト - Employeesリソース・バージョン11.2
「図22-10 RESTサンプル・プロジェクト - Employeesリソース・バージョン11.2」の説明
エンティティ・オブジェクトとビュー・オブジェクトのカスタマイズ
図22-11に示すように、EmployeesViewビュー・オブジェクトでは、LOV有効属性JobIdを定義します。LOVアクセッサ・リソースは、役職別のジョブ・リストを返し、対応するジョブIDの選択肢として示します。
JDeveloperでは、リソース定義で意図的にLOVアクセッサを公開しないことに注意してください。実行時に、ADF RESTランタイムは、リソース・アイテムのLOV有効属性の子としてLOVアクセッサ・リソースを自動的にネストします。
また、図22-11に、LOV有効属性が定義された新しいリソース・アイテムの作成のサポートを示します。EmployeesViewは、(v2:Jobsとして識別される)特定のバージョンのLOVアクセッサ・リソースを、LOV有効属性JobIdに関連付けます。実行時に、Employeesリソースの記述により、LOVリソースへのリンクが公開されます。リソース・アイテムを作成するPOSTリクエストにLOVリソースの支援が含まれることがあります。この場合、ビュー・オブジェクトLOV定義に依存することによりLOV有効属性に適切な値が返されます。
図22-12に示すように、EmployeesViewビュー・オブジェクトは、EmpByEmailFinder行検索を定義します。行検索では、従業員IDではなく従業員の電子メール・アドレス(Email属性)を使用して従業員を取得します。
行検索は、デフォルトですべてのバージョンのリソースで公開されることに注意してください。ただし、行検索キー属性が特定のリソース定義で定義されている場合は、その検索名をURLリソース・パスで使用する必要があります。行検索キーがリソース定義で明示的に定義されるまでは、URLリソース・パスでキー属性(このサンプルではEmployeeId)が必要となります。
図22-13に示すように、EmployeesViewビュー・オブジェクトでは、Picture属性でカスタム・コンテンツ・タイプimage/pngを定義します。このコンテンツ・タイプにより、属性のデフォルトのapplication/octet-streamコンテンツ・タイプ定義が置換され、イメージ・コンテンツのストリーミング時に期待される受入れタイプになります。
図22-13 RESTサンプル・プロジェクト - Employees BLOBコンテンツ・タイプ
「図22-13 RESTサンプル・プロジェクト - Employees BLOBコンテンツ・タイプ」の説明
図22-14に示すように、Departmentsエンティティ・オブジェクトでは、データ整合性チェックを有効化する更新識別子属性RelStateを定義します。属性のエディタでは、更新識別子を構成するために「更新識別子」フィールドと「履歴列」 - 「バージョン番号」フィールドが有効になっています。
ADFビジネス・コンポーネントのリソースの理解
-
Departmentsリソースは、DepartmentsVOビュー・インスタンス、およびEmployeesVOビュー・インスタンスへのアクセッサに基づきます。 -
Employeesリソースは、EmployeesVOビュー・インスタンスに基づきます。
実行時に、RESTful Webサービスのアクションが起動されると、サービスにより返されるペイロードには1つ以上のリソース・コレクションが含まれ、基礎となるビュー・オブジェクトにより問合せが行われる行セット、およびビュー・オブジェクト行の個々の属性で構成されます。リソース・コレクションでは、マスター/ディテール調整ビュー・インスタンスの関係が維持されます。
表22-1に示すように、リソース・コレクションは、ビュー・オブジェクト・インスタンスのRESTful Webサービス・ペイロード表現です。リソース・アイテムは、ペイロード・アイテム・オブジェクトの行および属性で、ビュー・オブジェクト行に対応します。
ノート:
ADFリソース・コレクションおよび含まれているアイテムの形式は、特定のADF RESTメディア・タイプによりJSONエンコード・エンティティとして定義されます。詳細は、「ADF RESTメディア・タイプ」を参照してください。
表22-1 JSONオブジェクトおよびADFビジネス・コンポーネント表現
| JSONオブジェクト | ADFビジネス・コンポーネント |
|---|---|
|
|
1つ以上の行で構成されるビュー・オブジェクト・インスタンス。 |
|
|
ビュー・オブジェクト行。特定の部門 |
ADF RESTカタログの記述の取得
RESTful Webサービス・リソース・カタログの記述により、サービス・エンドポイントに定義されたADF RESTful Webサービスで許可されている形状とアクションを識別できます。デフォルトでは、カタログ記述リクエストは、利用可能なすべてのパブリック・リソースを理解するために必要な情報(属性、コレクション、アイテム、注釈、アクション、リンクなど)を含むJSONオブジェクトを返します。
ADF RESTフレームワークでは、次のカタログ記述のユース・ケースをサポートしています。
-
すべてのリソース詳細(属性、コレクション、アイテム、注釈、アクション、リンクなど)が含まれる、完全なリソース・カタログの記述を取得します。
-
最小限のリソース・カタログの記述を取得します(この場合、記述の詳細はリソースのタイトルとリンクのみに限定され、子またはネストされたリソースは除外されます)。
-
リソースの可視性に基づいてリソース・カタログの記述(完全または最小限)を取得します。たとえば、パブリック・リソースのみ、プライベート(unlisted)リソースのみ、またはパブリックとプライベートの両方のリソースの記述を取得できます。
-
リソース・カタログの記述(完全または最小限)を取得しますが、親リソース内にネストされた子リソースは必要に応じて除外または追加し、また、すべてのリソース注釈も必要に応じて除外または追加します。
アプリケーションの特定バージョンの利用可能なすべてのパブリック・リソースのカタログ記述を取得するには、/describeをバージョンURLに追加します。
たとえば、次のURLは、識別されたアプリケーションのバージョン11.0として指定された利用可能なすべてのパブリック・リソースのリソース・カタログの記述を返します。
http://host:port/context-root/rest/11.0/describeノート:
GETリクエストを実行してリソース・カタログの記述を取得する場合、クライアントが特定バージョンのコンテキストにあることが必要です。サービス・エンドポイントのバージョン・リリース名の取得方法の詳細は、「リソース・バージョンの取得」を参照してください。
同じリクエスト内のすべてのリソースに関する情報の全セットを返す完全な記述を必要としない場合、最小限の記述をリクエストできます。たとえば、問合せパラメータmetadataModeがminimalに設定された次のURLは、すべての親リソースに関する記述を返しますが、取得される記述情報はリソースのタイトルとリンクのみに限定されます。
http://host:port/context-root/rest/11.0/describe?metadataMode=minimalさらに、最小限のカタログ記述のリクエストにURL問合せパラメータを追加して、記述の特定の詳細を取得することもできます。たとえば、追加された問合せパラメータを持つ次のURLは、親リソース内にネストされた使用可能なすべての子リソースを含む最小限のカタログ記述を取得します。
http://host:port/context-root/rest/11.0/describe?metadataMode=minimal&includeChildren=true次の表は、カタログ記述リクエストで使用されるURL問合せパラメータを示しています。これらの問合せパラメータを使用すると、記述で取得される詳細の量を制御できます。
表22-2 カタログ記述リクエストのオプションのURL問合せパラメータ
| URL問合せパラメータ | 値 | 説明 |
|---|---|---|
|
|
|
すべての詳細を含めるかどうかに関係なく、リソースの記述を取得する場合に使用します。デフォルトでは、すべてのリソースに関する情報の全セット(ネストされた子リソースを含む)を返す完全な記述を実行して、完全なカタログが取得されます。したがって、完全なカタログ記述には、リソースごとに次の情報セクションが含まれます。 タイトル、属性、コレクション、アイテム、注釈、子およびリンク 注釈はADF RESTリソース開発者がアプリケーション内に定義する必要があり、リソース上に存在しないことがあります。 URLパラメータ レスポンスにメタデータは不要だがセルフ・リンクのみを追加する場合は、記述リクエストに 問合せパラメータ |
|
|
(デフォルトは、完全または最小限のいずれのカタログを取得するかによって異なります) |
アプリケーション内の指定に従って、リソース注釈を除外または含める場合に使用します。デフォルトは、
metadataModeパラメータ値によって異なります。
注釈はADF RESTリソース開発者がアプリケーション内に定義する必要があり、リソース上に存在しないことがあります このパラメータは、 |
|
|
(デフォルトは、完全または最小限のいずれのカタログを取得するかによって異なります) |
親リソース内にネストされた使用可能なすべての子リソースを除外または含める場合に使用します。デフォルトは、
metadataModeパラメータ値によって異なります。
このパラメータは、 |
|
|
|
アプリケーション内の宣言に従って、特定の可視性のリソースの説明を取得する場合に使用します。このURLパラメータ値では、パブリック・リソースのみ(
「カタログ記述からリソースを非表示にする方法」の項を参照してください。 |
|
|
リソース・コレクション名のカンマ区切りリスト。 形式: 例: |
名前付きリソースの説明を取得して、リソースをカタログ・レベルでフィルタ処理する場合に使用します。 |
完全なカタログ記述の取得
ADF RESTランタイムでは、GETメソッドを使用した、アプリケーション・エンドポイントの使用可能なすべてのリソースの記述をサポートし、すべてのリソース(親リソース内にネストされたすべての子リソースを含む)に関する情報の全セットを返す完全な記述を実行します。
リソース・カタログに完全な情報を含めて、使用可能なすべてのリソースを調べるには:
-
リソース・カタログの記述を実行し、その記述内でリソースの名前を検索します。
children属性により、ネストされたリソースを識別します。 -
これらのリソース・オブジェクトを調査して、各リソースの形状を理解します。
-
attributesでは、使用可能なリソース・コレクション属性のリストを指定します。 -
collectionでは、コレクションの形状を指定し、finders(行検索の場合)、links、および使用可能なactions(メディア・タイプを含む)を指定します。 -
itemでは、コレクションのインスタンスの形状を指定し、item自体ではlinksと使用可能なactionsを指定します。 -
childrenでは、ネストされたリソースを指定します(children自体にはattributesオブジェクト、collectionオブジェクトおよびitemオブジェクトが含まれます)。
-
たとえば、Departmentsリソースと子Employeesリソースを含むサービスの記述は、次のオブジェクトを返します。
{
"Resources" : {
"Employees" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"collection" : {
...
} ],
"finders" : [ {
} ]
"links" : [ {
} ]
"actions" : [ {
} ]
},
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"children" : {
"Departments"
...
} ],
...
"links" : [ {
} ]
}
}
次のサンプルは、リソース・カタログ内のバージョン11.0のすべてのリソースを記述します。URLバージョン・パラメータ11.0は、アプリケーション固有のバージョン識別子に置き換えられる場合があることに注意してください。リソース・バージョンの指定の詳細は、「リソース・バージョンの取得」を参照してください。
ノート:
include問合せパラメータを使用して、特定の可視性のリソースが含まれる完全なカタログ記述を取得できます。たとえば、パブリックとプライベートの両方のリソースを表示するには、http://server/demo/rest/v1/describe?include=allを使用できます。all、unlistedまたはpublicをinclude問合せパラメータの値として使用できます。
リクエスト
-
URL
http://server/demo/rest/11.0/describe -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.description+json -
ペイロード
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { "rangeSize" : 24, "finders" : [ { "name" : "EmpByEmailFinder", "title" : "EmployeesByEmailVC", "attributes" : [ { "name" : "Email", "type" : "string", "updatable" : true, "required" : "Optional", "queryable" : false } ] }, { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "lov", "href" : "http://server/demo/rest/11.0/Employees/{id}/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" }, { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Employees/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "children" : { "JobsLOV" : { "discrColumnType" : false, "attributes" : [ { "name" : "JobId", "type" : "string", "updatable" : false, "mandatory" : true, "queryable" : true, "precision" : 10 }, { "name" : "JobTitle", "type" : "string", "updatable" : false, "mandatory" : true, "queryable" : true, "precision" : 35 }, { "name" : "MinSalary", "type" : "integer", "updatable" : false, "mandatory" : false, "queryable" : true, "precision" : 6 }, { "name" : "MaxSalary", "type" : "integer", "updatable" : false, "mandatory" : false, "queryable" : true, "precision" : 6 } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "JobId", "type" : "string", "updatable" : false, "mandatory" : true, "queryable" : true, "precision" : 10 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Employees/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/describe", "name" : "canonical", "kind" : "describe" } ] }, "Departments" : { "discrColumnType" : false, "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 }, { "name" : "DepartmentName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 30 }, { "name" : "RelState", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true } ], "collection" : { "rangeSize" : 24, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "testImpl", "parameters" : [ { "name" : "testid", "type" : "string", "mandatory" : false } ], "resultType" : "string", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "children" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "EmpByEmailFinder", "title" : "EmployeesByEmailVC", "attributes" : [ { "name" : "Email", "type" : "string", "updatable" : true, "required" : "Optional", "queryable" : false } ] }, { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } } }
最小限のカタログ記述の取得
ADF RESTランタイムでは、GETメソッドを使用して、取得するアプリケーション・エンドポイントの情報量を削減しながら、使用可能なすべてのリソースの記述をサポートしています。縮小版または最小限のカタログ記述は、リソースの情報をリソースのタイトル、リンク、および使用可能な注釈に限定することによって、記述の可読性を向上させるのに役立ちます。
リソース・カタログで、使用可能なすべてのリソースの最小限の記述を調べるには:
-
最小限のリソース・カタログの記述を実行し、その記述内でリソースの名前を検索します。ネストされたリソースまたは子リソースは、デフォルトでは表示されません。
-
これらのリソース・オブジェクトの
linksを調べます。
たとえば、Departmentsリソースを含むサービスの最小限の記述は、次のオブジェクトを返します。
{
"Resources" : {
"Departments" : {
Departments,
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.1/Departments/describe",
"name" : "self",
"kind" : "describe"
} ]
},
...
}
}デフォルトでは、子リソースは最小限の記述には含まれません。親リソース内にネストされた使用可能なすべての子リソースを含む最小限のカタログ記述を取得するには、includeChildren問合せパラメータを使用します。たとえば、最小限の記述で子リソースを表示するには、次のようなリクエストを使用できます。
http://server/demo/rest/11.1/describe?metadataMode=minimal&includeChildren=true子リソースEmployeesを持つDepartmentsリソースを含むサービスの最小限の記述は、includeChildren問合せパラメータがtrueに設定されている場合、次のオブジェクトを返します。
{
"Resources" : {
"Departments" : {
Departments,
"children" : {
"Employees" : {
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.1/Departments/{id}/child/Employees/describe",
"name" : "self",
"kind" : "describe"
} ]
}
},
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.1/Departments/describe",
"name" : "self",
"kind" : "describe"
} ]
},
...
}
}次のサンプルは、EmployeesリソースがDepartmentsリソース内にネストされ、JobsLOVリソースがEmployeeリソースにネストされている子リソースを含む、最小限のリソース・カタログ記述を取得します。
リクエスト
-
URL
http://server/demo/rest/11.1/describe?metadataMode=minimal&includeChildren=true -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.description+json -
ペイロード
{ "Resources" : { "Employees" : { "children" : { "JobsLOV" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/{id}/child/JobsLOV/describe", "name" : "self", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/describe", "name" : "self", "kind" : "describe" } ] } }, "Departments" : { "children" : { "Employees" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/describe", "name" : "self", "kind" : "describe" } ] } } }
リソースの可視性の宣言に基づいたカタログ記述の取得
ADF RESTランタイムでは、GETメソッドを使用し、アプリケーション・エンドポイントの特定の可視性のリソースを追加するURLパラメータを指定して、アプリケーションではプライベートと識別されるリソースを必要に応じて含めながら、使用可能なすべてのリソースの記述をサポートしています。
デフォルトでは、パブリックなリソースのみが記述に表示されます。このURLパラメータでは、パブリック・リソースのみ、プライベート(unlisted)リソースのみ、または両方のタイプを指定できます。プライベート・リソースを表示するには、記述リクエストに?include=all (パブリックとプライベートの両方のリソース)または?include=unlisted (プライベート・リソースのみ)を追加する必要があります。
アプリケーション開発者がリソース定義で可視性を宣言する方法の詳細は、「カタログ記述からリソースを非表示にする方法」を参照してください。
リソース・カタログにプライベート・リソースを表示するには:
-
URLパラメータ
?include=allまたは?include=unlistedを指定してリソース・カタログの記述を実行し、その記述内でプライベート・リソースの名前を検索します。 -
これらのリソース・オブジェクトを調査して、各リソースの形状を理解します。
次のサンプルは、Locationsリソースがunlistedとして構成されている、パブリックとプライベートの両方のリソースを含む最小限のリソース・カタログの記述を取得します。
リクエスト
-
URL
http://server/demo/rest/11.1/describe?metadataMode=minimal&include=all -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.description+json -
ペイロード
{ "Resources" : { "Employees" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/describe", "name" : "self", "kind" : "describe" } ] }, "Departments" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/describe", "name" : "self", "kind" : "describe" } ] }, "Locations" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Locations/describe", "name" : "self", "kind" : "describe" } ] } } }
ADF RESTリソースの記述の取得
RESTful Webサービスの記述により、ADF RESTful Webサービスで許可されている形状とアクションを識別できます。RESTリソース定義で定義されている属性、アクションおよびリンクを含むJSONオブジェクトを返します。
ADF RESTフレームワークでは、サービス・エンドポイントに関して次の記述のユースケースをサポートしています。
-
単一のリソース・コレクションを記述します。
-
単一のリソース・アイテムを記述します。
-
親子関係でのネストされたリソースを記述します。
-
2つ以上の名前付きリソース・コレクションを記述します。
-
使用可能なすべてのリソース(リソース・カタログ)を記述します。詳細は、「ADF RESTカタログの記述の取得」を参照してください。
記述を取得するには、/describeをリソースURLに追加して、HTTP GETを起動します。
ノート:
GETリクエストを実行してリソースの記述を取得する場合、クライアントが特定バージョンのコンテキストにあることも必要となります。サービス・エンドポイントのバージョン・リリース名の取得方法の詳細は、「リソース・バージョンの取得」を参照してください。
たとえば、次のURLは、識別されたアプリケーションのバージョン11.0のEmployeesリソースに関する記述を返します。
http://host:port/context-root/rest/11.0/Employees/describe
アプリケーションの特定バージョンのすべてのリソースの記述を取得するには、/describeをバージョンURLに追加します。
たとえば、次のURLは、識別されたアプリケーションのバージョン11.0のすべてのリソースに関する記述を返します。
http://host:port/context-root/rest/11.0/describe
リソース・コレクションの記述
ADF RESTランタイムでは、GETメソッドを使用したリソース・コレクションの記述をサポートしています。
リソース・コレクションを調査するには:
-
リソース・コレクションの記述を実行し、その記述内でリソースの名前を検索します。
-
これらのリソース・オブジェクトを調査して、各リソースの形状を理解します。
-
attributesでは、使用可能なリソース・コレクション属性のリストを指定します。 -
collectionでは、コレクションの形状を指定し、finder(行検索の場合)、links、および使用可能なactions(メディア・タイプを含む)を指定します。 -
itemでは、コレクションのインスタンスの形状を指定し、item自体ではlinksと使用可能なactionsを指定します。 -
childrenでは、ネストされたリソースを指定します(children自体にはattributesオブジェクト、collectionオブジェクトおよびitemオブジェクトが含まれます)。
-
たとえば、Departmentsリソースの記述は、次のオブジェクトを返します。
{
"Resources" : {
"Departments" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"collection" : {
...
} ],
"finders" : [ {
} ]
"links" : [ {
} ]
"actions" : [ {
} ]
},
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"children" : {
"Employees"
...
} ],
...
"links" : [ {
} ]
}
}
次のサンプルは、バージョン11.0のDepartmentsリソースを記述します。
リクエスト
-
URL
http://server/demo/rest/11.0/Departments/describe -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.description+json -
ペイロード
{ "Resources" : { "Departments" : { "discrColumnType" : false, "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 }, { "name" : "DepartmentName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 30 }, { "name" : "RelState", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true } ], "collection" : { "rangeSize" : 25, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "testImpl", "parameters" : [ { "name" : "testid", "type" : "string", "mandatory" : false } ], "resultType" : "string", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "children" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "EmpByEmailFinder", "title" : "EmployeesByEmailVC", "attributes" : [ { "name" : "Email", "type" : "string", "updatable" : true, "required" : "Optional", "queryable" : false } ] }, { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } } }
リソース・アイテムの記述
ADF RESTランタイムでは、GETメソッドを使用したリソース・アイテムの記述をサポートしています。
リソース・アイテムの記述は、通常、コレクションの記述と同じ情報を提供することに注意してください。ただし、多相コレクションの場合、リソース・アイテムの記述には、リソース・コレクションの記述よりも多くの情報が含まれます。たとえば、(車両リソースに自動車アイテムと航空機アイテムが含まれる)多相コレクション車両について考えてみます。車両の記述は、すべての車両の一般的な形状を返し、自動車リソース・アイテムの記述はそのオブジェクト固有の形状を返します。
リソース・アイテムを調査するには:
-
リソース・アイテムの記述を実行し、その記述内でリソースの名前を検索します。
children属性により、ネストされたリソースを識別します。 -
リソース・アイテムの記述を調査して、その形状を理解します。
-
attributesでは、使用可能なリソース・コレクション属性のリストを指定します。 -
itemでは、アイテム(定義された子コレクションなど)へのlinks、および使用可能なactionsを指定します。 -
linksでは、記述のリンクを指定します。
-
たとえば、Departmentsリソース・アイテムの記述は、次のオブジェクトを返します。
{
"Resources" : {
"Departments" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"links" : [ {
} ]
}
}
次のサンプルは、バージョン11.0のDepartmentsリソース・コレクションのインスタンスを記述します。
ノート: リクエストした記述上のリソース・アイテムのすべての子が再帰的に含まれるようにするには、記述URLに問合せパラメータ?includeChildren=trueを指定します。
リクエスト
-
URL
http://server/demo/rest/11.0/Departments/10/describe -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.description+json -
ペイロード
{ "Resources" : { "Departments" : { "discrColumnType" : false, "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 }, { "name" : "DepartmentName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 30 }, { "name" : "RelState", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true } ], "item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10/describe", "name" : "canonical", "kind" : "describe" } ] } } }
ネストされたリソースの記述
ADF RESTランタイムでは、GETメソッドを使用した、ADF RESTのネストされたリソースの記述をサポートしています。
リソース・カタログ内のネストされたリソースを調査するには:
-
ネストされたリソースの記述を実行し、その記述内でリソースの名前を検索します。
children属性により、ネストされたリソースを識別します。 -
これらのリソース・オブジェクトを調査して、各リソースの形状を理解します。
-
attributesでは、使用可能なリソース・コレクション属性のリストを指定します。 -
collectionでは、コレクションの形状を指定し、finder(行検索の場合)、links、および使用可能なactions(メディア・タイプを含む)を指定します。 -
itemでは、コレクションのインスタンスの形状を指定し、item自体ではlinksと使用可能なactionsを指定します。 -
childrenでは、ネストされたリソースを指定します(children自体にはattributesオブジェクト、collectionオブジェクトおよびitemオブジェクトが含まれます)。
-
たとえば、ネストされたリソースDepartmentsとリソースEmployeesの記述は、次のオブジェクトを返します。
{
"Resources" : {
"Employees" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"collection" : {
...
} ],
"finders" : [ {
} ]
"links" : [ {
} ]
"actions" : [ {
} ]
},
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"children" : {
"Departments"
...
} ],
...
"links" : [ {
} ]
}
}
次のサンプル(URL1)は、Departmentのコンテキストで見つけることができるバージョン11.0のEmployeesリソースを記述します。2番目のサンプル(URL2)は、ネストされた同じリソースEmployeesのアイテムを記述します(ネストされたリソース・アイテムは従業員のIDにより識別されます)。
ノート: リクエストした記述上のリソース・アイテムのすべての子が再帰的に含まれるようにするには、記述URLに問合せパラメータ?includeChildren=trueを指定します。
リクエスト
-
URL 1
http://server/demo/rest/11.0/Departments/10/child/Employees/describe -
URL 2
http://server/demo/rest/11.0/Departments/10/child/Employees/200/describe -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.description+json -
ペイロード1
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { "rangeSize" : 25, "finders" : [ { "name" : "EmpByEmailFinder", "title" : "EmployeesByEmailVC", "attributes" : [ { "name" : "Email", "type" : "string", "updatable" : true, "required" : "Optional", "queryable" : false } ] }, { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } } } -
ペイロード2
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200/describe", "name" : "canonical", "kind" : "describe" } ] } } }
複数のリソース・コレクションの記述
REST APIでは、2つ以上の名前付きリソース・コレクションの記述をサポートしています。
リソース・コレクションを調査するには:
-
resources問合せパラメータを使用して、名前付きリソースが含まれるリソース・コレクションの記述を実行します。 -
記述内でリソースの名前を検索します。
-
これらのリソース・オブジェクトを調査して、各リソースの形状を理解します。
-
attributesでは、使用可能なリソース・コレクション属性のリストを指定します。 -
collectionでは、コレクションの形状を指定し、finders(行検索の場合)、links、および使用可能なactions(メディア・タイプを含む)を指定します。 -
itemでは、コレクションのインスタンスの形状を指定し、item自体ではlinksと使用可能なactionsを指定します。 -
childrenでは、ネストされたリソースを指定します(children自体にはattributesオブジェクト、collectionオブジェクトおよびitemオブジェクトが含まれます)。
-
たとえば、Departmentsリソースの記述は、次のオブジェクトを返します。
{
"Resources" : {
"Departments" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"collection" : {
...
} ],
"finders" : [ {
} ]
"links" : [ {
} ]
"actions" : [ {
} ]
},
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"children" : {
"Employees"
...
} ],
...
"links" : [ {
} ]
}
}
次のサンプルは、resources問合せパラメータを使用して、リクエストで指定されたバージョン11.0のDepartmentsリソースとEmployeesリソースを記述します。
リクエスト
-
URL
http://server/demo/rest/11.0/Departments/describe?resources=Departments,Employees -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.description+json -
ペイロード
{ "Resources" : { "Departments" : { "discrColumnType" : false, "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 }, { "name" : "DepartmentName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 30 }, { "name" : "RelState", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true } ], "collection" : { "rangeSize" : 25, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "testImpl", "parameters" : [ { "name" : "testid", "type" : "string", "mandatory" : false } ], "resultType" : "string", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "children" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "EmpByEmailFinder", "title" : "EmployeesByEmailVC", "attributes" : [ { "name" : "Email", "type" : "string", "updatable" : true, "required" : "Optional", "queryable" : false } ] }, { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "EmpByEmailFinder", "title" : "EmployeesByEmailVC", "attributes" : [ { "name" : "Email", "type" : "string", "updatable" : true, "required" : "Optional", "queryable" : false } ] }, { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } } }
ネストされたリソース・コレクションの部分的な記述
ADF RESTランタイムでは、GETメソッドおよびパラメータpartialDescriptionを使用して、ネストされたリソースの部分的な記述を取得し、階層の深度を次の子リソースのみに制限できます。
記述リクエストでpartialDescriptionパラメータを使用することで、ネストされた親子階層内にネストされたオブジェクトが1つという深度の、ネストされたコレクションのみがレスポンス・ペイロードに含まれるようにできます。ネストされた親リソースの子の記述は拡張されておらず、階層内の次のリソースの部分的な記述を取得するリンクのみが提供されます。
ネストされたリソース・コレクションとその子リソース(ある場合)の部分的な記述を調べるには:
-
partialDescriptionパラメータを指定してネストされたリソース・コレクションの記述を実行し、記述内のネストされたリソースの名前を特定します。 -
これらのリソース・オブジェクトを調べて、リソースの形状を把握します。特に
children要素を調べて、リソース階層内の次の子リソースの部分的な記述のリンクを特定します(ネストされたリソースが1つの深度)。-
attributesでは、使用可能なリソース・コレクション属性のリストを指定します。 -
collectionでは、コレクションの形状を指定し、finder(行検索の場合)、links、および使用可能なactions(メディア・タイプを含む)を指定します。 -
itemでは、コレクションのインスタンスの形状を指定し、item自体ではlinksと使用可能なactionsを指定します。 -
childrenは、オブジェクトが1つの深度のネストされたリソースを特定し、?partialDescriptionパラメータとともに、部分的な記述を取得するための記述のリンクを提供します(この子リソースの記述にはattributes、collectionおよびitemオブジェクトは含まれません)。
-
たとえば、ネストされたEmployeesリソースの部分的な記述は、次のオブジェクトを返します。このサンプルでは、Employeesコレクションに子コレクションBonusが含まれています。部分的な記述リクエストでは、ネストされているリソースおよびネストされているリソースの1つの子(この場合はBonus)に深度が制限されます。
{
"Resources" : {
"Employees" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"collection" : {
...
} ],
"finders" : [ {
} ]
"links" : [ {
} ]
"actions" : [ {
} ]
},
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"children" : {
"Bonus" : {
"$ref" : "http://server/demo/rest/12.0/Departments/describe?partialDescription=Employees.Bonus"
} ],
...
"links" : [ {
} ]
}
}
次のサンプルでは、ネストされたEmployeesリソースのバージョン12.0の部分的な記述を取得し、リソース階層内の次の子Bonusの部分的な記述を取得するためのリンクを提供しています。
リクエスト
-
URL
http://server/demo/rest/12.0/Departments/describe?partialDescription=Employees -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.description+json -
ペイロード
{ "Resources" : { "Employees" : { "discrColumnType" : false, "ServiceConfiguration" : { "Cache-Control" : "max-age=30" }, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 25 }, { "name" : "PhoneNumber", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 20 }, { "name" : "HireDate", "type" : "datetime", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always" }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 10 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 8, "scale" : 2 }, { "name" : "CommissionPct", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 2, "scale" : 2 }, { "name" : "ManagerId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 6 }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 4 } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourcecollection+json", "application/json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "upsert", "method" : "POST", "header" : "Upsert-Mode=true", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/12.0/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "children" : { "Bonus" : { "$ref" : "http://server/demo/rest/12.0/Departments/describe?partialDescription=Employees.Bonus" } } "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } } }
指定したフィールドを使用したリソース・コレクションの記述
ADF RESTランタイムでは、GETメソッドおよびパラメータfieldsを使用したリソース・コレクションの制限付き記述の取得をサポートしています。記述リクエストでfieldsパラメータを使用することで、レスポンス・ペイロードにコレクションの特定の属性のみが含まれるようになります。
リソース・コレクションを調査するには:
-
リソース・コレクションの記述を実行し、その記述内でリソースの名前を検索します。
-
これらのリソース・オブジェクトを調査して、各リソースの形状を理解します。
-
attributesでは、使用可能なリソース・コレクション属性のリストを指定します。 -
collectionでは、コレクションの形状を指定し、finder(行検索の場合)、links、および使用可能なactions(メディア・タイプを含む)を指定します。 -
itemでは、コレクションのインスタンスの形状を指定し、item自体ではlinksと使用可能なactionsを指定します。 -
childrenでは、ネストされたリソースを指定します(children自体にはattributesオブジェクト、collectionオブジェクトおよびitemオブジェクトが含まれます)。
-
たとえば、Departmentsリソースの記述は、次のオブジェクトを返します。
{
"Resources" : {
"Departments" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"collection" : {
...
} ],
"finders" : [ {
} ]
"links" : [ {
} ]
"actions" : [ {
} ]
},
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"children" : {
"Employees"
...
} ],
...
"links" : [ {
} ]
}
}
次のサンプルでは、DepartmentsリソースおよびネストされたEmployeesリソースのバージョン12.0の、制限付き記述の取得を示しています。最初のリクエスト(URL 1)では、fieldsパラメータを使用して、Departmentsリソース・コレクションの1つの属性を取得します。2番目のリクエスト(URL 2)では、fieldsパラメータを使用し、ワイルドカード文字(*)を指定してDepartmentsリソース・コレクションのすべての属性を取得します。また、ネストされたEmployees子リソース・コレクションの1つのEmployeeId属性も取得します。
リクエスト
-
URL 1
http://server/demo/rest/12.0/Departments/describe?fields=DepartmentNameURL 2
http://server/demo/rest/12.0/Departments/describe?fields=*;Employees:EmployeeId -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.description+json -
ペイロード1
{ "Resources" : { "Departments" : { "discrColumnType" : false, "attributes" : [ { "name" : "DepartmentName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 30 } ], "collection" : { "rangeSize" : 25, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "upsert", "method" : "POST", "header" : "Upsert-Mode=true", "requestType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { } ] }, "item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "children" : { "Employees" : { "$ref" : "http://server/demo/rest/12.0/Departments/describe?partialDescription=Employees" } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } } }ペイロード2
{ "Resources" : { "Departments" : { "discrColumnType" : false, "ServiceConfiguration" : { "Cache-Control" : "max-age=30" }, "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 4 }, { "name" : "DepartmentName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 30 }, { "name" : "ManagerId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 6 }, { "name" : "LocationId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 4 } ], "collection" : { "rangeSize" : 25, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 4 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourcecollection+json", "application/json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "upsert", "method" : "POST", "header" : "Upsert-Mode=true", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] } ] }, "item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "children" : { "Employees" : { "discrColumnType" : false, "ServiceConfiguration" : { "Cache-Control" : "max-age=30" }, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 6 } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourcecollection+json", "application/json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "upsert", "method" : "POST", "header" : "Upsert-Mode=true", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/12.0/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } } }
記述リクエストでのETagの使用
ETagを使用すると、サービス・クライアントは前回記述をフェッチしてからWebサーバーのメタデータが変更されているか確認できるようになります。そのためには、ETagヘッダーを記述リクエストのレスポンスで返します。
ETagは、Webサーバーによって特定のバージョンのRESTリソースの記述に割り当てられる識別子です。RESTリソースの記述の表現が変更されると、異なるETagが新たに割り当てられます。ETagはHTTPヘッダー内で一意に使用されます。ETagの使用の詳細は、「データ整合性のチェック」を参照してください。
RESTリソースの記述の取得時に、WebサーバーはRESTリソースの現在の表現とともに、対応するETag値をHTTPレスポンス・ヘッダーのETagフィールド内に指定して返します。次に例を示します。
ETag: "5265766973696F6E33"クライアントは表現とそのETagをキャッシュできます。同じ記述を再度取得する必要がある場合、クライアントはリクエストのIf-None-Matchフィールドで、そのETagの保存済コピーを送信します。次に例を示します。
If-None-Match: "5265766973696F6E33"この後続のリクエストで、サーバーはクライアントのETagを現行バージョンのリソースのETagと比較します。ETag値が一致する場合はリソースが変更されていないことを示し、サーバーはHTTP 304 Not Modifiedステータスのレスポンスを送信します。このステータスは、キャッシュされたバージョンが有効であることを示します。
次のサンプルは、employeesリソースに対するETagの動作を記述します。
例22-1 ETag値が一致する場合
リクエスト
-
URL
/rest/v1/employees/describe -
HTTPメソッド
GET
-
If-None-Match
"5265766973696F6E33" -
Metadata-Context
label=latest -
ペイロード
なし
レスポンス
-
HTTPコード
304 -
ETag
"5265766973696F6E33" -
Metadata-Context
label="Revision3" -
ペイロード
なし
例22-2 ETag値が一致しない場合
リクエスト
-
URL
/rest/v1/employees/describe -
HTTPメソッド
GET
-
If-None-Match
"5265766973696F6E33" -
Metadata-Context
label=latest -
ペイロード
なし
レスポンス
-
HTTPコード
200 -
ETag
"5265766973696F6E34" -
Metadata-Context
label="Revision4" -
ペイロード
{ "Resources" : { "employees" : { ... } } }
ノート:
リクエスト・メタデータ・コンテキストが最新のMDSラベルを読み取るように構成されていない場合、ETagは返されません。
リソース・バージョンの取得
JDeveloperでは、ADF RESTリソース開発者は、バージョン識別子を作成し、これらの識別子を自分が作成したリソースに関連付けます。バージョン識別子を使用することで、RESTリソース開発者は既存のリソース定義の更新を管理できます。前のバージョンと後方互換性のない変更を使用してリソースを更新する必要がある場合、リソース開発者は新しいバージョンのリソースを作成し、そのリソースに一意のバージョン識別子を割り当てることができます。
ADF RESTランタイムでは、アプリケーションで定義されているバージョンの取得(使用可能なすべてのバージョンまたは特定のバージョンのみの取得など)をサポートしています。
また、RESTリソース開発者は、バージョン識別子を作成または更新するときにライフサイクル・ステータス(active、desupported、deprecated)を割り当てることができます。deprecatedのタグが付けられたリソースは、有効なリソースとして処理され、そのステータスはランタイムに影響を与えません。これに対し、ライフサイクル・ステータスdesupportedのタグが付いているリソースは、サービス・クライアントからアクセスできなくなり、サポートされないバージョンに対するリクエストは、次のエラー・メッセージを返します。
JBO-29151: The requested version 'x' has been desupported.
サービス・クライアントが、リクエストされたバージョンに存在しないリソースをリクエストすると、ADF RESTランタイムによって、ステータスがactiveまたはdeprecatedになっている前のバージョンにフォールバックされます。このため、Departmentsリソースのバージョン11.0および11.1が存在し、11.2が存在しない場合は、バージョン11.2へのリクエストに対して、次に最新のリソースであるバージョン11.1が返されます。
使用可能なすべてのリリース・バージョン名の取得
ADF RESTランタイムでは、GETメソッドを使用した、サービス・エンドポイントに定義されているリリース・バージョン名の取得をサポートしています。
リリース・バージョン名を調査するには:
-
サービス・エンドポイントの記述を実行し、その記述内で使用可能なリリース・バージョン名を検索します。
-
次の要素を調査して、リリース・バージョンの順序を理解します。
-
versionは、adf-config.xmlファイルで定義されているバージョン名を指定します。 -
isLatestプロパティは、最新のリリース・バージョンのバージョン名を指定します。 -
predecessor-versionは、前のリリース・バージョンへのリンクを指定します。 -
successor-versionは、2番目に最新のリリース・バージョンへのリンクを指定します。 -
currentは、最新のリリース・バージョンへのリンクを指定します。
-
-
必要に応じて、次の要素を調査し、特定のリリース・バージョンについてリクエストの処理に使用するADF RESTフレームワーク・バージョンのバージョンを理解します。
-
defaultFrameworkVersionプロパティは、ADF RESTリソース開発者が必要に応じてadf-config.xmlファイルで定義した、特定のリリース・バージョンに関連付けられているデフォルトのADF RESTフレームワーク・バージョンを指定します。新しいADF RESTフレームワーク・バージョンによって新機能が導入されることがあります。したがって、特定のフレームワーク・バージョンを各リリース・バージョンに関連付けると、サービス・クライアントは適切なレベルの機能とやり取りするようになります。「ADF RESTフレームワーク・バージョンの使用」を参照してください。 -
allowedFrameworkVersionsプロパティでは、特定のリリース・バージョンでサポートされるADF RESTフレームワーク・バージョンのリストを指定します。サービス・クライアントは、REST-Framework-Versionヘッダーの値を指定することでリスト内の任意の値でデフォルトのフレームワーク・バージョンをオーバーライドできます。
-
たとえば、2つのリリース・バージョンを持つサービス・エンドポイントの記述は、次のオブジェクトを返します。
{
"items" : [
{
"version" : "version_identifier_latest",
"isLatest" : true,
"adf:extension" : {
"defaultFrameworkVersion" : "framework_identifier",
"allowedFrameworkVersions" : [ "framework_identifier1", "framework_identifier2", ... ]
},
"links" : [
{
"rel" : "self",
...
},
{
"rel" : "canonical",
...
},
{
"rel" : "predecessor-version",
...
},
{
"rel" : "describe",
...
}
]
},
{
"version" : "version_identifier_previous",
"adf:extension" : {
"defaultFrameworkVersion" : "framework_identifier",
"allowedFrameworkVersions" : [ "framework_identifier1", "framework_identifier2", ... ]
},
"links" : [
{
"rel" : "self",
...
},
{
"rel" : "canonical",
...
},
{
"rel" : "successor-version",
...
},
{
"rel" : "describe",
...
}
]
}
],
"links" : [
...
{
"rel" : "current",
...
}
]
}
次のサンプルは、demoアプリケーションのリソース・カタログで定義されている、使用可能なすべてのリリース・バージョンを取得します。このサンプルでは、3つのリリース・バージョンが11.0、11.1および11.2で、11.2が現在の(最新の)リリース・バージョンです。タイプpredecessor-versionとsuccessor-versionのリンクは、各リリース・バージョンの位置をバージョンのリストにおけるそれぞれの相対位置で指定することに注意してください。このサンプルでは、バージョン11.0および11.1はADF RESTフレームワーク・バージョン1に明示的に関連付けられており、リリース・バージョン11.2はADF RESTフレームワーク・バージョン3に関連付けられています。フレームワーク・バージョンが新しいフレームワーク・バージョンによって新機能が導入される特定のOracle JDeveloperリリースに対応するADF RESTフレームワークの特定のバージョンのことを指すことに注意してください。
リクエスト
-
URL
http://server/demo/rest -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.description+json -
ペイロード
{ "items" : [ { "version" : "11.2", "isLatest" : true, "adf:extension" : { "defaultFrameworkVersion" : "3", "allowedFrameworkVersions" : [ "1", "2", "3" ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2", "name" : "canonical", "kind" : "item" }, { "rel" : "predecessor-version", "href" : "http://server/demo/rest/11.1", "name" : "predecessor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.2/describe", "name" : "describe", "kind" : "describe" } ] }, { "version" : "11.1", "adf:extension" : { "defaultFrameworkVersion" : "1", "allowedFrameworkVersions" : [ "1", "2", "3" ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1", "name" : "canonical", "kind" : "item" }, { "rel" : "predecessor-version", "href" : "http://server/demo/rest/11.0", "name" : "predecessor-version", "kind" : "item" }, { "rel" : "successor-version", "href" : "http://server/demo/rest/11.2", "name" : "successor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.1/describe", "name" : "describe", "kind" : "describe" } ] }, { "version" : "11.0", "adf:extension" : { "defaultFrameworkVersion" : "1", "allowedFrameworkVersions" : [ "1", "2", "3" ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0", "name" : "canonical", "kind" : "item" }, { "rel" : "successor-version", "href" : "http://server/demo/rest/11.1", "name" : "successor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.0/describe", "name" : "describe", "kind" : "describe" } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest", "name" : "self", "kind" : "collection" }, { "rel" : "canonical", "href" : "http://server/demo/rest", "name" : "canonical", "kind" : "collection" }, { "rel" : "current", "href" : "http://server/demo/rest/11.2", "name" : "current", "kind" : "item" } ] }
特定バージョンのリソースの取得
ADF RESTランタイムでは、GETメソッドを使用した、特定バージョンのリソースの取得をサポートしています。特定のリソース・バージョンとは、設計時にリソースに関連付けられたバージョンです。リリース・バージョン識別子は、adf-config.xmlの概要エディタの「リリース・バージョン」ページで定義されています。
次のサンプルは、2つのバージョンのDepartmentsリソースを記述します。最初のリソースの記述(リクエスト1)はバージョン11.0を返し、2番目の記述(リクエスト2)はバージョン11.1を返します。11.1のリソースの記述は、追加の必須属性HireDateとPhoneNumberがリソースで定義されていることを示しています。
リクエスト・バージョン1
-
URL 1
http://server/demo/rest/11.0/Departments -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.describe+json -
ペイロード1
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { ... } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { ... } ] }, "item" : { "links" : [ { ... } ], }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } } }
リクエスト・バージョン2
-
URL 2
http://server/demo/rest/11.1/Departments -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.describe+json -
ペイロード2
{ "Resources" : { "Employees" : { "discrColumnType" : false, "title" : "Employees All Attributes", "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10 }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] }, { "name" : "HireDate", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true }, { "name" : "PhoneNumber", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 } ], "collection" : { ... } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { ... } ] }, "item" : { "links" : [ { ... } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } } }
ADF RESTリソースの取得
ADF RESTランタイムでは、次のGETメソッドのユースケースをサポートしています。
-
リソース・コレクションのフェッチ。
-
ページ・リソース・コレクションのフェッチ。
-
主キー・ファインダ・パラメータを使用したリソース・ペイロードのフィルタ処理。
-
問合せパラメータを使用したリソース・ペイロードのフィルタ処理。
-
リソース・アイテムのフェッチ。
-
ネストされた子リソースのフェッチ。
-
ソートされたリソース・コレクションのフェッチ。
- リソース・コレクションまたはリソース・アイテムをフェッチして、
@context要素の下でアイテムの詳細をグループ化します。
リソース・コレクションのフェッチ
ADF RESTランタイムでは、GETメソッドを使用したリソース・コレクションのフェッチをサポートしています。
次のサンプルは、バージョン11.0のDepartmentsリソース・コレクションおよび5つのアイテムをフェッチします。
リクエスト
-
URL
http://server/sample/rest/11.0/Departments -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 30, "DepartmentName" : "Purchasing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/30/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 40, "DepartmentName" : "Human Resources", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/40/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 5, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
リソース・コレクションのページング
ADF RESTランタイムでは、GETメソッドを使用した、行セット・ページ区切りによるリソース・コレクションの取得をサポートしています。GETメソッドを使用したリソース・コレクションのページングは、次のURI問合せパラメータを使用して実行されます。
-
limitは、リソース・コレクション内で返されるリソースの数を制限します。limitがリソース数より大きい場合、フレームワークは使用可能なすべてのリソースを返します。値は、返されるリソースの最大数です。
-
offsetは、ゼロを基準とする索引(0が最初の位置)をコレクションに定義します。索引により、リソース・コレクションの開始位置が識別されます。offsetがリソース数より大きい場合、リソースは返されません。
(Departmentsリソース・コレクションに5つのアイテムがある)次のサンプルは、最初のリクエスト(URL1)が2つのアイテム(索引0と1)を取得し、offsetが省略されているため、レスポンスの開始位置は最初のアイテムになります。別のリソース・アイテム・セットを表示するために、2番目のリクエスト(URL2)では、3番目のアイテムに対応するように2のoffsetが使用され、2つのアイテム(索引2と3)のみを追加で取得するために2のlimitを使用して作成されており、最後のリクエスト(URL3)では、5つのリソース・コレクション・アイテムの最後のアイテム(索引4)を返すために4のoffsetが使用されています。
新しいリソース・アイテム・セットが取得されるたびに、レスポンスのhasMore属性は追加のアイテムがコレクションから返される可能性があるかどうかを示します。この例では、コレクションに含まれるアイテムは5つのみであるため、URL3のレスポンスではhasMoreがfalseに設定され、アイテムの最後のセットが取得済であることを示します。
limitパラメータがページングURLで省略された場合、ADF RESTランタイムでは、limitが(リソースのイテレータ・バインディング定義でデフォルトのRangeSize値として決められている) 25であると想定されることに注意してください。この場合、最大25のアイテムが各リクエストで返されます。このため、コレクションをページングする場合は、常にlimit問合せパラメータを含めて、必要な数のリソース・アイテムのみが返されるようにし、それ以上返されないようにするのがベスト・プラクティスです。
リクエスト
-
URL 1
http://server/demo/rest/11.0/Departments?limit=2 -
URL 2
http://server/demo/rest/11.0/Departments?offset=2&limit=2 -
URL 3
http://server/demo/rest/11.0/Departments?offset=4&limit=2 -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード1
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : true, "limit" : 2, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] } -
ペイロード2
{ "items" : [ { "DepartmentId" : 30, "DepartmentName" : "Purchasing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/30/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 40, "DepartmentName" : "Human Resources", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/40/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : true, "limit" : 2, "offset" : 2, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] } -
ペイロード3
{ "items" : [ { "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 1 "hasMore" : false, "limit" : 2 "offset" : 4, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
主キー値によるリソース・コレクションのフィルタ処理
ADF RESTランタイムでは、GETメソッドおよび(リソースの1つ以上の主キー属性で定義されるファインダを含む)固定URLを使用したリソース・コレクションのフェッチをサポートしています。リソースの基礎となる各ビュー・オブジェクトは、少なくとも1つの主キー属性を定義します。ADF RESTランタイムでは、ファインダ問合せ文字列の主キー値を渡してコレクションをフィルタ処理することをサポートしています。
主キー(PK)によるフィルタ処理は、1つ以上の主キー値を指定するファインダ問合せ文字列を使用して実行されます。主キー問合せ文字列パラメータを含むファインダの形式は、次のとおりです。
finder=PrimaryKey;<PKattr1>=<PKvalue1>,<PKattr2>=<PKvalue2>,...
たとえば、リソース・コレクションEmployeesは、主キー属性EmployeeIdを定義します。特定の従業員の主キー検索を使用してコレクションをフィルタ処理するには、検索問合せ文字列を、次の例で示すように指定します。
finder=PrimaryKey;EmployeeId=101
リソースが、複数の部分からなる主キーによって定義される場合、検索は主キー値の対応する数を渡してコレクションをフィルタ処理できます。たとえば、リソース・コレクションInventoryには、主キー属性としてProductIdおよびWarehouseIdがあります。特定のインベントリ・アイテムの主キー検索を使用してコレクションをフィルタ処理するには、検索問合せ文字列に両方の主キー値を、次の例で示すように指定します。
finder=PrimaryKey;ProductId=8568,WarehouseId=45
リソース・コレクションの記述は、ファインダおよび主キー属性を説明します。主キー・ファインダを使用するには:
-
リソースの記述を実行し、コレクション要素内の
finders属性を検索します。name属性は、ファインダをPrimaryKeyとして識別します。また、attributesの下の主キー属性の名前も検索します。 -
問合せパラメータ
finderを指定してGETを実行し、ファインダ名PrimaryKeyを使用して主キー属性を渡します。
たとえば、Employeesリソースの記述は次を返します。
"collection" : {
"rangeSize" : 24,
"finders" : [ {
"name" : "PrimaryKey",
"attributes" : [ {
"name" : "EmployeeId",
"type" : "integer",
"updatable" : true,
"mandatory" : true,
"queryable" : false
"precision" : 4,
} ]
次のサンプルは、(EmployeeId属性値101が渡される)ファインダPrimaryKeyで指定されたEmployeesコレクションをフェッチします。
ノート: 主キーではない属性でコレクションをフィルタ処理するには、「行検索によるリソース・コレクションのフィルタ処理」を参照してください。
リクエスト
-
URL
http://server/demo/rest/11.1/Employees?finder=PrimaryKey;EmployeeId=101 -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "items" : [ { "EmployeeId" : 101, "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 2000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/101", "name" : "Employees", "kind" : "item" } ] } ], "count" : 1, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees", "name" : "Employees", "kind" : "collection" } ] }
問合せパラメータによるリソース・コレクションのフィルタ処理
ADF RESTランタイムでは、GETメソッドを使用した、問合せパラメータによるリソース・コレクションのフェッチをサポートしています。
リソース・コレクションは、ADF RESTサービス・クライアントに登録されているADF RESTフレームワーク・バージョンに応じて、構文が異なる式を使用して問い合せることができます。ADF RESTフレームワーク・バージョンの詳細は、「ADF RESTフレームワークのバージョニングに関する必知事項」を参照してください。
次のサンプルは、Departmentsリソースの2つの異なるバージョンに基づいています。リソース11.0を示すURLサンプルは、ADF RESTフレームワークのバージョン1でのみサポートされるQuery-by-Example問合せパラメータ構文を表しています。一方、リソース11.1を示すURLサンプルは、ADF RESTフレームワーク・バージョン2 (以降)でサポートされるRowMatch問合せパラメータ構文を表しています。どちらのフレームワークのシナリオでも、サンプルではDepartmentsリソース・コレクションのフィールドをフェッチします。
ノート:
REST Webサービス・リクエストでは、問合せパラメータ値に表示される予約文字をエンコードする必要があります。たとえば、タイムスタンプ値の+文字は、%2Bとしてエンコードする必要があります。また、デフォルトでは、問合せパラメータ操作で使用されるリソースおよびリソース・アイテムの名前は大/小文字が区別されます。大/小文字を区別しないフィルタリングが必要な場合は、adf-config.xmlファイルのフラグrestV1QueryCaseSensitiveをfalseに設定できます。フラグのデフォルト値は、大/小文字を区別するフィルタリングを意味するtrueです。
ADF RESTフレームワーク・バージョン2 (以降)
ADF RESTフレームワークのバージョン2から、サービス・クライアントでは、拡張問合せ構文(RowMatch式とも呼ばれる)を使用してリソースをフェッチできます。バージョン2 (以降)で使用できる問合せ構文の詳細は、「ADF RESTフレームワーク・バージョン2の拡張問合せ構文に関する必知事項」を参照してください。
次のサンプルでは、給与が10000である従業員が少なくとも1人いるすべての部門をフェッチします。これは、親オブジェクト(Departments)をフェッチし、子オブジェクト属性(Employees.Salary)でフィルタ処理する例です。
フレームワーク・バージョン2を使用して作成したリクエストの例1
-
URL
http://server/demo/rest/11.2/Departments?q=Employees.Salary = 10000 -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
フレームワーク・バージョン2からのレスポンスの例1
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード
{ "items" : [ { "DepartmentId" : 70, "DepartmentName" : "Public Relations", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments/70", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2/Departments/70", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.2/Departments/70/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 80, "DepartmentName" : "Sales", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments/820", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2/Departments/80", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.2/Departments/80/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments", "name" : "Departments", "kind" : "collection" } ] }
次のサンプルでは、数値IDが10または文字「H」で始まる部門名を持つすべての部門をフェッチします。
フレームワーク・バージョン2を使用して作成したリクエストの例2
-
URL
http://server/demo/rest/11.1/Departments?q=DepartmentId = 10またはDepartmentName like 'H*' -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
フレームワーク・バージョン2からのレスポンスの例2
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.2/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 40, "DepartmentName" : "Human Resources", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.2/Departments/40/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments", "name" : "Departments", "kind" : "collection" } ] }
ADF RESTフレームワーク・バージョン1
ADF RESTフレームワークのバージョン1では、Query-by-Example構文をサポートしています。バージョン1でのみサポートされるこの構文を使用するのにアプリケーション構成の変更は必要ありません。ADF RESTフレームワークのバージョン1で使用可能な問合せ構文の説明は、「GETメソッドの操作」を参照してください。
次のサンプルは、30未満のDepartmentId値が割り当てられた部門をフェッチします。
ノート:
ADF RESTフレームワークのバージョン1では、文字列照合フィルタ・パラメータを使用して問合せを作成し、照合する文字列に問合せ構文の予約語(ANDやORなど)が含まれている場合、問合せ式内の他のパラメータと区別するために、引用符で囲まれた文字列を空白文字で区切る必要があります。たとえば、次の問合せは、引用符で囲まれた文字列'Accounting and Finance'に対してフィルタ処理しようとします。文字列には予約語ANDが含まれているため、バージョン1で実行可能にするには、文字列照合フィルタ・パラメータは、一重引用符の前後に空白が必要です。
?q=DepartmentName= 'Accounting and Finance' &fields=DepartmentName,Location
フレームワークバージョン2以降、予約語を含む文字列照合フィルタを区切るために空白文字を使用する必要はなくなりました。
フレームワーク・バージョン1を使用して作成したリクエスト
-
URL
http://server/demo/rest/11.0/Departments?q=DepartmentId<30 -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
フレームワーク・バージョン1からのレスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
リソース・アイテムのフェッチ
ADF RESTランタイムでは、GETメソッドを使用したリソース・コレクションのアイテムのフェッチをサポートしています。
次のサンプルは、バージョン11.0のDepartmentsリソース・コレクションのインスタンスのすべてのフィールドをフェッチします。
リクエスト
-
URL
http://server/demo/rest/11.0/Departments/50 -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
ネストされた子リソースのフェッチ
ADF RESTランタイムでは、GETメソッドを使用した、ネストされたリソースの取得をサポートしています。
ネストされた子リソースのペイロード構造は、ADF RESTサービス・クライアントに登録されているADF RESTフレームワーク・バージョンによって異なります。ADF RESTフレームワーク・バージョンの詳細は、「ADF RESTフレームワークのバージョニングに関する必知事項」を参照してください。
次のサンプルは、Employeesリソースの2つの異なるバージョンに基づいています。リソース11.0を示すURLサンプルは、ADF RESTフレームワーク・バージョン1および2でサポートされるレスポンス・ペイロード構造を表しています。一方、リソース11.1を示すURLサンプルは、ADF RESTフレームワーク・バージョン3 (以降)でサポートされるレスポンス・ペイロード構造を表しています。どちらのフレームワークのシナリオでも、サンプルではDepartmentsリソースの子としてEmployeesリソースをフェッチします。
ネストされたリソースの識別に使用される名前は、リソースがADFビジネス・コンポーネント・モデル・プロジェクトで作成される場合、設計時に決定されることに注意してください。モデル・プロジェクトで作成されるネストされたリソースのデフォルト名は、ネストされたリソースのビュー・リンク・アクセッサ定義の宛先ビュー・インスタンスです(ビュー・リンクDeptToEmpFkLinkのEmployeesView1など)。このため、ADF RESTリソース開発者にとって、リソース名をURLパラメータとしてより適切な名前に変更することがベスト・プラクティスです。次の例では、リソース名は、親リソース名Departmentsの命名規則に従ってEmployeesに変更されています。
ADF RESTフレームワーク・バージョン3 (以降)
ADF RESTフレームワークのバージョン3から、ADF RESTランタイムは、リソース・アイテムの配列としてではなく、リソース・コレクションとしてレスポンス・ペイロード内にネストされた子リソースを返します。フレームワーク・バージョン3 (以降)で使用可能なこの機能を使用すると、サービス・クライアントでは、初期リクエストでフェッチされないままのアイテム数を特定した後、追加レコードのリクエストを作成できます。子リソースの属性hasMoreおよびcountは、リソース・コレクションからさらにアイテムを返すことができるかどうかを示します。ADF RESTフレームワーク・バージョン3を選択した場合、レスポンス・ペイロードからのページ区切り属性の使用方法の詳細は、「リソース・コレクションのページング」を参照してください。
次のサンプルでは、ADF RESTフレームワーク・バージョン3 (以降)の機能を示します。レスポンス・ペイロードはネストされた子リソースをリソース・コレクションとして表し、コレクション・オブジェクトにhasMore属性とcount属性が含まれています。追加のリソース・アイテムについて子リソースを問合せる必要がある場合は、リンクが提供されます。このサンプルでは、Employees子リソースのアイテムがペイロードにフェッチされ、countが3です。レスポンス・ペイロードは、hasMore属性がfalseである、つまりフェッチされていないアイテムがないことを示しています。
フレームワーク・バージョン3を使用して作成したリクエスト
-
URL
http://server/demo/rest/11.1/Departments/50?expand=Employees -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
フレームワーク・バージョン3からのレスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "DepartmentId" : 50, "DepartmentName" : "Shipping", "Employees" : { "items" : [ { "EmployeeId" : 120, "FirstName" : "Matthew", "LastName" : "Weiss", "Email" : "MWEISS", "JobId" : "ST_MAN", "DepartmentId" : 50, "Salary" : 8000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.1/Departments/50", "name" : "Departments", "kind" : "item" } ] }, { "EmployeeId" : 121, "FirstName" : "Adam", "LastName" : "Fripp", "Email" : "AFRIPP", "JobId" : "ST_MAN", "DepartmentId" : 50, "Salary" : 8200, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/50/child/Employees/121", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Departments/50/child/Employees/121", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.1/Departments/50", "name" : "Departments", "kind" : "item" } ] }, { ... } ] } ], "count" : 3, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Departments/50", "name" : "Departments", "kind" : "item" } ] }
ADF RESTフレームワーク・バージョン1またはバージョン2
ADF RESTフレームワークのバージョン1およびバージョン2は、ネストされた子リソースをレスポンス・ペイロード内に展開されたリソース・アイテムの配列として返します。フェッチされるリソース・コレクションが大規模である場合、リソース・アイテムの配列には制限があるため、リクエストを複数作成する必要があります。
次のサンプルでは、ADF RESTフレームワーク・バージョン1およびバージョン2の機能を示します。
最初のリクエスト・サンプル(URL 1)は、従業員120で識別される単一の子リソース・アイテムを取得します。URLパラメータchildは、リクエストされたリソースEmployeesの関係を識別します。
2番目のリクエスト(URL 2)では、問合せパラメータexpandを使用して、Departmentsリソース・コレクション50でネストされているすべてのEmployeesリソース・アイテムが確実に返されるようにしています。
3番目のリクエスト(URL 3)はアクセッサ・ドット表記法の使用(例: Employees.JobHistory)を示しています。問合せパラメータexpandも併用しているため、Departmentsリソース・コレクション80で、ネストされているすべてのJobHistoryリソースがEmployeesリソース・アイテムとともに返されます。
フレームワーク・バージョン1またはバージョン2を使用して作成したリクエスト
-
URL 1
http://server/demo/rest/11.0/Departments/50/child/Employees/120 -
URL 2
http://server/demo/rest/11.0/Departments/50?expand=Employees -
URL 3
http://server/demo/rest/11.0/Departments/80?expand=Employees.JobHistory&onlyData=true -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
フレームワーク・バージョン1またはバージョン2からのレスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード1
{ "EmployeeId" : 120, "FirstName" : "Matthew", "LastName" : "Weiss", "Email" : "MWEISS", "JobId" : "ST_MAN", "DepartmentId" : 50, "Salary" : 8000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" } ] } -
ペイロード2
{ "DepartmentId" : 50, "DepartmentName" : "Shipping", "Employees" : [ { "EmployeeId" : 120, "FirstName" : "Matthew", "LastName" : "Weiss", "Email" : "MWEISS", "JobId" : "ST_MAN", "DepartmentId" : 50, "Salary" : 8000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" } ] }, { "EmployeeId" : 121, "FirstName" : "Adam", "LastName" : "Fripp", "Email" : "AFRIPP", "JobId" : "ST_MAN", "DepartmentId" : 50, "Salary" : 8200, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/121", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/121", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" } ] }, { ... } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" } ] }
-
ペイロード3
{ "DepartmentId" : 80, "DepartmentName" : "Sales", "RelState" : null, "Employees" : [ ... { "EmployeeId" : 176, "FirstName" : "Jonathon", "LastName" : "Taylor", "Email" : "JTAYLOR", "JobId" : "SA_REP", "DepartmentId" : 80, "Salary" : 8600, "CommissionPct" : 0.2, "JobHistory" : [ { "EmployeeId" : 176, "StartDate" : "2011-03-24", "EndDate" : "2012-12-31", "JobId" : "SA_REP", "DepartmentId" : 80 }, { "EmployeeId" : 176, "StartDate" : "2013-01-01", "EndDate" : "2015-03-31", "JobId" : "SA_MAN", "DepartmentId" : 80 } ] }, ... ] }
リソース・コレクションのソート
ADF RESTランタイムでは、GETメソッドを使用した、フェッチ済リソース・コレクションのソートをサポートしています。
リソース・コレクションのソートは、orderBy問合せ文字列パラメータを1つ以上の属性名と組み合せて使用して実行されます。次のオプションのソート順序フラグを各属性に関連付けることができます。
-
ascは昇順でソートします。(デフォルト)
-
descは降順でソートします。
orderBy問合せ文字列パラメータの形式は次のとおりです。
<orderBy_attribute1_name>:<(asc/desc)>, <orderBy_attribute2_name>:<(asc/desc)>
例: attribute1:desc,attribute2
GETメソッドを使用して、リソース・コレクションで大/小文字を区別しないソートを実行するためには、orderBy問合せ文字列パラメータが次の形式に従う必要があります。
upper(<orderBy_attribute1_name>):<(asc)>またはlower(<orderBy_attribute2_name>)
次のサンプル(URL1)は、DepartmentName属性でソートされたDepartmentsコレクションをフェッチします。2番目のサンプル(URL2)は、salary属性でソートされた子Employeesコレクションをフェッチします。いずれのリクエスト・サンプルにもソート順序フラグが指定されていないため、レスポンスは昇順になります。
リクエスト
-
URL 1
http://server/demo/rest/11.0/Departments?orderBy=DepartmentName -
URL 2
http://server/demo/rest/11.0/Departments/50/child/Employees?orderBy=Salary -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード1
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 40, "DepartmentName" : "Human Resources", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/40/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 30, "DepartmentName" : "Purchasing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/30/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 5, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] } -
ペイロード2
{ "items" : [ { "EmployeeId" : 132, "FirstName" : "TJ", "LastName" : "Olson", "Email" : "TJOLSON", "JobId" : "ST_CLERK", "DepartmentId" : 50, "Salary" : 2100, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/132", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/132", "name" : "Employees", "kind" : "item" } ] }, { "EmployeeId" : 136, "FirstName" : "Hazel", "LastName" : "Philtanker", "Email" : "HPHILTAN", "JobId" : "ST_CLERK", "DepartmentId" : 50, "Salary" : 3100, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/136", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/136", "name" : "Employees", "kind" : "item" } ] } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees", "name" : "Employees", "kind" : "collection" } ] }
グループ化されたコンテキスト情報を持つリソースのフェッチ
ADF RESTランタイムでは、GETメソッドを使用したリソースのフェッチおよび、リソース・フィールドおよびリンクなどのリソース・アイテムのコンテキスト情報を含むペイロードの取得がサポートされており、リクエストでADF RESTフレームワーク・バージョン6を使用できる場合は、アイテムの情報を個別にグループ化できます。
ADF RESTフレームワークのバージョン6以降、リソース・フィールドと個々のアイテムのコンテキスト情報をより簡単に区別できるように、リソース・リクエストのレスポンス・ペイロードに@context要素が導入されました。この要素により、各アイテムの情報をグループ化して、GETリクエストのレスポンス・ペイロードを整理できます。
以前のフレームワーク・バージョン(5以前)と比較して、フレームワーク・バージョン6以降のGETリクエスト・ペイロードの結果には、次の変更が加えられました。
-
新しい
@contextセクションがリソースの各アイテムのフィールド・リストの下に表示され、アイテムの識別情報およびリンクが提供されます。 -
新しい
key要素が@contextセクション内に表示され、特定のリソース・アイテムの一意識別子が文字列として提供されます。 -
@contextセクション内のlinksセクションには、changeIndicatorなどのプロパティはリストされなくなります。 -
changeIndicator値はETagに移動され、@contextセクション内のheaders要素の下にあります。
次のサンプルでは、Departmentsリソース・コレクションと3つのアイテムを各アイテムのコンテキスト情報とともに@context要素の下にフェッチします。
フレームワーク・バージョン6を使用して作成したコレクション・リクエストの例
-
URL
http://server/sample/rest/12.0/Departments -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
フレームワーク・バージョン6を使用して作成したコレクション・レスポンスの例
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "@context" : { "key" : "1", "headers" : { "ETag" : "ACED00C78" }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] } }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "@context" : { "key" : "2", "headers" : { "ETag" : "ACED00B74" }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] } }, { "DepartmentId" : 30, "DepartmentName" : "Purchasing", "@context" : { "key" : "3", "headers" : { "ETag" : "ACED001E8" }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/30/child/Employees", "name" : "Employees", "kind" : "collection" } ] } } ], "count" : 3, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
次のサンプルでは、Departmentsリソース・コレクションのインスタンスのすべてのフィールドを各アイテムのコンテキスト情報とともに@context要素の下にフェッチします。
フレームワーク・バージョン6を使用して作成したアイテム・リクエストの例
-
URL
http://server/demo/rest/12.0/Departments/50 -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
フレームワーク・バージョン6を使用して作成したアイテム・レスポンスの例
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "DepartmentId" : 50, "DepartmentName" : "Shipping", "@context" : { "key" : "1", "headers" : { "ETag" : "ACED00G26" }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] } }
リソース・アイテムの作成
ADF RESTランライムでは、次の作成ユースケースをサポートしています。
-
コレクションでのリソース・アイテムの作成。
-
子リソース・アイテムの作成。
コレクションでのリソース・アイテムの作成
ADF RESTランタイムでは、POSTメソッドを使用した、既存のリソース・コレクションでのリソース・アイテムの作成をサポートしています。
POSTメソッドでリクエストを行う前に、リソース・アイテムがLOV有効属性で定義されているかどうかを確認します。LOV有効属性が存在し、その属性が必須として定義されている場合は、まずリソース・コレクション上のLOVリソースにアクセスして、エンド・ユーザーに選択リストが表示されるようにする必要があります。LOVリソースのアクセス方法の詳細は、「リソース・アイテム作成時のLOV有効属性値の取得」を参照してください。
次のサンプルは、単一のアイテムを含む新しいDepartmentsリソース・コレクションを作成します。
リクエスト
-
URL
http://server/demo/rest/11.0/Departments -
HTTPメソッド
POST
-
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "DepartmentId" : 15, "DepartmentName" : "NewDept" }
レスポンス
-
HTTPコード
201 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
場所
http://server/demo/rest/Departments/15 -
ペイロード
{ "DepartmentId" : 15, "DepartmentName" : "NewDept", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/15/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
子リソース・アイテムの作成
ADF RESTランタイムでは、POSTメソッドを使用した、1つのラウンドトリップでのADF REST子リソース・アイテムの作成をサポートしています。作成は、親と子が両方とも存在しない場合にのみ成功します。
次のサンプルは、ネストされたリソース・アイテムを作成します。最初のリクエスト・サンプル(URL1)は、既存のDepartmentsリソース内に従業員999で識別される子リソース・アイテムを作成します。2番目のリクエスト(URL2)は、親リソースと子リソースを作成します。
リクエスト
-
URL 1
http://server/demo/rest/11.0/Departments/15/child/Employees -
URL 2
http://server/demo/rest/11.0/Departments -
HTTPメソッド
POST
-
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード1
{ "EmployeeId": 999, "FirstName": "New", "LastName": "Guy", "Email": "NGUY", "JobId": "SA_REP", "DepartmentId": 15, "Salary": 9999 } -
ペイロード2
{ "DepartmentId": 17, "DepartmentName": "NewerDept", "Employees": [ { "EmployeeId": 99999, "FirstName": "Newer", "LastName": "Guy", "Email": "NRGUY", "JobId": "SA_MAN", "DepartmentId": 17, "Salary": 10001 } ] }
レスポンス
-
HTTPコード
201 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
場所
http://server/demo/rest/11.0/Departments/15/child/Employees/999 -
ペイロード1
{ "EmployeeId" : 999, "FirstName" : "New", "LastName" : "Guy", "Email" : "NGUY", "JobId" : "SA_REP", "DepartmentId" : 15, "Salary" : 9999, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/15/child/Employees/999", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/15/child/Employees/999", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.0/Departments/15/child/Employees/999/lov/JobsView1", "name" : "JobsView1", "kind" : "collection" } ] } -
場所
http://server/demo/rest/11.0/Departments/17 -
ペイロード2
{ "DepartmentId" : 17, "DepartmentName" : "NewerDept", "Employees" : [ { "EmployeeId" : 99999, "FirstName" : "Newer", "LastName" : "Guy", "Email" : "NRGUY", "JobId" : "SA_MAN", "DepartmentId" : 17, "Salary" : 10001, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/17/child/Employees/99999", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/17/child/Employees/99999", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/17", "name" : "Departments", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.0/Departments/17/child/Employees/99999/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/17", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/17", "name" : "Departments", "kind" : "item" } ] }
リソース・アイテムの更新
ADF RESTランタイムでは、PATCHメソッドを使用したリソース・アイテムの更新をサポートしています。更新は、行がすでに存在している場合にのみ成功します。
次のサンプルは、(DepartmentNameがリクエスト・ペイロードで変更された) Departmentsアイテム15を更新します。
リクエスト
-
URL
http://server/demo/rest/11.0/Departments/15 -
HTTPメソッド
PATCH
-
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "DepartmentId" : 15, "DepartmentName" : "UpdatedDeptName" }
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "DepartmentId" : 15, "DepartmentName" : "UpdatedDeptName", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/15/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
リソース・アイテムの更新または作成(Upsert)
ADF RESTランタイムでは、Upsertモードが有効になっているPOSTメソッドを使用した、既存のリソース・アイテムの更新とリソース・アイテムの作成(アイテムが存在しない場合)をサポートしています。
ヘッダー変数Upsert/trueを指定してPOSTメソッドを使用するとUpsert機能が有効化され、これにより、ADF RESTリソースの作成(このリソースが存在しない場合)または更新(リソースが存在する場合)が行われます。このアクション(Upsert)を有効にするには、ユーザー・インタフェースで「作成」および「更新」チェック・ボックスを選択します。ヘッダー変数Upsert/trueが指定されていないか、Upsert/falseに設定されている場合、Upsert機能は無効になります。また、「作成」チェック・ボックスのみが選択されているか、「更新」チェック・ボックスのみが選択されている場合、POSTでは、リソースの作成または更新の権限が許可されていれば、そのアクションを実行します。Upsertが意図したとおりに機能するのは、リソースで「作成」と「更新」の両方のオプションが有効になっている場合のみです。
次のサンプルは、子のEmployeeリソース・アイテムを持つ新しいDepartmentリソース・アイテムを(Upsertを介して)作成します。
リクエスト
-
URL
http://server/demoapp/rest/1.0/Departments -
HTTPメソッド
POST -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
HTTPヘッダー
Upsert-Mode/true -
ペイロード
{ "Deptno": 80, "Dname": "ENG80", "Emp": [{ "Empno": 8080, "Ename": "Smith", "Mgr": 8080 }] }
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
コンテンツ・エンコーディング
Null -
ペイロード
{ "Deptno": 80, "Dname": "ENG80", "Emp": [{ "Empno": 8080, "Ename": "Smith", "Mgr": 8080 }] }
次のサンプルは、(Upsertを介した)更新プロセスを示しています。レスポンス・ペイロードでは、Department (Dept)リソース・アイテムのAltKey (Dname)が使用されます。同様に、Employee (Emp)子リソース・アイテムのAltKey (Email)が使用されます。Dname Altkey (Dname=ENG80)を使用して、要求されたDepartment (Dept 80)を検索およびロードします。次に、このDepartmentのLocation (Loc)が更新されます。Email Altkeyを使用してEmployee子リソース・アイテム(Emp 8080)を検索およびロードし、リクエスト・ペイロードでこのEmployee子リソース・アイテムのSal属性とJob属性が更新されます。リクエスト・ペイロードには、2番目のEmployee子リソース・アイテム(Emp 9080)も含まれています。Enameキーを使用して、この2番目のEmployee子リソース・アイテムを検索します。見つかった場合は、この2番目のEmployee子リソース・アイテムのSal属性とJob属性が更新されます。この2番目のEmployee子リソース・アイテムが存在しない場合は、リクエスト・ペイロードにより、この2番目のEmployee子リソース・アイテムが作成されます。
リクエスト
-
URL
http://server/demoapp/rest/1.0/Departments -
HTTPメソッド
POST -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
HTTPヘッダー
Upsert-Mode/true -
ペイロード
{ "Dname": "ENG80", "Loc": "HQ-altkey", "Emp": [{ "Email": "smith@xyz.com", "Sal": 8000, "Job": "ENGINEER1" }, { "Empno": 9080, "Ename": "John", "Sal": 9000, "Job": "SALES1" } ] }
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
コンテンツ・エンコーディング
Null -
ペイロード
{ "Deptno": 80, "Dname": "ENG80", "Loc": "HQ-altkey", "TrEmpno": null, "Emp": [{ "Empno": 8080, "Ename": "Smith", "Job": "ENGINEER1", "Email": "smith@xyz.com", "Hiredate": null, "Sal": 8000, "Comm": null, "Deptno": 80 }, { "Empno": 9080, "Ename": "John", "Job": "SALES1", "Mgr": 9080, "Hiredate": null, "Sal": 9000, "Comm": null, "Deptno": 80 } ] }
リソース・アイテムの削除
ADF RESTランタイムでは、DELETEメソッドを使用したリソース・アイテムの削除をサポートしています。フレームワークでは、リソース・コレクションの削除は現在サポートされていません。
次のサンプル(URL1)は、Employeesリソース・コレクションの従業員ID 99999をDepartmentsリソース・アイテム17の子として削除します。2番目のリクエストURLは、Departmentsリソース・アイテム17を削除します。
リクエスト
-
URL 1
http://server/demo/rest/11.0/Departments/17/child/Employees/99999 -
URL 2
http://server/demo/rest/11.0/Departments/17 -
HTTPメソッド
DELETE
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
204 -
コンテンツ・タイプ
なし
-
ペイロード
なし
データ整合性のチェック
ADF RESTランタイムでは、リクエストされたリソースでデータ整合性チェックが有効な場合、レスポンス・ヘッダーへのエンティティ・タグ(ETag)の生成をサポートしています。データ整合性チェックは、リソースの基礎となるエンティティ・オブジェクトで更新識別子属性を構成する必要があるADFビジネス・コンポーネント開発者によって有効化されます。
リソースの基礎となるエンティティ・オブジェクトでエンティティ更新識別子が構成されている場合、ADF RESTランタイムは、サーバー側の各リソースの状態を示す一意の値を割り当てます。実行時に、サーバー側リソースの基礎となっている行が変更されると、Oracle ADFは新しい状態値をETagに割り当てます。次のヘッダーは、Departmentsリソース・アイテムを取得するリクエストで返されるETagを示しています。
HTTP/1.1 200 OK Cache-Control: no-cache, no-store, must-revalidate Location: Content-Length: 1069 Content-Type: application/json ETag: "ACED00057372037200136261636C6520136261636C65237200136261636C652" Content-Encoding: Link: <http://server/demo/rest/11.0/Departments/10>;rel="self";kind="item";name="Departments"
ノート:
ETagおよびデータ整合性チェックは、RESTリソースで自動的に有効化されないことに注意してください。ETag値の生成をサポートするために、ADFビジネス・コンポーネント開発者は、チェックされるリソースの基礎となるエンティティ・オブジェクトで更新識別子有効属性を構成する必要があります。エンティティ・オブジェクトでの更新識別子属性の構成の詳細は、「同時更新によるデータの消失を防ぐ方法」を参照してください。
サービス・クライアントは、各リソース・アイテムのレスポンス・ヘッダーで返されたETag値を使用して、事前条件ヘッダー(If-Match/If-None-Match)を含む後続のリクエストを実行できます。指定されたETagおよび事前条件に基づいて、サーバーは現在のリソース状態を評価し、指定されたETagと照合します。事前条件が満たされている場合はリクエストされた操作が実行され、満たされていない場合は412エラーが返されます。エラー・ペイロードにはサーバー側の現在のリソースが含まれ、ヘッダーでは現在のETag値も反映されます。
ETag値のテストをサポートするために、ADF RESTフレームワークでは、次の事前条件ヘッダー・フィールドが提供されています。これらの事前条件フィールドを使用すると、フレームワークは、指定されたETag値を、前にリクエストされたアイテムのETag値と比較します。
-
クライアントが(前のリソース・アイテム・レスポンスから取得して)提供している状態が、サーバーの現在の状態に一致することを検証します。
If-Match: "<ETag value from resource item response>" -
クライアントが(前のリソース・アイテム・レスポンスから取得して)提供している状態が、サーバーの現在の状態に一致しないことを検証します。
If-None-Match: "<ETag value from resource item response>"
次に、データ整合性をチェックする場合の一般的なユースケースを示します。
-
リソース・アイテムが、更新前のサーバー側リソース状態に一致することを確認します。
-
リクエストされたいずれのアイテムも前にリクエストされたアイテムに一致しない場合、サーバー側リソース状態を使用してリソース・アイテムを取得します
これらのユースケースにGETメソッドとPATCHメソッドが関連する場合は、事前条件ヘッダーとETag値を使用して、HTTPメソッド操作がリソースの現在の状態に適用されることを確認できます。
リソース・コレクションを取得すると、追加のカスタム・プロパティchangeIndicatorが、データ整合性が有効なリソースのレスポンス・ペイロードに出現します。このプロパティには、リクエストされたコレクション内の各リソース・アイテムの現在のETag値が含まれます。次のサンプルは、Departmentsリソース・コレクションのlinksセクション内のchangeIndicatorプロパティを示しています。リソース・コレクション・ペイロードにETag値が存在すると、サーバー・クライアントは個別のリソース・アイテムからETagを取得するためのリクエストの数を減らすことができるため、サーバー・クライアントにとって便利です。
レスポンス内にRelState属性が存在することにも注意してください。これは、ADFビジネス・コンポーネント開発者がデータ整合性チェックをサポートするためにエンティティ・オブジェクトで構成した更新識別子属性の名前です。この属性の値は、状態が更新された回数を反映します。
{
"items" : [ {
"DepartmentId" : 10,
"DepartmentName" : "Administration",
"RelState" : 1,
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item",
"properties" : {
"changeIndicator" : "ACED0005737200136A6176612E7574696C2E41727261794C69737
47881D21D99C7619D03000149000473697A65787000000001770400000001737200186F721
636C652E6A626F2E646F6D61696E2E4E7564A362286F0200015B0004646174617400025B45
27870757200025B42ACF317F8060854E00200007870"
}
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item",
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item",
"properties" : {
"changeIndicator" : "ACED0005737200136A6176612E7574696C2E149000473697A6578
70000000017704000000017372001B6F7261636C652E6A626F2E646F60000C78"
}
}, {
"rel" : "child",
"href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
"name" : "Employees",
"kind" : "collection",
} ]
}, {
"DepartmentId" : 20,
"DepartmentName" : "Marketing",
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments/20",
"name" : "Departments",
"kind" : "item",
"properties" : {
"changeIndicator" : "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200186F7261636C652E6A626F2E646F6D61696E2E4E756D626572A5B1371914E0BFDA0200014900096D48617368436F6465787200116F7261636C652E73716C2E4E554D424552E90466EE632BE1D5020000787200106F7261636C652E73716C2E446174756D4078F514A362286F0200015B0004646174617400025B427870757200025B42ACF317F8060854E0020000787000000002C10A0000000078"
}
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Departments/20",
"name" : "Departments",
"kind" : "item"
}, {
"rel" : "child",
"href" : "http://server/demo/rest/11.0/Departments/20/child/Employees",
"name" : "Employees",
"kind" : "collection"
} ]
}, {
...
} ]
} ],
"count" : 5,
"hasMore" : true,
"limit" : 25,
"offset" : 0,
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments",
"name" : "Departments",
"kind" : "collection"
} ]
}
ADF RESTリソース・アイテムの更新時のデータ整合性のチェック
ADF RESTランタイムでは、更新識別子属性が有効になっているADFビジネス・コンポーネント・エンティティ・オブジェクトが基礎となっているリソース・アイテムを、PATCHメソッドを使用して更新する際のデータ整合性チェックをサポートしています。
ETagヘッダーおよび条件付きヘッダー・フィールドを使用してデータ整合性をチェックするには:
-
1つ以上のリソース・アイテムを問い合せて、返されたリソース・アイテムごとに、レスポンスの
propertiesセクション内のchangeIndicatorプロパティからETag値を取得します。複数のリソース・アイテムを問い合せる場合、単一のETagレスポンス・ヘッダーはありません。かわりに、レスポンス内の各アイテムのETagはpropertiesセクションにあります。HTTP/1.1 200 OK Cache-Control: no-cache, no-store, must-revalidate Location: Content-Length: 861 Content-Type: application/json ETag: "responseETag123" Content-Encoding: Link: <http://server/demo/rest/11.0/Departments/10>;rel="self";kind="item";name="Departments" Set-Cookie: JSESSIONID=jXvsJ1GpdkFJV5Jh0yk7D72vPZ42t8tLYDg74NRKFQzXdnsjG9vv!1113104013; path=/; HttpOnly X-ORACLE-DMS-ECID: 51f1ff4535af720c:-7e156247:148ec9eeb3b:-8000-00000000000001ad X-Powered-By: Servlet/2.5 JSP/2.1 { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "responseETag123" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
-
PATCHリクエストを使用してリソース・アイテムを更新し、次の条件付きヘッダー・フィールドを指定してデータ整合性をチェックします。
-
If-Match: "<ETag value from resource item response>"(リクエストされたリソース・アイテムの状態が、前のリソース・アイテム・レスポンスの最新状態であることを検証します)。
-
次のサンプルは、If-Match事前条件テストが満たされた場合、Departments 10リソース・アイテムのDepartmentNameフィールドを更新します。最初のリクエスト(リクエスト1)で、ETag値responseETag123は、サーバー側の現在のDepartments 10リソース・アイテムのETagと同一であり、リソース・アイテムの状態がサーバー側と一致していることを示します。この結果、DepartmentNameに対する更新が許可されます。
ただし、後続のリクエスト(リクエスト2)では、If-Match事前条件で指定されたETagは変更されておらず、サーバー側のDepartments 10リソース・アイテムの新しいETag値と一致しなくなります。古いETag値が2番目のリクエストで使用された結果として、更新は(事前条件テストに失敗したことを示す) HTTPコード412で失敗し、現在のETag値responseETag567がレスポンス・ヘッダーで返されます。これは、複数のユーザーが同じリソース・アイテムに同時にアクセスする場合、本番Webアプリケーションで発生します。たとえば、ユーザー1とユーザー2の両方が同じアイテムを問い合せると、そのアイテムは、たとえばETag値1を持ちます。次に、ユーザー1がETag値1でアイテムを正常に更新し、ユーザー2がETag値1で同じアイテムを更新しようとすると失敗します。
リクエスト1
-
URL 1
http://server/demo/rest/11.0/Departments/10 -
HTTPメソッド
PATCH
-
事前条件1
If-Match: "responseETag123" -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード1
{ "DepartmentName" : "FirstAttempt_NewDepartmentName" }
レスポンス1
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ETag
responseETag567 -
ペイロード1
{ "DepartmentId" : 10, "DepartmentName" : "FirstAttempt_NewDepartmentName", "RelState" : null, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "responseETag567" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
リクエスト2
-
URL 2
http://server/demo/rest/11.0/Departments/10 -
HTTPメソッド
PATCH
-
事前条件2
If-Match: "staleETag789" -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード2
{ "DepartmentName" : "SecondAttempt_NewDepartmentName" }
レスポンス2
-
HTTPコード
412(事前条件が失敗しました) -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ETag
responseETag567 -
ペイロード2
{ "DepartmentId" : 10, "DepartmentName" : "FirstAttempt_NewDepartmentName", "RelState" : null, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "responseETag567" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
ADF RESTリソース・アイテムの取得時のデータ整合性のチェック
ADF RESTランタイムでは、更新識別子属性が有効なADFビジネス・コンポーネント・エンティティ・オブジェクトが基礎となっているリソース・アイテムを、GETメソッドを使用して取得する際のデータ整合性チェックをサポートしています。
ETagヘッダーおよび条件付きヘッダー・フィールドを使用してデータ整合性をチェックするには:
-
1つ以上のビジネス・オブジェクト・アイテムを問い合せて、返されたリソース・アイテムごとに、レスポンスの
propertiesセクション内のchangeIndicatorプロパティからETag値を取得します。複数のビジネス・オブジェクト・アイテムを問い合せる場合、単一のETagレスポンス・ヘッダーはありません。ADF RESTフレームワークのバージョン5以前の場合、レスポンス内の各アイテムのETagは
propertiesセクションにあります。フレームワーク・バージョン6以降の場合、各アイテムのETagは@context要素内にあり、この要素を使用してアイテムのすべての情報を1つのセクションにグループ化します。次のサンプルは、バージョン6を有効にする前のフレームワーク・バージョンでのレスポンスを示しています。HTTP/1.1 200 OK Cache-Control: no-cache, no-store, must-revalidate Location: Content-Length: 861 Content-Type: application/json ETag: "responseETag123" Content-Encoding: Link: <http://server/demo/rest/11.0/Departments/10>;rel="self";kind="item";name="Departments" Set-Cookie: JSESSIONID=jXvsJ1GpdkFJV5Jh0yk7D72vPZ42t8tLYDg74NRKFQzXdnsjG9vv!1113104013; path=/; HttpOnly X-ORACLE-DMS-ECID: 51f1ff4535af720c:-7e156247:148ec9eeb3b:-8000-00000000000001ad X-Powered-By: Servlet/2.5 JSP/2.1 { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "ACED0005737200136A6176612E7574696C2E4" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] } -
1つ以上のビジネス・オブジェクト・アイテムを問い合せて、次の条件付きヘッダー・フィールドを指定してデータ整合性をチェックします
。
-
If-None-Match: "<ETag value from resource item response>"(前にリクエストされたいずれのリソース・アイテムの状態も、リソース・アイテム・リクエストの最新状態でないことを検証します)。
-
次のサンプルは、If-None-Match事前条件が満たされた場合、Departments 10リソース・アイテムを取得します。最初のリクエスト(リクエスト1)で、ETag値responseETag123は、サーバー側の前にリクエストされたDepartments 10リソース・アイテムのETagと一致し、リソース・アイテムの状態がサーバー側と一貫性があることを示します。結果として、事前条件は失敗し、新しいDepartments 10リソース・アイテムを返す必要はありません。リクエストは、サーバーの状態が変更されていないことを示すHTTPコード304を返します。
ただし、後続のリクエスト(リクエスト2)では、If-None-Match事前条件で指定されたETag unmatchedETagXYZはサーバーに存在しません。結果として、事前条件が成功し、Departments 10リソース・アイテムが取得されます。リクエストは、条件が変更されたことを示すHTTPコード200を返し、現在の(変更されていない) ETag値responseETag123がレスポンス・ヘッダーで返されます。
リクエスト1
-
URL 1
http://server/demo/rest/11.0/Departments/10 -
HTTPメソッド
GET
-
事前条件1
If-None-Match: "responseETag123" -
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス1
-
HTTPコード
304(状態は変更されていません) -
コンテンツ・タイプ
なし
-
ペイロード1
なし
リクエスト2
-
URL 2
http://server/demo/rest/11.0/Departments/10 -
HTTPメソッド
GET
-
事前条件2
If-None-Match: "unmatchedETagXYZ" -
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス2
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ETag
responseETag123 -
ペイロード2 (フレームワーク・バージョン5以前で作成)
{ "DepartmentId" : 10, "DepartmentName" : "Administration", "RelState" : null, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "responseETag123" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }ペイロード2 (フレームワーク・バージョン6以降で作成)
{ "DepartmentId" : 10, "DepartmentName" : "Administration", "RelState" : null, "@context" : { "key" : "AB8765BCD", "headers" : { "ETag" : "responseETag123." }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item", }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
添付の使用
ADF RESTランタイムでは、BLOB属性またはCLOB属性のコンテンツ・ストリーミングをサポートしています。
LOB属性は、次の方法で処理されます。
-
ペイロード自体には含まれていないカスタム・コンテンツとしてリンクされます。
これは、BLOB属性とCLOB属性のデフォルト設定であり、サポートされているペイロード・タイプ(
image/pngなど)で表すことができないリソースを指すenclosureリンク・タイプを使用してレスポンス・ペイロードで指定されます。 -
Base64文字列形式にエンコードされ、リクエスト・ペイロード自体に含められます。
現在、高度な機能(チャンク・エンコードのサポートなど)は、ADF RESTランタイムでサポートされていません。エンタープライズ・アーキテクチャで作業している開発者は、特殊なコンテンツ管理システム(Oracle WebCenter Contentなど)の使用を調査する場合があります。
attributeセクションでLOB属性を示すかわりに、レスポンス・ペイロードにはコンテンツへのenclosureリンクが常に含まれます。Employeesリソース・アイテムの次の記述では、application/octet-streamのデフォルトのrequestTypeを使用してBLOB属性Pictureを定義します。リソース・アイテムのenclosureリンクがitemsセクションに表示されます。actionsセクションでは、コンテンツの操作に使用できる操作を識別します。
{
"Resources" : {
"Employees" : {
"discrColumnType" : false,
"attributes" : [ {
...
}, {
"name" : "Picture",
"type" : "attachment",
"updatable" : true,
"mandatory" : false,
"queryable" : false,
"actions" : [ {
"name" : "delete",
"method" : "DELETE"
}, {
"name" : "get",
"method" : "GET",
"responseType" : [ "application/octet-stream" ]
} ]
} ],
"item" : {
"links" : [ {
...
}, {
"rel" : "enclosure",
"href" : "http://server/demo/rest/11.0/Employees/101/enclosure/Picture",
"name" : "Picture",
"kind" : "other"
} ],
"actions" : [ {
} ]
},
"links" : [ {
...
} ]
}
}
リソース・アイテムの属性コンテンツ・タイプは、ADF RESTリソース開発者がcontentTypeプロパティをLOBタイプ属性のカスタム・プロパティとして構成することで割り当てることができます。たとえば、PNGイメージ・ファイルを使用する場合、コンテンツ・タイプを前もって割り当てることができます。
-
カスタム・プロパティ:
contentType -
値:
image/png
一部のユースケースでは、この属性自体がなんらかの外部コンテンツへのリンクとなります。属性がこの方法で構成されている場合、リソース・アイテム・ペイロードに表示されるだけでなく、外部コンテンツを指すリンクも作成されます。リソースの説明では、GETアクションのみを外部リンクに使用できます。属性値に含まれるURLを変更するには、リソース・アイテムでの更新のリクエストを実行します。
ADF RESTリソース開発者は、次の属性を追加して、リンクを生成するように属性を構成できます。
-
名前:
inputHandler -
値:
oracle.adf.internal.model.rest.core.binding.inputHandler.LinkInputHandler
リソース・アイテムのエンクロージャ・リンクを使用した添付のストリーミング
ADF RESTランタイムでは、リソース・アイテムのペイロードに含めることができないストリーミング・コンテンツを、そのコンテンツへのリンクを使用することでサポートしています。リンクされたコンテンツに対してサポートされているメソッドはGETとDELETEです。リソース・アイテムを(POSTメソッドを使用して)作成すると同時にLOBコンテンツを作成する場合、コンテンツをbase64としてエンコードする必要があることに注意してください。base64を使用してコンテンツを埋め込む方法のサンプルは、「Base64を使用したLOBコンテンツの置換」を参照してください。
リンクからコンテンツをストリーミングするには:
-
リソース・アイテムを取得し、目的の属性の
enclosureリンクを検索します。itemセクションで、使用可能な属性のリンクを定義します。または、リソースの説明を実行して、リソース・アイテムで生成されたエンクロージャ・リンクを識別できます。一般に、リソースの説明には、GETリソース・ペイロードでは返されないその他の有用な情報(
image/pngなどの予期されるレスポンス・タイプなど)、およびサポートされる属性のアクションが含まれています。 -
LOBコンテンツへのリンクを使用して、HTTP操作(GETまたはDELETE)を実行します。
Employees 101の次のリソース・アイテムは、linksセクション内のPicture属性のenclosureリンクを示します。
ノート:
enclosureに指定するURLは、イメージのURLではなく、イメージのエンクロージャ・リンクにする必要があります。
{
"EmployeeId" : 101,
"FirstName" : "Neena",
"LastName" : "Smith",
"Email" : "NSMITH",
"JobId" : "AD_VP",
"DepartmentId" : 90,
"Salary" : 2000,
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Employees/101",
"name" : "Employees",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Employees/101",
"name" : "Employees",
"kind" : "item"
}, {
"rel" : "lov",
"href" : "http://server/demo/rest/11.0/Employees/101/lov/JobsLOV",
"name" : "JobsLOV",
"kind" : "collection"
}, {
"rel" : "enclosure",
"href" : "http://server/demo/rest/11.0/Employees/101/enclosure/Picture",
"name" : "Picture",
"kind" : "other"
} ]
}
たとえば、次のサンプルは、従業員101に関連付けられているPNGイメージをストリーミングします。
様々なメディア・タイプをサポートするために、リクエスト・タイプはデフォルトでapplication/octet-streamになることに注意してください。ADF RESTリソース開発者がカスタム・プロパティcontentTypeを定義している場合は、指定されたリクエスト・タイプがリソース・アイテムの説明に表示されます。
リクエスト
-
URL
http://server/demo/rest/11.0/Employees/101/enclosure/Picture -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
image/png -
ペイロード
ストリーミングされたコンテンツ
Base64を使用したLOBコンテンツの置換
ADF RESTランタイムでは、コンテンツがbase64文字列形式で表されている場合、JSONペイロードを使用してLOBコンテンツを作成および更新できます。
たとえば、次のサンプルは、従業員101のPNGイメージを置換します。このユースケースでは、Picture属性はbase64でエンコードされた文字列としてリクエスト・ペイロード内に表される必要があります。リソース・アイテム101はすでに存在し、Picture属性のみが操作されるため、他の属性を指定する必要はありません。
レスポンス・ペイロードには、Picture属性へのenclosureリンクが含まれることに注意してください。
リクエスト
-
URL
http://server/demo/rest/11.0/Employees/101 -
HTTPメソッド
PATCH
-
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "Picture" : "/9j/4AAQSkZJRgABAAEAYABgAAD//..." }
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "EmployeeId" : 101, "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 2000, "links" : [ { "rel" : "lov", "href" : "http://server/demo/rest/11.0/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" }, { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Employees/101/enclosure/Picture", "name" : "Picture", "kind" : "other" } ] }
LOVの使用
ADF RESTランタイムでは、次のLOV有効属性のユースケースをサポートしています。
-
スタンドアロンLOVの非依存LOV有効属性値を取得します。
既知の含有リソース・アイテムのコンテキストでLOV有効リソース・アイテムを更新できるようにする必要がある場合は、このユースケースを参照してください。
-
カスケードLOV用のネストされたLOV有効属性値を取得します。
依存LOV有効属性に基づいて、ネストされたLOVリソース・アイテムを更新できるようにする必要がある場合は、このユースケースを参照してください。
ADF RESTフレームワーク・バージョン5以降、ユースケースのプロシージャが変更されたことに注意してください。フレームワークの旧バージョンでは、RESTリクエストはユースケースに依存していました。しかし、フレームワーク・バージョン5以降、すべてのLOVユースケース(スタンドアロンまたはカスケード)は、静的LOVリソースに対して有効にする行検索URLに依存します。
フレームワークのバージョン1から4での非依存LOV有効属性値の取得
ADF RESTフレームワーク・バージョン4以前では、ランタイムで、GETメソッドを使用した既知の含有リソース・アイテムのコンテキストでの、LOV有効属性値の取得をサポートしています。
ADF RESTフレームワーク・バージョン4以前では、LOV有効属性のリソース・アイテムは子LOVリソースURLをネストし、この子リソースを、既知の含有リソース・アイテムのコンテキストに基づいて値リストを取得するために使用できます。
ノート:
ADF RESTフレームワーク・バージョン5以降は、行検索URLを使用してLOVリソース・アイテムを移入することをお薦めします。「フレームワーク・バージョン5以降でのLOV有効属性値の取得」を参照してください。ADF RESTフレームワークのバージョン4以前でカスケードLOV属性リストを移入する必要がある場合は、「フレームワークのバージョン1から4での依存LOV有効属性値の取得」を参照してください。
フレームワーク・バージョン4以前において、非キャッシュ・リストでLOV有効属性を使用するには:
-
リソースの記述を実行し、LOVに関する次の詳細を検索します。
リソース属性の
lov記述でchildRefプロパティを検索し、LOVの選択肢を含む子リソース・コレクションを識別します。LOV有効属性値を取得する操作はLOV子リソースではサポートされていないため、LOV子リソースのリソース記述にはlovの説明は表示されません。lov記述には、リソース・アイテムからLOV子リソース・コレクションへのビュー・オブジェクト属性マッピングが含まれます。この属性マッピングには、LOV値が選択された場合に値がリソース・アイテムからコピーされる、子リソースからの1つ以上のソース属性が含まれます。LOVの選択では、LOVを表示する属性以外にリソース・アイテム内の追加の値が導出される場合があります。そのような場合、属性マッピングではderived = trueとしてそれを識別します。最後に、lov記述は、結果がユーザー・インタフェースにバインドされている場合、子リソース・コレクションのどの属性をエンド・ユーザーへの表示に使用できるかを識別します。 -
次に、リソース・アイテムの
links要素を検索し、lovがrelで、対応するLOV子リソース(リソース・アイテムchildRefプロパティで指定されている)を識別するhrefを検索します。ヒント: リソースの記述は、リソース・コレクションから特定のリソース・アイテム名を指定して完了するテンプレートとしてLOV子リソースを表示します。GETを実行してリソース・コレクションを取得し、特定のリソース・アイテムに対応するLOV子リソースの作業リンクを検索できます。
-
LOVリンクを使用してGETを実行し、オプションで、追加のフィルタ処理を使用してLOV結果を絞り込むか、ペイロードから不要な属性を除外します。
lov記述内にリストされている表示属性を常にフェッチする必要があります。表示属性は、エンド・ユーザーが職位のリストなどの認識できる値リストからLOV値を選択できるようにする属性値です。LOV定義により、LOVの選択が適用された場合に正しいソース属性がリソース・アイテムの更新に使用されるようになります。
たとえば、Employeesリソース・コレクションの記述は、次を返します。
{
"Resources" : {
"Employees" : {
"discrColumnType" : false,
"attributes" : [ {
"name" : "EmployeeId",
"type" : "integer",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 6
}, {
"name" : "FirstName",
"type" : "string",
"updatable" : true,
"mandatory" : false,
"queryable" : true,
"precision" : 20
}, {
"name" : "LastName",
"type" : "string",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 25
}, {
"name" : "Email",
"type" : "string",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 25
}, {
"name" : "JobId",
"type" : "string",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 10,
"controlType" : "choice",
"maxLength" : "10",
"lov" : {
"childRef" : "JobsLOV",
"attributeMap" : [ {
"source" : "JobId",
"target" : "JobId"
} ],
"displayAttributes" : [ "JobTitle" ]
}
...
"item" : {
"links" : [ {
"rel" : "lov",
"href" :
"http://server/demo/rest/11.0/Employees/{id}/lov/JobsLOV",
"name" : "JobsLOV",
"kind" : "collection"
}, {
...
次のサンプルは、JobsLOVリソース・コレクションからLOV表示属性JobTitleの値をフェッチします。問合せパラメータonlyDataとfieldsにより、表現がフィルタ処理され、レスポンス・ペイロードにデータのみが含まれるようになります(ここで、PresidentとAdministration Assistantは表示属性JobTitleの値の例です)。
フレームワーク・バージョン4以前を使用して作成したリクエスト
-
URL
http://server/demo/rest/11.0/Employees/101/lov/JobsLOV?onlyData=true&fields=JobTitle -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
フレームワーク・バージョン4以前から返されたレスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード
{ "items" : [ { "JobTitle" : "President" }, { "JobTitle" : "Administration Assistant" }, { "JobTitle" : "Finance Manager" }, { "JobTitle" : "Accountant" }, { "JobTitle" : "Accounting Manager" }, { "JobTitle" : "Public Accountant" } ], "count" : 6, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] }
フレームワークのバージョン1から4での依存LOV有効属性値の取得
ADF RESTフレームワーク・バージョン4以前では、依存LOV有効属性リスト(カスケードLOVとも呼ばれる)をサポートする場合など、行コンテキストなしでリソース・アイテムを移入する必要がある場合に、ランタイムではGETメソッドを使用したLOV有効属性値の取得をサポートしています。
ADF RESTフレームワーク・バージョン1から4では、記述によって既知の行のコンテキストなしで依存リストにアクセスするための静的LOV URLが提供され、エンド・ユーザーが1つのLOVで行った選択により、ネストされたLOVに表示されるリストが決定されます。カスケードLOVの例として、StatesとCitiesの2つのリストの表示があげられます。Cities LOV子属性に表示するリストは、State LOV属性の選択が行われるまでは不明です。この場合、モデル・プロジェクトで作業するADF RESTリソース開発者は、行コンテキストを必要としない静的LOVリソースを定義して、リソース記述内のネストされたLOV属性リストにアクセスできるようにします。モデル・プロジェクトでの静的LOVリソースの作成の詳細は、「LOV属性を使用したADF RESTリソースの作成操作のサポート方法」を参照してください。
ADF RESTフレームワーク・バージョン1から4で、非依存LOV属性リスト(1つのLOV)を移入する必要がある場合は、「既存のリソース・アイテムのLOV有効属性値の取得」を参照してください。
ノート:
ADF RESTフレームワーク・バージョン5以降は、行検索URLを使用してLOVリソース・アイテムを移入することをお薦めします。バージョン5が有効な場合、最上位レベルのLOVリソースのみがサポートされ、リソースの記述では、ネストされたLOV子リソースにアクセスするためのURLは提供されません。「フレームワーク・バージョン5以降でのLOV有効属性値の取得」を参照してください。フレームワーク・バージョン4以上で、依存LOV有効属性を使用するには:
-
リソースの記述を実行し、LOVに関する次の詳細を検索します。
属性の
lov記述でlovResourcePathプロパティを検索し、LOVの選択肢を含むLOVリソースを識別します。LOV有効属性値を取得する操作はLOV子リソースではサポートされていないため、LOV子リソースのリソース記述にはlovの説明は表示されません。lov記述には、リソース・アイテムからLOVリソース・コレクションへの属性マッピングが含まれます。この属性マッピングには、LOV値が選択された場合に値がリソース・アイテムからコピーされる、LOVリソースからの1つ以上のソース属性が含まれます。LOVの選択では、LOVを表示する属性以外にリソース・アイテム内の追加の値が導出される場合があります。そのような場合、属性マッピングではderived = trueとしてそれを識別します。最後に、lov記述は、結果がユーザー・インタフェースにバインドされている場合、LOVリソース・コレクションのどの属性をエンド・ユーザーへの表示に使用できるかを識別します。 -
次に、リソース・コレクション記述
links要素を検索し、relがlovで、hrefがそのLOVリソース(lovResourcePathプロパティで指定されている)を識別するリンクを検索します。lovResourcePathは1つ以上のLOVリソースが指定される配列です。配列では、依存LOV有効属性(カスケードLOVとも呼ばれる)のユース・ケースがサポートされます。たとえば、配列"lovResourcePath" : [ "Countries", "States" ]はCountriesとStatesというLOVリソースを指定し、州(States)を表示するLOVリストは国(Countries)のLOVの選択に依存するといったものです。依存LOV属性に表示させる値を取得するには、次のように親LOVリソース・コレクションからの子リンクを使用します。-
LOVリソース・リンクを使用してGETを実行します(
rel: lov、name: Countries)。 -
エンド・ユーザーがLOVリソース・コレクションからリソース・アイテムを選択します(たとえば、
United States)。 -
選択されたリソース・アイテム内の子リンクを使用してGETを実行します(
rel: child、name: States)。これにより、親LOVリソース(国)に基づく値(州)のリストを持つリソース・コレクションを取得できます。
-
-
LOVリソース・リンクを使用してGETを実行し、オプションで、追加のフィルタ処理を使用してLOV結果を絞り込むか、ペイロードから不要な属性を除外します。
lov記述内にリストされている表示属性を常にフェッチする必要があります。表示属性は、エンド・ユーザーが職位のリストなどの認識できる値リストからLOV値を選択できるようにする属性値です。 -
LOVリソースからキャッシュしたLOV属性値があれば、クライアント・ユーザー・インタフェースでLOV表示属性を表示して、そこでエンド・ユーザーからの値の入力を受け付け新しいリソース・アイテムを作成することも可能です。目的の値を入力するときには、LOV有効属性に対して表示されたLOVから値を選択し、「送信」をクリックします。これによりクライアントは作成リクエストを実行できます。ADFビジネス・コンポーネント・ビュー・オブジェクト属性のLOV定義により、LOVの選択が適用された場合に正しいソース属性がリソース・アイテムの更新に使用されるようになります。新しいリソース・アイテムを作成するペイロードのPOSTリクエストの送信方法の詳細は、「コレクションでのリソース・アイテムの作成」を参照してください。
たとえば、Employeesリソース・コレクションの記述は、次を返します。
{
"Resources" : {
"Employees" : {
"discrColumnType" : false,
"attributes" : [ {
"name" : "EmployeeId",
"type" : "integer",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 6
}, {
"name" : "FirstName",
"type" : "string",
"updatable" : true,
"mandatory" : false,
"queryable" : true,
"precision" : 20
}, {
"name" : "LastName",
"type" : "string",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 25
}, {
"name" : "Email",
"type" : "string",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 25
}, {
"name" : "JobId",
"type" : "string",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 10,
"controlType" : "choice",
"maxLength" : "10",
"lov" : {
"childRef" : "JobsLOV",
"attributeMap" : [ {
"source" : "JobId",
"target" : "JobId"
} ],
"displayAttributes" : [ "JobTitle" ],
"lovResourcePath" : [ "Jobs" ]
}
...
},
"links" : [ {
...
"rel" : "lov",
"href" : "http://server/demo/rest/11.0/Jobs",
"name" : "Jobs",
"kind" : "collection"
}, {
...
次のサンプルでは、Jobsリソース・コレクションからLOV表示属性JobTitleの値をフェッチします。問合せパラメータonlyDataとfieldsにより、表現がフィルタ処理され、レスポンス・ペイロードにデータのみが含まれるようになります(ここで、PresidentとAdministration Assistantは表示属性JobTitleの値の例です)。
フレームワーク・バージョン4以前を使用して作成したリクエスト
-
URL
http://server/demo/rest/11.0/Jobs?onlyData=true&fields=JobTitle -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
フレームワーク・バージョン4以前から返されたレスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード
{ "items" : [ { "JobTitle" : "President" }, { "JobTitle" : "Administration Assistant" }, { "JobTitle" : "Finance Manager" }, { "JobTitle" : "Accountant" }, { "JobTitle" : "Accounting Manager" }, { "JobTitle" : "Public Accountant" } ], "count" : 6, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Jobs", "name" : "Jobs", "kind" : "collection" } ] }
フレームワーク・バージョン5以降でのLOV有効属性値の取得
ADF RESTフレームワーク・バージョン5以降、ランタイムでは、既知の含有リソース・アイテムを渡すことによる、または依存LOV属性リストでの実行時の選択に基づく、GETメソッドを使用したLOV有効属性からの値の取得をサポートしています。
行検索URLでは、1つのLOVまたはカスケードLOVのLOVリストの取得をサポートしており、エンド・ユーザーが1つのLOVで行った選択によって、ネストされたLOVに表示するリストが決定されます。カスケードLOVの例として、StatesとCitiesの2つのリストの表示があげられます。Cities LOV子属性に表示するリストは、State LOV属性の選択が行われるまでは不明です。この場合、モデル・プロジェクトで作業するADF RESTリソース開発者は、行コンテキストを必要としない静的LOVリソースを定義して、リソース記述内のネストされたLOV有効属性リストにアクセスできるようにします。モデル・プロジェクトでの静的LOVリソースの作成の詳細は、「LOV属性を使用したADF RESTリソースの作成操作のサポート方法」を参照してください。
リソースの記述から行検索URLを取得してGETリクエストに渡すことで、バインド・パラメータ値を送信して、含有リソースを指定し、LOV有効属性に行コンテキストを与えることができます。カスケードLOVの場合、依存LOV属性値を取得後、取得した値を含むPOSTリクエストをペイロードとして使用して、ネストされたLOVリストを移入できます。
ノート:
ADF RESTフレームワーク・バージョン5以降は、行検索URLを使用してLOVリソース・アイテムを移入することをお薦めします。前のバージョンのフレームワークとは異なり、記述での行検索URLの使用では、依存LOVと非依存LOVの両方がサポートされています。以前のフレームワーク・バージョンでのLOVの使用の詳細は、「フレームワーク・バージョン1から4での非依存LOV有効属性値の取得」と「フレームワーク・バージョン1から4での依存LOV有効属性値の取得」を参照してください。フレームワーク・バージョン5以降で、LOV行検索URLを使用するには:
-
リソースの記述を実行し、LOVに関する次の詳細を検索します。
属性の
lov記述でchildRefForCreateプロパティを検索し、LOVの選択肢を含むLOVリソースを識別します。lov記述には、リソース・アイテムからLOVリソース・コレクションへの属性マッピングが含まれます。この属性マッピングには、LOV値が選択された場合に値がリソース・アイテムからコピーされる、LOVリソースからの1つ以上のソース属性が含まれます。LOVの選択では、LOVを表示する属性以外にリソース・アイテム内の追加の値が導出される場合があります。そのような場合、属性マッピングではderived = trueとしてそれを識別します。最後に、lov記述は、結果がユーザー・インタフェースにバインドされている場合、LOVリソース・コレクションのどの属性をエンド・ユーザーへの表示に使用できるかを識別します。 -
次に、リソース・アイテム記述の
links要素を探し、lovのrelと親LOVリストのhrefでリンクを特定します。 -
LOVリソース・リンクを使用してGETを実行し、オプションで、追加のフィルタ処理を使用してLOV結果を絞り込むか、ペイロードから不要な属性を除外します。
lov記述内にリストされている表示属性を常にフェッチする必要があります。表示属性は、エンド・ユーザーが都道府県のリストなどの認識できる値リストからLOV値を選択できるようにする属性値です。 -
LOVリソースからキャッシュしたLOV属性値があれば、クライアント・ユーザー・インタフェースでLOV表示属性を表示して、そこでエンド・ユーザーからの値の入力を受け付け新しいリソース・アイテムを作成することも可能です。目的の値を入力するときには、LOV有効属性に対して表示されたLOVから値を選択し、「送信」をクリックします。これによりクライアントは作成リクエストを実行できます。ADFビジネス・コンポーネント・ビュー・オブジェクト属性のLOV定義により、LOVの選択が適用された場合に正しいソース属性がリソース・アイテムの更新に使用されるようになります。新しいリソース・アイテムを作成するペイロードのPOSTリクエストの送信方法の詳細は、「コレクションでのリソース・アイテムの作成」を参照してください。
-
依存LOV属性に表示する値を取得するには、選択したリソース・アイテムのパラメータ化された行検索で、LOVリソース・リンク(
childRefForCreateプロパティで指定した)を使用します。選択したリソース・アイテムでLOVリソース・リンク(rel: lovおよびname: CityLOVForCreate)を使用してGETを実行します。これにより、親LOVリソース(都道府県)に基づく値(市区町村)のリストを含むリソース・コレクションを取得できます。
たとえば、Addressリソース・コレクションの記述は、次を返します。
{
"Resources" : {
"Address" : {
"discrColumnType" : false,
"attributes" : [ {
...
}, {
"name" : "City",
"type" : "string",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 32,
"controlType" : "choice",
"maxLength" : "32",
"lov" : {
"childRef" : "CityLOV",
"childRefForCreate" : "CityLOVForCreate",
"attributeMap": [ {
"source" : "CityName",
"target" : "City"
}],
"displayAttributes" : [ "CityName" ],
}
}, {
"name" : "State",
"type" : "string",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 2,
"controlType" : "choice",
"maxLength" : "2",
"lov" : {
"childRef" : "StateLOV",
"childRefForCreate" : "StateLOVForCreate",
"attributeMap": [ {
"source" : "StateCode",
"target" : "State"
}],
"displayAttributes" : [ "StateCode" ],
}
}, {
...
},
"item" : {
"links" : [ {
...
}, {
"rel": "lov",
"href": "http://server/demo/rest/11.0/Address/{id}/lov/CityLOV",
"name": "CityLOV",
"kind": "collection"},
}, {
"rel" : "lov",
"href" : "http://server/demo/rest/11.0/Cities?finder=ByStateFinder%3BstateVar%3D{State}",
"name" : "CityLOVForCreate",
"kind" : "collection"
}, {
}, {
"rel": "lov",
"href": "http://server/demo/rest/11.0/Address/{id}/lov/StateLOV",
"name": "StateLOV",
"kind": "collection"},
}, {
"rel" : "lov",
"href" : "http://server/demo/rest/11.0/States",
"name" : "StateLOVForCreate",
"kind" : "collection"
}, {
...
次のサンプルでは、StatesLOVリソース・コレクションから親LOV表示属性StateCodeの値をフェッチします。問合せパラメータonlyDataとfieldsにより、表現がフィルタ処理され、レスポンス・ペイロードにデータのみが含まれるようになります(ここで、CAとTXは表示属性StateCodeの値の例です)。
フレームワーク・バージョン5を使用して作成したLOVリクエスト
-
URL
http://server/demo/rest/11.0/States?onlyData=true&fields=StateCode -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
フレームワーク・バージョン5によって返されるLOVレスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード
{ "items" : [ { "StateCode" : "CA" }, { "StateCode" : "TX" }, { "StateCode" : "MS" }, { ... } ] }
使用方法にカスケードLOVが含まれる場合、このサンプルでは、LOV表示属性CityNameを持つ依存LOVの値をCities LOVリソース・コレクションからフェッチします。行検索では、親LOVのクライアントで返された状態名CAのパラメータが使用されます。
フレームワーク・バージョン5を使用して作成した依存LOVリクエスト
-
URL
http://server/demo/rest/11.0/Cities?finder=ByStateFinder%3BstateVar%3D{State}" -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
フレームワーク・バージョン5によって返される依存LOVレスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード
{ "items": [{ "Statecode": "CA", "Cityname": "Tracy" }, { "Statecode": "CA", "Cityname": "Pleasanton" }, { "Statecode": "CA", "Cityname": "Jackson" }, { "Statecode": "CA", "Cityname": "San Jose" }, { ... } ] }
ADF RESTフレームワーク・バージョンの使用
サービス・クライアントでは、ADF RESTランタイム・フレームワークのバージョン2で提供される拡張問合せ機能など、新機能または拡張機能を利用するために異なるペイロード形式の引渡しが必要になることがあります。フレームワーク・バージョンとは、特定のOracle JDeveloperリリースから使用可能なADF RESTフレームワークの特定のバージョンのことを指します。
リクエストを処理するフレームワーク・バージョンを指定できると、クライアントでは準備が整えばそれらの機能を選択できます。
ADF RESTランタイムでは、特定のADF RESTフレームワーク・バージョンに応じてリクエストを実行するために次のユース・ケースをサポートしています。
-
サービス・クライアントがペイロードの処理に作用するフレームワーク・バージョンを指定できること。
-
サービス・クライアントが使用するデフォルトのフレームワーク・バージョン(サーバーで構成)を指定できること。
-
ADF RESTリソース開発者がデフォルトのフレームワーク・バージョンをリリース・バージョン下のすべてのURIに対して宣言できること。
-
リクエストでフレームワーク・バージョンを指定していない場合、
/context/<release-version>/で始まるURIに対するすべてのペイロードで、adf-config.xmlファイルで宣言されているデフォルトのフレームワーク・バージョンが想定されます。 -
リクエストでフレームワーク・バージョンを指定している場合、指定されたフレームワーク・バージョンが使用されます。
-
サービス・クライアントは、カスタム・ヘッダーREST-Framework-VersionをRESTリソース・リクエストに渡して、リクエストの実行に使用するフレームワーク・バージョンを指定できます。バージョン・ヘッダーに渡されたADF RESTフレームワーク・バージョンにより、RESTサービス開発者がadf-config.xmlファイルでアプリケーション別に定義したデフォルトのフレームワーク宣言はオーバーライドされます。
サービス・クライアントがバージョン・ヘッダーをリクエストに渡していない場合、ADF RESTランタイムではadf-config.xmlファイルに定義されているデフォルトを使用します。デフォルトのフレームワーク・バージョンが定義されておらず、バージョン・ヘッダーが渡されていない場合は、ADF RESTフレームワークのベース・バージョン(バージョン1)と想定されます。
フレームワーク・バージョン宣言は、adf-config.xmlファイルでアプリケーション固有のリソース・バージョン名ごとにADF RESTリソース開発者が行います。たとえば、次のサンプルは、フレームワーク・バージョン3、2および1が宣言されたリソース・バージョン11.2、11.1および11.0を示しています。
<versions>
<version name="11.2" displayName="11.2" restFrameworkVersion="2"/>
<version name="11.1" displayName="11.1" lifecycle="deprecated" restFrameworkVersion="1"/>
<version name="11.0" displayName="11.0" lifecycle="deprecated" restFrameworkVersion="1"/>
</versions>前述の例では、リクエストがフレームワーク・バージョン・ヘッダーを渡していない場合、リソース11.0および11.1では古いペイロード形式を使用する一方、11.2では新しいペイロード形式を使用します。これにより、フレームワーク・バージョンがリクエストに指定されていない場合、特定のリリース用のリソースにアクセスする既存のサービス・クライアントは、ADF RESTフレームワークによって新しいペイロード形式が導入されても影響を受けませんが、最新のリソースにアクセスする新しいサービス・クライアントは新しいペイロード形式を選択できます。
ルート・リソース/contextには、最新リリースのデフォルトのADF RESTフレームワーク・バージョンが使用されます。
サービス・クライアントでは、特定のリソースについてデフォルトのフレームワーク・バージョンの検出が必要になることもあります。このユース・ケースをサポートするため、次のサンプルが示すように、ADF RESTではリソース・バージョンの記述内にデフォルトのフレームワーク・バージョンを返します。サービス・クライアントは、REST-Framework-Versionヘッダーの値を指定することで、デフォルトのフレームワーク・バージョンを別のフレームワーク・バージョン識別子でオーバーライドできます。allowedFrameworkVersionsプロパティでは、使用可能なフレームワーク・バージョンの値をリストします。
{
"items" : [
{
"version" : "11.2",
"isLatest" : true,
"adf:extension" : {
"defaultFrameworkVersion" : "2",
"allowedFrameworkVersions" : [ "1","2","3","4","5","6","7" ]
},
"links" : [
...各フレームワーク・バージョンでサポートされるADF RESTフレームワーク機能の詳細は、「ADF RESTフレームワークのバージョニングに関する必知事項」を参照してください。
リソース・バージョンのADF RESTフレームワーク・バージョンの取得
ADF RESTランタイムでは、GETメソッドを使用した、サービス・エンドポイントによって定義される各アプリケーション固有のリリース・バージョン名に関連付けられたADF RESTフレームワークのバージョンの取得をサポートしています。
RESTアプリケーションに指定されたリソース・バージョンはアプリケーションのRESTリソースに固有である一方、フレームワーク・バージョンはADF RESTフレームワークの機能における変更を指定し、特定のJDeveloperリリースに対応します。サービス・エンドポイントによって必要なレベルの機能がサービス・クライアントに確実公開されるようにするには、RESTリソース開発者が必要に応じて、アプリケーションのadf-config.xmlファイルでフレームワーク・バージョンを各RESTリソースのリリース・バージョン名に割り当てます。
ノート:
各フレームワーク・バージョンでサポートされるADF RESTフレームワーク機能の詳細は、「ADF RESTフレームワークのバージョニングに関する必知事項」を参照してください。
アプリケーションで定義されたリリース・バージョン名に割り当てられているフレームワーク・バージョンを調べるには:
-
サービス・エンドポイントの記述を実行し、その記述内で使用可能なリリース・バージョン名を検索します。
-
リリース・バージョンを特定する
versionプロパティを探します。 -
関連付けられた
defaultFrameworkVersionプロパティを調べて、特定のリリース・バージョンに対するリクエストの実行に使用されるADF RESTフレームワークのバージョンを把握します。-
defaultFrameworkVersionプロパティは、ADF RESTリソース開発者が必要に応じてadf-config.xmlファイルで定義した、特定のリリース・バージョンに関連付けられているデフォルトのADF RESTフレームワーク・バージョンを指定します。新しいADF RESTフレームワーク・バージョンによって新機能が導入されることがあります。したがって、特定のフレームワーク・バージョンを各リリース・バージョンに関連付けると、サービス・クライアントは適切なレベルの機能とやり取りするようになります。「ADF RESTフレームワーク・バージョンの使用」を参照してください。
-
-
デフォルトのフレームワーク・バージョンをオーバーライドする場合は、
allowedFrameworkVersionsプロパティを調べて、使用可能なバージョンを把握します。-
allowedFrameworkVersionsプロパティでは、特定のリリース・バージョンでサポートされるADF RESTフレームワーク・バージョンのリストを特定します。サービス・クライアントは、REST-Framework-Versionヘッダーの値を指定することでリスト内の任意の値でデフォルトのフレームワーク・バージョンをオーバーライドできます。
-
たとえば、2つのリリース・バージョンを持つサービス・エンドポイントの記述は次のオブジェクトを返します(各リリース・バージョンが特定のADF RESTフレームワーク・バージョンに関連付けられています)。
{
"items" : [
{
"version" : "version_identifier_latest",
"isLatest" : true,
"adf:extension" : {
"defaultFrameworkVersion" : "framework_identifier",
"allowedFrameworkVersions" : [ "framework_identifier1", "framework_identifier2", ... ]
},
"links" : [
{
"rel" : "self",
...
},
{
"rel" : "canonical",
...
},
{
"rel" : "predecessor-version",
...
},
{
"rel" : "describe",
...
}
]
},
{
"version" : "version_identifier_previous",
"adf:extension" : {
"defaultFrameworkVersion" : "framework_identifier",
"allowedFrameworkVersions" : [ "framework_identifier1", "framework_identifier2", ... ]
},
"links" : [
{
"rel" : "self",
...
},
{
"rel" : "canonical",
...
},
{
"rel" : "successor-version",
...
},
{
"rel" : "describe",
...
}
]
}
],
"links" : [
...
{
"rel" : "current",
...
}
]
}次のサンプルは、demoアプリケーションのリソース・カタログで定義されている、使用可能なすべてのリリース・バージョンを取得します。このサンプルでは、3つのリリース・バージョンが11.0、11.1および11.2で、11.2が現在の(最新の)リリース・バージョンです。このサンプルでは、バージョン11.0および11.1はADF RESTフレームワーク・バージョン1に明示的に関連付けられており、リリース・バージョン11.2はADF RESTフレームワーク・バージョン2に関連付けられています。フレームワーク・バージョンが特定のOracle JDeveloperリリースから使用可能なADF RESTフレームワークの特定のバージョンのことを指すことに注意してください。
リクエスト
-
URL
http://server/demo/rest -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.description+json -
ペイロード
{ "items" : [ { "version" : "11.2", "isLatest" : true, "adf:extension" : { "defaultFrameworkVersion" : "3", "allowedFrameworkVersions" : [ "1", "2", "3", "4" ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2", "name" : "canonical", "kind" : "item" }, { "rel" : "predecessor-version", "href" : "http://server/demo/rest/11.1", "name" : "predecessor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.2/describe", "name" : "describe", "kind" : "describe" } ] }, { "version" : "11.1", "adf:extension" : { "defaultFrameworkVersion" : "1", "allowedFrameworkVersions" : [ "1", "2", "3", "4" ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1", "name" : "canonical", "kind" : "item" }, { "rel" : "predecessor-version", "href" : "http://server/demo/rest/11.0", "name" : "predecessor-version", "kind" : "item" }, { "rel" : "successor-version", "href" : "http://server/demo/rest/11.2", "name" : "successor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.1/describe", "name" : "describe", "kind" : "describe" } ] }, { "version" : "11.0", "adf:extension" : { "defaultFrameworkVersion" : "1", "allowedFrameworkVersions" : [ "1", "2", "3", "4" ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0", "name" : "canonical", "kind" : "item" }, { "rel" : "successor-version", "href" : "http://server/demo/rest/11.1", "name" : "successor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.0/describe", "name" : "describe", "kind" : "describe" } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest", "name" : "self", "kind" : "collection" }, { "rel" : "canonical", "href" : "http://server/demo/rest", "name" : "canonical", "kind" : "collection" }, { "rel" : "current", "href" : "http://server/demo/rest/11.2", "name" : "current", "kind" : "item" } ] }
ヘッダーを使用してフレームワーク・バージョンを指定するリクエストの実行
ADF RESTランタイムでは、特定のADF RESTフレームワーク・バージョンに固有の機能がペイロードの処理に作用するように、カスタム・ヘッダーを使用したサービス・エンドポイントでの個々のリクエストの実行をサポートしています。カスタム・ヘッダーによって指定されたフレームワーク・バージョンにより、クライアント・アプリケーションに存在することもあるデフォルトのフレームワーク・バージョンはオーバーライドされます。
ノート:
フレームワーク・バージョンとは、(特定のOracle JDeveloperリリースに対応する)使用可能なADF RESTフレームワークの特定のバージョンのことを指します。各フレームワーク・バージョンでサポートされるADF RESTフレームワーク機能の詳細は、「ADF RESTフレームワークのバージョニングに関する必知事項」を参照してください。
サービス・エンドポイントによって必要なレベルの機能がサービス・クライアントに確実公開されるようにするには、RESTリソース開発者が必要に応じて、デフォルトのADF RESTフレームワーク・バージョンをアプリケーションのadf-config.xmlファイルで指定されている各RESTリソース・バージョンに割り当てます。しかし、サービス・クライアントでは、デフォルトのフレームワーク・バージョンをオーバーライドし、カスタム・ヘッダーに渡された指定のフレームワーク・バージョンを使用して個々のリクエストを処理することもあります。その場合、ADF RESTランタイムでは、宣言されたデフォルトのフレームワーク・バージョンを無視します。
特定のADF RESTフレームワーク・バージョンを使用してリクエストを処理するには、リクエストで、フレームワーク・バージョン番号を指定したカスタム・ヘッダーREST-Framework-Versionを渡す必要があります。たとえば、次のヘッダーは、このバージョン・ヘッダーを渡すリクエストの処理に使用されるフレームワーク・バージョン2を指定しています。
REST-Framework-Version: 2
カスタム・ヘッダーがリクエストで省略されている場合、ADF RESTランタイムでは、adf-config.xmlファイルで定義されているアプリケーションのデフォルトのフレームワーク・バージョンを使用します。アプリケーションでデフォルトのフレームワーク・バージョンが定義されておらず、サービス・クライアントに対するリクエストでバージョン・ヘッダーが省略されている場合、ADF RESTフレームワークのベース・バージョン(バージョン1)と想定されます。
宣言されたデフォルトのフレームワーク・バージョンを使用するリクエストの実行
ADF RESTランタイムでは、宣言されたADF RESTフレームワークのデフォルトのバージョンに固有の機能がペイロードの処理に作用するように、サービス・エンドポイントでのすべてのリクエストの実行をサポートしています。
ノート:
フレームワーク・バージョンとは、(特定のOracle JDeveloperリリースに対応する)使用可能なADF RESTフレームワークの特定のバージョンのことを指します。各フレームワーク・バージョンでサポートされるADF RESTフレームワーク機能の詳細は、「ADF RESTフレームワークのバージョニングに関する必知事項」を参照してください。
サービス・エンドポイントによって必要なレベルの機能がサービス・クライアントに確実公開されるようにするには、RESTリソース開発者が必要に応じて、デフォルトのADF RESTフレームワーク・バージョンをアプリケーションのadf-config.xmlファイルで指定されている各RESTリソース・バージョンに割り当てます。したがって、リクエストが作成されると、ADF RESTランタイムではadf-config.xmlファイルでの宣言に応じて、特定のリソース・バージョンに対するリクエストを処理します。
たとえば、次のURLではリソース・バージョン11.2を指定しています(アプリケーションのadf-config.xmlファイルにより、このリソース・バージョンはADF RESTフレームワークのバージョン2と関連付けられています)。ADF RESTフレームワークのバージョン2ではRowMatchフィルタ式がサポートされるため、結果として、ADF RESTランタイムでは適切な機能でリクエストを処理し、SAで始まる名前(SALESなど)の部門またはLocationがBOSTONの部門をフェッチします。
http://server/demo/rest/11.2/Departments?q=DepartmentName like 'SA*' or Location = 'BOSTON'
サービス・クライアントでは、デフォルトのフレームワーク・バージョンをオーバーライドし、カスタム・ヘッダーに渡された指定のフレームワーク・バージョンを使用して個々のリクエストを処理することもあります。その場合、ADF RESTランタイムでは、アプリケーションのデフォルトを無視します。カスタム・ヘッダーがリクエストで省略されている場合、ADF RESTランタイムでは常に、adf-config.xmlファイルで定義されているアプリケーションのデフォルトのフレームワーク・バージョンを使用します。アプリケーションでデフォルトのフレームワーク・バージョンが定義されておらず、サービス・クライアントに対するリクエストでバージョン・ヘッダーが省略されている場合、ADF RESTフレームワークのベース・バージョン(バージョン1)と想定されます。
警告およびエラー・レスポンスの操作
ADF RESTフレームワーク・バージョン4以降が有効になっている場合、エラー・レスポンスをJSONペイロード形式で、例外の詳細とともに取得できます。フレームワーク・バージョン3以前では、エラー・レスポンスの形式は単純なメッセージ文字列です。
ADF RESTフレームワーク・バージョン6以降が有効になっている場合、警告レスポンスをJSONペイロード形式で、詳細とともに取得できます。
リクエストでADF RESTフレームワーク・バージョン4を使用でき、そのリクエストがapplication/vnd.oracle.adf.error+jsonまたはapplication/jsonメディア・タイプで実行される場合、レスポンスでは、HTTPステータス・コードとエラー・メッセージの他に、例外の詳細を取得できます。フレームワーク・バージョン4では、レスポンスの形式が例外の詳細ペイロードになり、サービス・クライアントに次の利点をもたらします。
-
1つのリクエスト内で複数のエラーが発生した場合、各エラーの詳細が階層構造で表示されます。
-
各エラーに対応するADF例外を特定するアプリケーション固有のエラー・コードが表示される場合があります。
-
各エラーの場所を特定するエラー・パスがリクエスト・ペイロード構造で表示される場合があります。
ノート:
例外の詳細には、アプリケーション固有のエラー・コードやリクエスト・ペイロードのエラー・パスなど、一部の詳細が表示される場合とされない場合があります。
たとえば、次のような間違った書式設定の日付フィールドが含まれるペイロードを使用して送信されたPOSTに対するエラー・レスポンスを、フレームワーク・バージョン3 (以前)が有効な場合とフレームワーク・バージョン4 (以降)が有効な場合とで比較します。
{ "EmpNum" : 5027,
"EmpName" : "John",
"EmpHireDate" : "not a date"
}標準エラー・レスポンス(バージョン3以前)
フレームワーク・バージョン4がない場合、レスポンス・ペイロードは生成されず、かわりにリクエスト・ペイロードを参照しない単一のエラー・メッセージのみがレスポンスで返されます。
"An instance of type oracle.jbo.domain.Date cannot be created from string not a date. The string value must be in format YYYY-MM-DDTHH:MI:SS.sss+hh:mm."
例外ペイロード・エラー・レスポンス(バージョン4以降)
フレームワーク・バージョン4が有効になっている場合、次の例外の詳細ペイロードがレスポンス用に生成されます。ペイロードには通常のHTTPステータス・コードが含まれ、1つ以上の例外の詳細が配列構造で書式設定されます。
{ "title" : "Bad Request",
"status" : "400",
"o:errorDetails" : [ {
"detail" : "An instance of type oracle.jbo.domain.Date cannot be created from string not a date.
The string value must be in format YYYY-MM-DDTHH:MI:SS.sss+hh:mm.",
"o:errorCode" : "26099",
"o:errorPath" : "/EmpHireDate"
} ]
}例外ペイロード警告レスポンス(バージョン6以降)
フレームワーク・バージョン6が有効になっている場合、レスポンスに対して次のような警告詳細ペイロードが生成されます。ペイロードには通常のHTTPステータス・コードが含まれ、リソース・アイテムごとに@contextセクションで警告の詳細が書式設定されます。
"@context" : {
...
} ],
"warnings": [ {
"detail": "Warning from overridden validateEntity method in DeptImpl : DeptName = ABC or DEF"
}, {
"detail": "Attribute set with value 50 for DeptNum in Dept failed",
"o:errorCode": "27011",
"o:errorPath": "/DeptNum"
}, {
"detail": "Warning from overridden create method in DeptViewDefRowImpl"
}, {
"detail": "Warning from overridden afterCommit method in DeptViewImpl"
} ]
}
}例外ペイロード・エラー・レスポンスの理解
-
ADF RESTフレームワーク・バージョンがバージョン4である。
-
application/vnd.oracle.adf.error+jsonまたはapplication/jsonが、レスポンスで使用可能なメディア・タイプである。
例外の詳細ペイロードは、ADF RESTフレームワークで定められた、次の構造を持つJSONオブジェクトです。
{ "title" : "Message as per HTTP status code",
"status" : "HTTP error code",
"o:errorDetails" : [
...
{
"detail" : "Message of detail error",
"o:errorCode" : "error code"
"o:errorPath" : "JSON pointer to the location of the error in the request payload"
},
...
]
}フレームワーク・バージョン4を使用し、application/vnd.oracle.adf.error+jsonメディア・タイプまたはapplication/jsonメディア・タイプのリクエストを作成することで、例外ペイロードをエラー・レスポンスとして選択できます。
例外ペイロード内で、o:errorDetailsは、発生したエラーの数とタイプによって異なる場合があります。さらに、エラー・コードとエラー・パスがレスポンス・ペイロードに表示される保証はないため、サービス・クライアントがそれらに依存することはできません。
標準エラー・メッセージ・レスポンスの取得
ADF RESTフレームワーク・バージョン1から3を有効にしてリクエストが実行されると、ADF RESTランタイムでは、検証またはシステム・エラーを示すエラー・メッセージを生成します。
バージョン4より前のADF RESTフレームワークでは、1つのエラー・メッセージとHTTPステータス・コードがエラー・レスポンスで返されます。バージョン4以降では、サービス・クライアントは詳細な例外ペイロードが含まれるエラー・レスポンスを取得できます。
次のサンプルは、新しい部門レコードを持つDepartmentsオブジェクトの作成を試行します。しかし、この例では、その部門インスタンスのレコードがすでに存在するため、リクエストは失敗します。ADF RESTフレームワーク・バージョン4 (以降)が有効になっていないため、レスポンスはエラー・メッセージです。
フレームワーク・バージョン3を使用して作成したリクエストの例
-
URL
http://server/demo/rest/11.2/Departments -
HTTPメソッド
POST
-
受入れヘッダー
application/vnd.oracle.adf.resourceitem+json,application/json -
ペイロード
{ "DeptNum" : 50, "DeptName" : "SALES", }
フレームワーク・バージョン3からのレスポンスの例
-
HTTPコード
400 -
エラー・レスポンス
A department with the same name already exists. Please provide a different name.
例外ペイロード・エラー・レスポンスの取得
ADF RESTランタイムでは、リクエストでADF RESTフレームワーク・バージョン4を使用でき、そのリクエストが適切なメディア・タイプを使用して実行される場合に、レスポンスで例外の詳細を取得できます。
REST APIフレームワークのバージョン4以降、Webアプリケーションでは、詳細な例外ペイロードが含まれるエラー・レスポンスを取得できます。
例外ペイロードでは、o:errorDetails配列は、リクエスト・オブジェクトでエラーが発生した場所のエラー・パスを提供します。ただし、これらの特定の詳細がWebアプリケーションで常に利用可能なわけではありません。
次のサンプルは、新しい部門アイテムを持つ部門オブジェクトを作成しようとしています。ただし、この例では、部門のアイテムがすでに存在するため、リクエストは失敗します。
フレームワーク・バージョン4を使用して作成したリクエストの例1
-
URL
http://server/demo/rest/11.2/Departments -
HTTPメソッド
POST
-
受入れヘッダー
application/vnd.oracle.adf.resourceitem+json,application/json -
ペイロード
{ "DeptNum" : 50, "DeptName" : "SALES", }
フレームワーク・バージョン4からのレスポンスの例1
-
HTTPコード
400 -
コンテンツ・タイプ
application/json -
ペイロード
{ "title" : "Bad Request", "status" : "400", "o:errorDetails" : [ { "detail" : "A department with the same name already exists. Please provide a different name.", "o:errorCode" : "Dept_Rule_0" } ] }
次のサンプルは、新しい部門アイテムを持つ部門オブジェクトを作成しようとしています。ただし、この例では、入力された従業員名がEmpNameフィールドに定義されている検証ルールで許可されている文字数を超えているため、リクエストは失敗します。
フレームワーク・バージョン4を使用して作成したリクエストの例2
-
URL
http://server/demo/rest/11.1/Departments -
HTTPメソッド
POST
-
受入れヘッダー
application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json -
ペイロード
{ "DeptNum" : 52, "DeptName" : "newDept522", "Employees" : [ { "EmpNum" : 501, "EmpName" : "MILLERSxxxxxxxxxxxxxxxxx" }, { "EmpNum" : 502, "EmpName" : "JONESPxxxxxxxxxxxxxxxxx" } ] }
フレームワーク・バージョン4からのレスポンスの例2
-
HTTPコード
400 -
コンテンツ・タイプ
application/vnd.oracle.adf.error+json -
ペイロード
{ "title" : "Bad Request", "status" : "400", "o:errorDetails" : [ { "detail" : "Value MILLERSxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.", "o:errorCode" : "27040", "o:errorPath" : "/Employees/0/EmpName" }, { "detail" : "Value JONESPxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.", "o:errorCode" : "27040", "o:errorPath" : "/Employees/1/EmpName" } ] }
次のサンプルは、バッチ操作を実行しようとしています。ただし、この例では、エラー・レスポンスの例外詳細ペイロードに示されている理由により、バッチ操作が失敗します。
フレームワーク・バージョン4を使用して作成したリクエストの例3
-
URL
http://server/demo/rest/11.1 -
HTTPメソッド
POST
-
受入れヘッダー
application/vnd.oracle.adf.batch+json,application/vnd.oracle.adf.error+json -
ペイロード
{ "parts": [ { "id": "part1", "path": "/Employees", "operation": "create", "payload" : { "EmpNum" : 1299, "EmpJob" : "CLERK", "EmpMgr" : 7566, "EmpHireDate" : null, "EmpSal" : 245, "EmpComm" : 0, "EmpDeptNum" : 30 } }, { "id": "part2", "path": "/Employees", "operation": "create", "payload": { "EmpNum" : 7589, "EmpName" : "SampleEmpxxxxxxxxxxxxxxxxxx", "EmpJob" : "CLERK", "EmpMgr" : 7566, "EmpHireDate" : null, "EmpSal" : 245, "EmpComm" : 0, "EmpDeptNum" : 30 } }, { "id": "part3", "path": "/Departments", "operation": "create", "payload": { "DeptNum" : 52, "DeptName" : "newDept522", "Employees" : [ { "EmpNum" : 7588, "EmpName" : "SampleEmpxxxxxxxxxxxxxxxxxx", "EmpJob" : "CLERK", "EmpMgr" : 7566, "EmpHireDate" : null, "EmpSal" : 245, "EmpComm" : 0, "EmpDeptNum" : 30 } ] } }, { "id": "part4", "path": "/Departments/10/child/Loc", "operation": "get" }, { "id": "part5", "path": "/Departments?invQP=invVal", "operation": "get" }, { "id": "part6", "path": "/Departments/54", "operation": "delete" }, { "id": "part7", "path": "/1.0/Departments/54", "operation": "get" } ] }
フレームワーク・バージョン4からのレスポンスの例3
-
HTTPコード
400 -
コンテンツ・タイプ
application/vnd.oracle.adf.error+json -
ペイロード
{ "title" : "Bad Request", "status" : "400", "o:errorDetails" : [ { "detail" : "URL request parameter invQP cannot be used in this context.", "o:errorCode" : "27520" }, { "detail" : "Attribute EmpName in Emp is required.", "o:errorCode" : "27014", "o:errorPath" : "/parts/0" }, { "detail" : "Value SampleEmpxxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.", "o:errorCode" : "27040", "o:errorPath" : "/parts/1/payload/EmpName" }, { "detail" : "Attribute EmpName in Emp is required.", "o:errorCode" : "27014", "o:errorPath" : "/parts/1" }, { "detail" : "Value SampleEmpxxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.", "o:errorCode" : "27040", "o:errorPath" : "/parts/2/payload/Employees/0/EmpName" }, { "detail" : "Attribute EmpName in AM.Dept_empWorksIn_deptToEmpQA_EmpViewDef is required.", "o:errorCode" : "27014", "o:errorPath" : "/parts/2" }, { "detail" : "Not Found", "o:errorCode" : "11404", "o:errorPath" : "/parts/3" } ] }
ペイロード・レスポンスでの警告メッセージの取得
ADF RESTランタイムでは、リクエストでADF RESTフレームワーク・バージョン6を使用でき、そのリクエストが適切なメディア・タイプを使用して実行される場合に、レスポンスで警告の詳細を取得できます。
REST APIフレームワークのバージョン6以降、Webアプリケーションでは、レスポンス・ペイロードで警告レスポンスを取得できます。
例外ペイロードでは、o:errorPaths要素により、リクエスト・オブジェクトでエラーが発生した場所のエラー・パスが提供されますが、この具体的な詳細は、リソースをバッキングするエンティティ・オブジェクトに設定されている検証ルールに依存します。
次のサンプルは、新しい部門アイテムを持つ部門オブジェクトを作成しようとしています。ただし、この例では、部門のDeptNameはDepartmentsエンティティ・オブジェクトの検証メソッドで許可されないと指定されているため、リクエストは失敗します。
フレームワーク・バージョン6を使用して作成したリクエストの例1
-
URL
http://server/demo/rest/12.0/Departments -
HTTPメソッド
POST
-
受入れヘッダー
application/vnd.oracle.adf.resourceitem+json,application/json -
ペイロード
{ "DeptNum" : 50, "DeptName" : "ABC", }
フレームワーク・バージョン6からのレスポンスの例1
-
HTTPコード
201 -
コンテンツ・タイプ
application/json -
ペイロード
... "@context" : { ... } ], "warnings": [ { "detail": "Warning from overridden validateEntity method in DeptImpl : DeptName = ABC or DEF" }, { "detail": "Attribute set with value 50 for DeptNum in Dept failed", "o:errorCode": "27011", "o:errorPath": "/DeptNum" }, { "detail": "Warning from overridden create method in DeptViewDefRowImpl" }, { "detail": "Warning from overridden afterCommit method in DeptViewImpl" } ] } }
次のサンプルは、新しい部門アイテムを持つ部門オブジェクトを作成しようとしています。ただし、この例では、入力した従業員給与がEmpSalaryフィールドに定義された検証ルールで許可される給与を満たしていないため、リクエストは失敗します。
フレームワーク・バージョン6を使用して作成したリクエストの例2
-
URL
http://server/demo/rest/11.1/Departments -
HTTPメソッド
POST
-
受入れヘッダー
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "DeptNum" : 52, "DeptName" : "newDept522", "Employees" : [ { "EmpNum" : 501, "EmpName" : "MILLER "EmpSalary" : "85" } ] }
フレームワーク・バージョン6からのレスポンスの例2
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.error+json -
ペイロード
... "@context" : { ... } ], "warnings": [ { "detail": "Warning from Emp entity expressionValidator : Salary value is < 100.", "o:errorCode": "ExcTooLow", "o:errorPath": "/Employees/10" }, ] } }
高度な操作
ADF RESTランタイムでは、次の高度なユースケースをサポートしています。
-
既存のリソース・アイテムのコンテキストでLOV属性値を取得します。
-
属性を制限するフィルタ処理を使用する部分取得によりリソースを問い合わせます。
-
行検索を使用してリソース・コレクションをフェッチします。
-
リソース・アイテムまたはリソース・コレクションのデータのみを返します。
-
リソース・コレクション内のリソース・アイテムの推定カウントを返します。
-
HTTPメソッドをオーバーライドして、更新を実行します
-
バッチ・リクエストを実行します。
属性のフィルタ処理による問合せ(部分取得)
ADF RESTランタイムでは、GETメソッドを使用した、リソース・コレクションからのフィールド・サブセットの取得をサポートしています。
ネストされた子リソースのペイロード構造は、ADF RESTサービス・クライアントに登録されているADF RESTフレームワーク・バージョンによって異なります。ADF RESTフレームワーク・バージョンの詳細は、「ADF RESTフレームワークのバージョニングに関する必知事項」を参照してください。
次のサンプルは、EmployeesリソースおよびDepartmentsリソースの2つの異なるバージョンに基づいています。リソース11.0を示すURLサンプルは、ADF RESTフレームワーク・バージョン1および2でサポートされるレスポンス・ペイロード構造を表しています。一方、リソース11.1を示すURLサンプルは、ADF RESTフレームワーク・バージョン3 (以降)でサポートされるレスポンス・ペイロード構造を表しています。どちらのフレームワークのシナリオでも、サンプルではDepartmentsリソースの子としてEmployeesリソースをフェッチします。
ノート:
ADF RESTリソースのバッキング・ビュー・オブジェクトで実行されるSQL SELECT文は、ビュー・オブジェクトがどのように作成されたかに基づきます。宣言SQLモードを有効にしてADF Business Componentsデベロッパで作成するビュー・オブジェクトのみが、問合せパラメータfieldsにより命名された属性のリストのみを使用して作成した最適化されたSQL SELECT文をサポートします。非宣言ビュー・オブジェクトで実行されるSELECT文は、ビュー・オブジェクト定義のすべての属性を含みます。実行時の最適化を実現するには、ADF Business Componentsデベロッパで、宣言SQLモードのみを使用してADF RESTリソースに対するビュー・オブジェクトを作成することをお薦めします。
ADF RESTフレームワーク・バージョン3 (以降)
ADF RESTフレームワークのバージョン3から、ADF RESTランタイムは、リソース・アイテムの配列としてではなく、リソース・コレクションとしてレスポンス・ペイロード内にネストされた子リソースを返します。フレームワーク・バージョン3 (以降)で使用可能なこの機能を使用すると、サービス・クライアントでは、初期リクエストでフェッチされないままのアイテム数を特定した後、追加レコードのリクエストを作成できます。子リソースの属性hasMoreおよびcountは、リソース・コレクションからさらにアイテムを返すことができるかどうかを示します。ADF RESTフレームワーク・バージョン3を選択した場合、レスポンス・ペイロードからのページ区切り属性の使用方法の詳細は、「リソース・コレクションのページング」を参照してください。
次のサンプルでは、ADF RESTフレームワーク・バージョン3 (以降)の機能を示します。レスポンス・ペイロードはネストされた子リソースをリソース・コレクションとして表し、コレクション・オブジェクトにhasMore属性とcount属性が含まれています。追加のリソース・アイテムについて子リソースを問合せる必要がある場合は、リンクが提供されます。この例では、レスポンス・ペイロードは、hasMore属性がfalseである、つまり部門10または部門20のEmployees子リソースに基づいてフェッチされていないアイテムがないことを示しています。
フレームワーク・バージョン3を使用して作成したリクエスト
-
URL
http://server/demo/rest/11.1/Departments?fields=DepartmentId;Employees:FirstName&onlyData=true -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
フレームワーク・バージョン3を使用して作成したレスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード
{ "items" : [ { "DepartmentId" : 10, "Employees" : { "items" : [ { { "FirstName" : "Jennifer" } } ], "count" : 1, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" }, ] }, { "DepartmentId" : 20, "Employees" : { "items" : [ { { "FirstName" : "Michael" }, { "FirstName" : "Pat" } } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" }, ] }, { ... ], "count" : 25, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments", "name" : "Departments", "kind" : "collection" } ]
ADF RESTフレームワーク・バージョン1またはバージョン2
ADF RESTフレームワークのバージョン1およびバージョン2は、ネストされた子リソースをレスポンス・ペイロード内に展開されたリソース・アイテムの配列として返します。フェッチされるリソース・コレクションが大規模である場合、すべてのアイテムをフェッチするのに複数のリクエストが必要になります。
次のサンプルは、DepartmentsコレクションとEmployeesコレクションのインスタンスの属性値をフェッチします。問合せパラメータfieldsにより、レスポンス・ペイロードには指定された属性のみが含まれるようになります。GETリクエストは、属性値を指定しないURL内のいずれのリソース値も返さない場合があることに注意してください。
最初のリクエスト(URL 1)は、Employeesコレクションのインスタンスの値をフェッチします。問合せパラメータfieldsにより、レスポンス・パラメータには指定した属性(FirstName、LastNameおよびEmail)のみが含まれるようになります。
2番目のリクエスト(URL 2)は、DepartmentsコレクションのインスタンスのDepartmentId値、および各部門の従業員のFirstName値をフェッチします。問合せパラメータonlyDataは、レスポンスをフィルタ処理して、子リンクを非表示にします。
3番目のリクエスト(URL 3)は、DepartmentsコレクションのインスタンスのDepartmentId値、および各部門の従業員のFirstName値および各従業員のJobId履歴をフェッチします。問合せパラメータonlyDataは、レスポンスを再度フィルタ処理して、子リンクを非表示にします。
フレームワーク・バージョン1または2を使用して作成したリクエスト1
-
URL 1
http://server/demo/rest/11.0/Employees/101?fields=FirstName,LastName,Email -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
フレームワーク・バージョン1または2からのレスポンス1
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード1
{ "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.0/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] }
フレームワーク・バージョン1または2を使用して作成したリクエスト2
-
URL 2
http://server/demo/rest/11.0/Departments?fields=DepartmentId;Employees:FirstName&onlyData=true -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
フレームワーク・バージョン1または2からのレスポンス2
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード2
{ "items" : [ { "DepartmentId" : 10, "Employees" : [ { "FirstName" : "Jennifer" } ] }, { "DepartmentId" : 20, "Employees" : [ { "FirstName" : "Michael" }, { "FirstName" : "Pat" } ] }, { "DepartmentId" : 30, "Employees" : [ { "FirstName" : "Den" }, { "FirstName" : "Alexander" }, { "FirstName" : "Shelli" }, { "FirstName" : "Sigal" }, { "FirstName" : "Guy" }, { "FirstName" : "Karen" } ] }, { "DepartmentId" : 40, "Employees" : [ { "FirstName" : "Susan" } ] }, ... ], "count" : 25, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ]
フレームワーク・バージョン1または2を使用して作成したリクエスト3
-
URL 3
http://server/demo/rest/11.0/Departments?fields=DepartmentId;Employees:FirstName;Employees.JobHistory:JobId&onlyData=true -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
フレームワーク・バージョン1または2からのレスポンス3
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourcecollection+json -
ペイロード3
{ "items" : [ { "DepartmentId" : 10, "Employees" : [ { "FirstName" : "Jennifer", "JobHistory" : [ { "JobId" : "AD_ASST" }, { "JobId" : "AC_ACCOUNT" } ] } ] }, { "DepartmentId" : 20, "Employees" : [ { "FirstName" : "Michael", "JobHistory" : [ { "JobId" : "MK_REP" } ] }, { "FirstName" : "Pat", "JobHistory" : [ { "JobId" : "AD_ASST" }, { "JobId" : "AC_ACCOUNT" } ] } ] }, { "DepartmentId" : 30, "Employees" : [ { "FirstName" : "Den", "JobHistory" : [ { "JobId" : "ST_CLERK" } ] }, { "FirstName" : "Alexander", "JobHistory" : [ { "JobId" : "AD_ASST" }, { "JobId" : "AC_ACCOUNT" } ] }, { "FirstName" : "Shelli", "JobHistory" : [ { "JobId" : "AD_ASST" }, { "JobId" : "AC_ACCOUNT" } ] ] ... ], "count" : 25, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
行検索によるリソース・コレクションのフィルタ処理
ADF RESTランタイムでは、GETメソッドを使用してリソース・コレクションをフェッチする行検索の適用をサポートしています。ADF RESTリソース開発者は、行検索と呼ばれるシード済フィルタを定義します。ADF RESTランタイムでは、これらのフィルタにパラメータを渡すこと、およびシード済フィルタを使用してコレクションを減らす(つまりフィルタ処理する)ことをサポートしています。
行検索によるフィルタ処理は、1つ以上の行検索パラメータ値を指定するファインダ問合せ文字列を使用して実行されます。行検索問合せ文字列パラメータが含まれるファインダの形式は次のとおりです。
finder=<rowfinderName>;<attr1>=<value1>,<attr2>=<value2>,...
例: finder=DeptByName;Dname=ACCOUNTING
リソース・コレクションの記述は、行検索の形状を説明します。行検索を使用するには:
-
リソースの記述を実行し、コレクション要素内の
finders属性を検索します。name属性は、行検索定義名を識別します。また、attributesの下の行検索パラメータの名前も検索します。 -
問合せパラメータ
finderを含むGETを実行し、行検索名およびパラメータを渡します。
たとえば、Departmentsリソースの記述は次を返します。
"collection" : {
"rangeSize" : 25,
"finders" : [ {
"name" : "EmpByEmailFinder",
"title" : "EmployeesByEmailVC",
"attributes" : [ {
"name" : "Email",
"type" : "string",
"updatable" : true,
"required" : "Optional",
"queryable" : false
} ]
次のサンプルは、Email属性値NSMITHが渡される行検索EmpByEmailFinderで指定されたDepartmentsコレクションをフェッチします。
リクエスト
-
URL
http://server/demo/rest/11.1/Employees?finder=EmpByNameFinder;Email=NSMITH -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "items" : [ { "EmployeeId" : 101, "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 2000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.1/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } ], "count" : 1, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees", "name" : "Employees", "kind" : "collection" } ] }
ペイロードのリソース・データのみを返す
ADF RESTランタイムでは、リソース・コレクションまたはリソース・アイテムのGETメソッドを使用した、リソース・アイテムのデータのみの取得をサポートしています。
次のサンプルは、Employeesコレクション属性の値をフェッチします。問合せパラメータonlyDataにより、表現がフィルタ処理され、レスポンス・ペイロードにデータのみが含まれ、リンクが含まれないようになります。
リクエスト
-
URL
http://server/demo/rest/11.1/Employees?onlyData=true -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "items" : [ { "EmployeeId" : 101, "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 2000 }, { "EmployeeId" : 102, "FirstName" : "Lex", "LastName" : "De Haan", "Email" : "LDEHAAN", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 3000 }, { "EmployeeId" : 103, "FirstName" : "Alexander", "LastName" : "Hunold", "Email" : "AHUNOLD", "JobId" : "IT_PROG", "DepartmentId" : 60, "Salary" : 4000 }, { "EmployeeId" : 104, "FirstName" : "Bruce", "LastName" : "Ernst", "Email" : "BERNST", "JobId" : "IT_PROG", "DepartmentId" : 60, "Salary" : 5000 }, { "EmployeeId" : 105, "FirstName" : "David", "LastName" : "Austin", "Email" : "DAUSTIN", "JobId" : "IT_PROG", "DepartmentId" : 60, "Salary" : 6000 } ], "count" : 5, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees", "name" : "Employees", "kind" : "collection" } ] }
リソース・アイテムの推定カウントを返す
ADF RESTランタイムでは、リソース・コレクション内の推定アイテム数の取得をサポートしています。
次のサンプルは、合計レコードを推定し、Employeeコレクションの最初の2つのアイテムを問い合せます。問合せパラメータtotalResultsにより、totalResults属性のみがレスポンス・ペイロードに含まれるようになります。
リクエスト
-
URL
http://server/demo/rest/11.1/Employees?totalResults=true&limit=2 -
HTTPメソッド
GET
-
コンテンツ・タイプ
なし
-
ペイロード
なし
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "items" : [ { "EmployeeId" : 101, "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 2000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/NSMITH", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/NSMITH", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.1/Employees/NSMITH/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] }, { "EmployeeId" : 102, "FirstName" : "Lex", "LastName" : "De Haan", "Email" : "LDEHAAN", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 3000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/LDEHAAN", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/LDEHAAN", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.1/Employees/LDEHAAN/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } ], "totalResults" : 5, "count" : 2, "hasMore" : true, "limit" : 2, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees", "name" : "Employees", "kind" : "collection" } ] }
HTTPメソッドのオーバーライドおよび更新の実行
HTTPサーバーまたはクライアントによっては、HTTP仕様の一部のメソッドの公開をサポートしていない場合があります。ADF RESTランタイムでは、一般的なPOSTメソッドを使用して、他のメソッドの操作を実行できます。
次のサンプルは、POSTメソッドを使用して、PATCHメソッドのオーバーライドによりDepartmentsリソース・アイテムを更新します。
リクエスト
-
URL
http://server/demo/rest/11.1/Departments/15 -
HTTPメソッド
POST
-
X-HTTP-Method-Override
PATCH
-
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "DepartmentName": "UpdatedDept", }
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.resourceitem+json -
ペイロード
{ "DepartmentId" : 15, "DepartmentName" : "UpdatedDept", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/15", "name" : "Departments", "kind" : "item" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.1/Departments/15/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
バッチ・リクエストの実行
ADF RESTランタイムでは、バッチ・リクエストを使用した、単一ラウンドトリップでの複数操作の実行をサポートしています。データは、リクエストの最後にコミットされます。ただし、バッチ・リクエスト内の1つのリクエスト部分が失敗した場合は、すべての変更がロールバックされ、エラー・レスポンスが返されます。
バッチ・リクエストは、作成、更新、削除、アップサートおよび取得リクエストの組合せで構成できます。パス・パラメータとペイロードは、リクエストを直接呼び出す場合に使用するものと同じにする必要があります。getメソッドは、バッチ・リクエスト内の同じURLパラメータを個別のHTTPリクエストとしてサポートします。
次のサンプルは、4つの部分で操作を実行するバッチ処理が成功したことを示しています: 1)従業員101の更新、2)従業員102の更新、3)従業員103の更新、4)従業員101の問合せ。
リクエスト
-
URL
http://server/demo/rest/11.1 -
HTTPメソッド
POST
-
コンテンツ・タイプ
application/vnd.oracle.adf.batch+json -
ペイロード
{ "parts": [{ "id": "part1", "path": "/Employees/101", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part2", "path": "/Employees/102", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part3", "path": "/Employees/103", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part4", "path": "/Employees?q=EmployeeId%3D101", "operation": "get" }] }
レスポンス
-
HTTPコード
200 -
コンテンツ・タイプ
application/vnd.oracle.adf.batch+json -
ペイロード
{ "parts": [{ "id": "part1", "path": "http://server/demo/rest/11.1/Employees/101", "operation": "update", "payload": { "EmployeeId": 101, "FirstName": "Neena", "LastName": "Smith", "Email": "NSMITH", "JobId": "AD_VP", "DepartmentId": 90, "Salary": 10000, "links": [{ "rel": "self", "href": "http://server/demo/rest/11.1/Employees/101", "name": "Employees", "kind": "item" }, { "rel": "canonical", "href": "http://server/demo/rest/11.1/Employees/101", "name": "Employees", "kind": "item" }, { "rel": "lov", "href": "http://server/demo/rest/11.1/Employees/101/lov/JobsLOV", "name": "JobsLOV", "kind": "collection" }] } }, { "id": "part2", "path": "http://server/demo/rest/11.1/Employees/102", "operation": "update", "payload": { "EmployeeId": 102, "FirstName": "Lex", "LastName": "De Haan", "Email": "LDEHAAN", "JobId": "AD_VP", "DepartmentId": 90, "Salary": 10000, "links": [{ "rel": "self", "href": "http://server/demo/rest/11.1/Employees/102", "name": "Employees", "kind": "item" }, { "rel": "canonical", "href": "http://server/demo/rest/11.1/Employees/102", "name": "Employees", "kind": "item" }, { "rel": "lov", "href": "http://server/demo/rest/11.1/Employees/102/lov/JobsLOV", "name": "JobsLOV", "kind": "collection" }] } }, { "id": "part3", "path": "http://server/demo/rest/11.1/Employees/103", "operation": "update", "payload": { "EmployeeId": 103, "FirstName": "Alexander", "LastName": "Hunold", "Email": "AHUNOLD", "JobId": "IT_PROG", "DepartmentId": 60, "Salary": 10000, "links": [{ "rel": "self", "href": "http://server/demo/rest/11.1/Employees/103", "name": "Employees", "kind": "item" }, { "rel": "canonical", "href": "http://server/demo/rest/11.1/Employees/103", "name": "Employees", "kind": "item" }, { "rel": "lov", "href": "http://server/demo/rest/11.1/Employees/103/lov/JobsLOV", "name": "JobsLOV", "kind": "collection" }] } }, { "id": "part4", "path": "http://server/demo/rest/11.1/Employees", "operation": "get", "payload": { "EmployeeId": 101, "FirstName": "Neena", "LastName": "Smith", "Email": "NSMITH", "JobId": "AD_VP", "DepartmentId": 90, "Salary": 10000, "links": [{ "rel": "self", "href": "http://server/demo/rest/11.1/Employees/101", "name": "Employees", "kind": "item" }, { "rel": "canonical", "href": "http://server/demo/rest/11.1/Employees/101", "name": "Employees", "kind": "item" }, { "rel": "lov", "href": "http://server/demo/rest/11.1/Employees/101/lov/JobsLOV", "name": "JobsLOV", "kind": "collection" }] } }] }
ADF RESTフレームワーク・リファレンス
ADF RESTフレームワークでは、HTTPメソッド、HTTPヘッダー、リクエストURLパラメータ、メディア・タイプおよびその他の概念をサポートして、リソースに対するREST APIコールの作成を可能にしています。
ADF RESTの記述のlinksオブジェクト構造
linksは、値が常にURLリンクとなるJSONオブジェクトであり、リンク名はそのリンクのrelに応じて定義されます。linksオブジェクトは、各リソース・コレクション、リソース・アイテムおよびリソース自体に対して生成されます。
リソースの記述内のURLリンクは、そのURLのすべての部分を決定する十分な情報がない場合、テンプレート・プレースホルダ値({id})を使用して生成されることに注意してください。たとえば、次の子リンクは、特定のDepartmentリソースの値のプレースホルダを含むURLを提供します。
"item" : {
"links" : [ {
"rel" : "child",
"href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees",
"name" : "Employees",
"kind" : "collection",
"cardinality" : {
"value" : "1 to *",
"sourceAttributes" : "DepartmentId",
"destinationAttributes" : "DepartmentId"
}rel属性の値
rel属性は、現在のリソースとリンクが指すリソースとの間のリンク関係のタイプを定義します。関係は、表22-3に示すいずれかの値で指定できます。
表22-3 ADF RESTリソースの記述でのリンク関係
| リンク関係 | 説明 |
|---|---|
|
|
常にリソース用に生成されます。 |
|
|
常に生成されます。 |
|
|
常にネストされたリソース用に生成されます。 |
|
|
リソースにネストされた子が存在する場合に生成されます。 |
|
|
リソース・アイテムでLOV(値リスト)有効属性用に生成されます。2つのタイプの 最初のタイプはLOVビュー・アクセッサおよびリソース・アイテムの基礎となるLOV有効属性によって、モデル・プロジェクト内で定義されます。2つ目のタイプはLOVアクセッサ上のLOVリソースによってモデル・プロジェクト内で定義され、リソースがリソース・アイテムの基礎となるLOV有効属性に関連付けられます。 |
|
|
BLOB属性とCLOB属性用にデフォルトで生成されます。この関係では、サポートされているペイロード・タイプで表すことができないリソースを指すリンクを示します。この関係の例として、JSONで表すことができないイメージがあります。
|
|
|
フレームワーク・ドメインの外部に存在するリソース用に生成されます。 |
|
|
複数のリソース・バージョン識別子が存在する場合にリソース・バージョンの記述内に生成されます。 |
|
|
複数のリソース・バージョン識別子が存在する場合にリソース・バージョンの記述内に生成されます。 |
|
|
複数のリソース・バージョン識別子が存在する場合にリソース・バージョンの記述内に生成されます。 |
|
|
リソース・バージョンの記述内に生成されます。 |
cardinality属性の値
cardinality属性は、ソース・リソースと宛先リソースとの間のカーディナリティを定義するオプションの属性です。この属性は、rel属性値がchildで、リソース・タイプがvnd.oracle.adf.description+jsonである場合にのみ使用可能です。このカーディナリティ属性には次の属性があります。
-
value: カーディナリティの値。例: "1 to *" -
sourceAttributes: 宛先リソースへのリンクに使用される、ソース・リソース内の属性。 -
destinationAttributes: ソース・リソースへのリンクに使用される、宛先リソース内の属性。
ADF REST APIフレームワーク・バージョン
フレームワーク・バージョンとは、特定のOracle JDeveloperリリースから使用可能なADF RESTフレームワークの特定のバージョンのことを指します。
ADF RESTランタイムでは、ペイロードの処理に作用するフレームワーク・バージョンの指定や、使用するデフォルトのフレームワーク・バージョン(サーバーで構成)の指定を、クライアントが実行できます。リクエストを処理するフレームワーク・バージョンを指定すると、クライアントでは準備が整えばそれらの機能を選択できます。たとえば、rowmatch式(フレームワーク・バージョン2以降で提供)とQuery-by-Example構文(バージョン1のみ)の両方をサポートするには、フレームワーク・バージョン2 (以降)をWebアプリケーションで定義する新しいリリース・バージョン識別子に関連付ける必要があります。たとえば、次のURLサンプルでは、リリース・バージョン11.0の元の機能を保持しながら、バージョン11.1の新機能を公開できます。これは、Webアプリケーションがフレームワーク・バージョン2をリリース・バージョン11.1のデフォルトとして宣言していることを前提としています。あるいは、Webアプリケーションで現在のフレームワーク・バージョンの機能が不要になった場合に、新しいフレームワーク・バージョンを既存のリリース・バージョン識別子に関連付けることができます。したがって、新しいフレームワーク・バージョンを使用するために、リリース・バージョンを増す必要がありません。各フレームワーク・バージョンでサポートされるADF RESTフレームワーク機能の詳細は、「ADF RESTフレームワークのバージョニングに関する必知事項」を参照してください。
リクエストでフレームワーク・バージョンを指定していない場合、/context/<release-version>/で始まるURIに対するすべてのペイロードで、adf-config.xmlファイルで宣言されているデフォルトのフレームワーク・バージョンが想定されます。
ノート:
バージョン1より後の各ADF RESTフレームワーク・バージョンでは、以前のフレームワーク・バージョンではサポートされていない機能が提供されます。そのため、後のフレームワーク・バージョンを選択すると、REST APIを使用するサービス・クライアントに関する後方互換性がない変更がアプリケーションのREST APIに導入される可能性があります。下位互換の問題は、次の表の「非サポート」列を参照してください。
次の表では、各フレームワーク・バージョンに対する変更について説明します。
表22-4 ADF REST APIフレームワーク・バージョン
| REST APIフレームワーク・バージョン | サポート | 非サポート | 例 |
|---|---|---|---|
|
1 - デフォルトのバージョン。他のバージョンが指定されていない場合に、これを使用してWebアプリケーションのリクエストを処理します |
Query-by-Exampleリソース問合せ構文がサポートされます
|
|
|
|
2 - リクエストのバージョンを指定する必要があります。その場合にのみ、REST APIでは拡張式構文を使用したリクエストの処理がサポートされます。 |
REST APIコールでは、より高度な問合せ構文がサポートされます。
|
Query-by-Exampleリソース問合せ構文は互換性がありません。 フレームワーク・バージョン1に依存するWebアプリケーションに後方互換性のない変更が導入されます。 |
|
|
3 - ペイロード構造では、ネストされた子リソースをアイテムの配列(バージョン1および2)でなく、リソース・コレクションとして表すようになっています |
後続のREST APIリクエストでリソース・アイテムがさらに返されるかどうかを判別するためにWebアプリケーションで使用できるペイロード属性によってネストされた子リソースの取得がサポートされます。 フェッチするために複数のリクエストを必要とするネストされた子リソースのページ区切りがサポートされます。
|
フレームワーク・バージョン1または2に依存するWebアプリケーションに後方互換性のない変更が導入されます。 |
「属性のフィルタ処理による問合せ(部分取得)」を参照してください。 エラー・レスポンスについては、「標準エラー・メッセージ・レスポンスの取得」も参照してください。 |
|
4 – リクエストでREST APIフレームワーク・バージョン4を使用でき、そのリクエストが |
例外の詳細ペイロード形式のレスポンスがサポートされ、Webアプリケーションに次の利点をもたらします。
|
例外の詳細には、アプリケーション固有のエラー・コードやリクエスト・ペイロードのエラー・パスなど、一部の詳細が表示される場合とされない場合があります。 |
「例外ペイロード・エラー・レスポンスの取得」を参照してください。 |
|
5 -行コンテキストに依存しないLOVを共有して、レコードを除外できます。複数のリソースでLOVを共有することもできます。 LOVリソースは独自の最上位レベル・リソースによって表され、行コンテキストのLOV URLはペイロードおよび記述で返されなくなります。 |
LOVリソースURLのリソース・パラメータ内にネストされるLOVの依存性を削除します。 リクエスト・パラメータおよびレスポンス・パラメータのサポートが拡張され、現在サポートされている文字列、数値、日付およびブール型以外もサポートされます。 |
LOVリソースURLのネスト・レベル。 |
「行検索のLOVリソースの構成に関する必知事項」を参照してください。 サポートされるJava型には、 |
|
6 -リソース・フィールドとリンクやヘッダーなどのアイテム・コンテキスト情報を区別できます。また、レスポンス・ペイロードのコンテキスト・セクションに、作成/アップサートおよび更新アクションに関する警告も表示されます。 |
バッキング・エンティティ・オブジェクト属性に対して検証規則が有効になっている場合、 |
...
"@context" : {
"key" : "AB8765BCD",
"headers" : {
"ETag" : "ACED..."
...
},
"links": [ {
"rel": "self",
"href":
...
} ]
"warnings": [ {
"detail": "Warning from overridden validateEntity method in DeptImpl : DeptName = ABC"
}, {
"detail": "Attribute set with value 92 for DeptNum in Dept failed",
"o:errorCode": "27011",
"o:errorPath": "/DeptNum"
}, {
"detail": "Warning from overridden afterCommit method in DeptViewImpl"
}, {
"detail": "Warning from overridden afterCommit method in DeptViewImpl"
} ]
}
} |
|
|
7 -で、記述およびリソース・アイテムのペイロード・リンクのセクションから行レベルのLOVリソースの記述を削除するオプションが提供されます。 |
最上位レベルのLOVリソース・リンクの使用をサポートします |
記述およびペイロード内の行コンテキストLOV |
ADF RESTペイロード圧縮のサポート
サーバーとクライアント間で交換されるHTTPペイロードをエンコードできます。この機能は、クライアントがサービス・リクエストでAccept-Encoding: gzipヘッダーまたはContent-Encodingヘッダーを指定した場合に有効になります。
リソースのエンコーディング・サポートを無効化するには、カスタム・プロパティadf.rest.enablecompressionをfalseに設定します。JDeveloperでは、このプロパティはFusion WebアプリケーションのADF構成ファイル(adf-config.xml)で設定されています。
表22-5は、ADF RESTフレームワークでサポートされているコンテンツ・エンコーディング・トークンを示しています。
表22-5 サポートされているコンテンツ・エンコーディング・トークン
| コンテンツ・エンコーディング | 説明 |
|---|---|
|
|
ペイロードを圧縮しません。動作は、エンコーディングが省略されている場合と同じです。 |
|
|
RFC 1952 [25]で説明されているように、ファイル圧縮プログラム |
|
|
FRC 1950 [31]で定義されている |
ADF RESTメディア・タイプ
MIMEタイプまたはコンテンツ・タイプとも呼ばれるメディア・タイプは、クライアントとサーバー間で交換されるペイロードの使用可能なリソース構造を定義します。すべてのADF RESTメディア・タイプはJSONに基づいています。クライアント・アプリケーションでアクセスされるリソースは、applicationタイプとjsonサブタイプに分類されます。
REST APIを起動するサービス・クライアントは、表22-6にリストされているいずれかのメディア・タイプを使用してRESTful Webサービスと対話します。これらのタイプでは、リソースの基礎となるビュー・オブジェクト定義によってメディア・タイプが変わらないことが定義されています。acceptヘッダーの値は、起動のコンテキストに応じて変わることに注意してください。ADF RESTフレームワーク・メディア・タイプのJSONトークン構造へのリンクを次の表に示します。
ノート:
サポートされているメディア・タイプを指定するかわりに、サービス・クライアント・リクエストのacceptヘッダーは、サポートされるすべてのメディア・タイプのスーパーセットがレスポンスで受け入れられる場合にapplication/jsonを指定できます。
表22-6 ADF RESTフレームワークでサポートされるメディア・タイプ
| メディア・タイプ | 起動コンテキスト | 説明 |
|---|---|---|
|
|
GETメソッド |
ADF RESTランタイムで返されるすべてのリソース・コレクションの形式を表します。 すべての属性がフレームワークにより自動的に生成されます。 例については、「リソース・コレクションの記述」を参照してください。 |
|
|
GETメソッド POSTメソッド PATCHメソッド |
ADF RESTランタイムで返されるすべてのリソース・アイテムの形式を表します。POSTまたはPATCHリクエスト・ペイロード内のリソース・アイテムの形式も表します。 属性 例については、「リソース・アイテムの記述」を参照してください。 |
|
|
POSTメソッド |
アクションの実行結果を記述します。 |
|
|
GETメソッド |
リソースおよびその要素を記述します。 例については、「使用可能なすべてのリソースの記述」を参照してください。 |
|
. |
||
|
|
POSTメソッド |
実行される一連の操作を記述します(操作は部分のセットで構成され、各部分はリクエストを表します)。バッチ・リクエストは、単一のトランザクションで実行されます。 例については、「バッチ・リクエストの実行」を参照してください。 |
|
|
GETメソッド |
すべてのバージョンのリソースを取得するリクエストの結果を記述します。 例については、「使用可能なすべてのバージョン・リリース名の取得」を参照してください。 |
|
|
任意 |
エラーが発生したリクエストに対する例外ペイロードのエラー・レスポンスを記述します。このメディア・タイプを使用してエラー・レスポンス・ペイロードで例外の詳細を取得するには、ADF RESTフレームワーク・バージョン4 (以降)を有効にしてリクエストを実行する必要があります。 例については、「例外ペイロード・エラー・レスポンス」を参照してください。 |
ADF RESTデータ型
ADF RESTデータ型は、ADF RESTフレームワークによってADF RESTリソース・アイテムとそれらの基礎となるADFビジネス・コンポーネント・エンティティ・オブジェクト属性との間でマップされます。実行時に、フレームワークは、フェッチされたADF RESTリソース・アイテムのデータ型を記述属性typeとして公開します。
表22-7は、ADF RESTリソースのビュー・オブジェクトの基礎となるエンティティ・オブジェクト属性でサポートされているADFビジネス・コンポーネント・データ型と、ADF RESTフレームワークが定義するADF RESTデータ型との間の関係を示しています。一般に、フレームワークではリソース・アイテムの基礎となる属性のSQLタイプに基づいてADF RESTリソース・アイテムのデータ型を定義しますが、次の2つの例外があります。
-
基礎となる属性がブール型マップとして定義されている場合、ADF RESTタイプは常にブールになります。
-
基礎となる属性のJavaタイプがblobまたはclobである場合、ADF RESTタイプは添付になります。
表22-7 ADF RESTフレームワークでサポートされるデータ型
| ADFの基礎となる属性 | ADF RESTデータ型 |
|---|---|
|
属性が次のいずれかの型マップで構成される場合:
|
boolean |
|
Javaクラス: |
attachment |
Javaクラス: ADF RESTフレームワーク・バージョン5以降サポートされるjava.util.List
|
array |
Javaクラス: ADF RESTフレームワーク・バージョン5以降サポートされるjava.util.Map
|
object |
SQLタイプ: Char |
string |
SQLタイプ: Number |
integer |
SQLタイプ: Number (precision = *、scale > 0)
|
number |
SQLタイプ: Number (precision < 10、scale = 0)
|
integer |
SQLタイプ: Number (precision >= 10、scale = 0)
|
integer |
SQLタイプ: Date
|
Java型が Java型が Java型がそれ以外の場合( RESTサービスでは、 |
ADF REST HTTPコード
ADF RESTフレームワークでは、次の表にリストされているHTTPコードをサポートしています。返される特定のコードは、Webサービスで起動されたHTTPメソッドによって異なります。
表22-8 ADF RESTフレームワークでサポートされているHTTPコード
| HTTPコード | 説明 |
|---|---|
|
|
リクエストが正常に実行され、レスポンスにコンテンツが含まれます。 |
|
|
リソースが正常に作成されました。レスポンスには作成されたリソースが含まれます。 |
|
|
リクエストが正常に実行され、レスポンスにはコンテンツが含まれません。 |
|
|
指定されたETagに応じて、リソースは変更されませんでした。 |
|
|
構文の形式が正しくないため、サーバーがリクエストを理解できませんでした。 |
|
|
リクエストのリソースがセキュリティによって保護されており、認証がまだ提供されていないため、サーバーはリクエストの処理を拒否しています。 |
|
|
リクエストされたリソースが見つかりませんでした。 |
|
|
リクエストによって識別されたリソースは、リクエストで送信されたAcceptヘッダーによって受入れ不可となったコンテンツ特性を含むレスポンス・エンティティを生成することのみが可能です。 |
|
|
サーバー側のリソース状態は指定されたETagと一致しません。 |
|
|
リクエストされたメソッドに対するリクエストのエンティティが、リクエストされたリソースではサポートされていない形式であるため、サーバーはリクエストの処理を拒否しています。 |
|
|
サーバーに予期しない状況が発生し、リクエストを遂行できなくなりました。 |
ADF REST HTTPヘッダー・サポート
ADF RESTフレームワークでは、次の表にリストされているHTTPヘッダーをサポートしています。
表22-9 ADF RESTフレームワークでサポートされているHTTPヘッダー
| HTTPヘッダー名 | 説明 |
|---|---|
|
|
リクエスト/レスポンス・ペイロードのコンテンツ・タイプを指定するために使用します。ADF RESTランタイムでは、「ADF RESTメディア・タイプ」で説明しているように、メディア・タイプを解析(リクエスト/レスポンス)できます。 |
|
|
リクエスト/レスポンス・ペイロードのコンテンツ・エンコーディングを指定するために使用します。ADF RESTランタイムでは、「ADF RESTペイロード圧縮のサポート」で説明しているように、エンコーディングを使用する圧縮リクエストを解析できます。 |
|
|
レスポンス・ペイロードの予期されたコンテンツ・タイプを指定するために使用します。ADF RESTランタイムでは、「ADF RESTメディア・タイプ」で説明しているように、メディア・タイプを解析(リクエスト/レスポンス)できます。 |
|
|
許容されるエンコード・レスポンスのリストを指定するために使用します。ADF RESTフレームワークは、「ADF RESTペイロード圧縮のサポート」で説明しているエンコーディングを使用してレスポンスを生成できます。 |
|
|
実行時にリクエストの処理に使用するADF RESTフレームワークのバージョンを指定する場合に使用します。「ADF RESTフレームワーク・バージョンの使用」で説明されているとおり、バージョン・ヘッダーに渡されたADF RESTフレームワーク・バージョンにより、 |
|
|
新たに作成されたリソースのURIを識別するために使用します。ADF RESTフレームワークには、新しいリソースを作成するPOSTのレスポンスに |
|
|
リクエスト内のリソースの状態を、サーバー上のリソースの状態と比較するために使用します。ADF RESTフレームワークでは、更新識別子属性を使用するように構成されたADFビジネス・コンポーネント・エンティティ・オブジェクトが基礎となるリソースの |
|
|
リクエスト内のリソースの状態が、サーバー上のリソースの最新状態であるかどうかを識別するために使用します。このヘッダーは、条件付きリクエストを実行するためにサポートされています。「データ整合性のチェック」を参照してください。 |
|
|
リクエスト内のリソースの状態が、サーバーでの現在の状態に一致しないかどうかを識別するために使用します。このヘッダーは、条件付きリクエストを実行するためにサポートされています。「データ整合性のチェック」を参照してください。 |
|
|
サーバーでサポートされていないアクションを実行するために使用します。これは、(HTTP仕様で定義されていない)カスタム・ヘッダーであり、HTTPメソッドの名前がその値として含まれます。この値(有効な場合)は、使用されるHTTPメソッドの定義に使用されます。このヘッダーはPOSTリクエストでのみ考慮されます。「HTTPメソッドのオーバーライドおよび更新の実行」を参照してください。 |
|
|
アンチCSRFメカニズムが有効になっている場合、どのリクエストにもこのヘッダーを付ける必要があります。アンチCSRFメカニズムを有効にするには、 |
|
|
フレームワーク・ペイロードをキャッシュ/保存する中間プロキシを回避する場合に使用します。このヘッダーはすべてのHTTPレスポンスに構成されます。デフォルトでは、この値によってキャッシュが無効化され、フレームワークによってレスポンス・ヘッダー( ただし、アプリケーション開発者は、リソース定義を構成することで、デフォルトの動作をオーバーライドできます。この値はリソース・ツリーに設定でき、これに応じてヘッダーが設定されます。現在、 <seconds></MaxAge> (リソース・ツリーに設定されている場合)。次のリソース定義ファイルのサンプルは値の設定方法を示しています。<pageDefinition ...>
<parameters/>
<executables/>
<bindings>
<tree ....>
<ServiceConfiguration>
<CacheControl>
<MaxAge>30</MaxAge>
</CacheControl>
</ServiceConfiguration>
<nodeDefinition ../>
</tree>
</bindings>
</pageDefinition>
リソース定義上で |
|
|
POSTを使用するリクエスト内でUpsert-Mode:trueを使用すると、リソース・アイテムが存在しない場合はリソース・アイテムが作成され、リソース・アイテムが存在する場合はリソース・アイテムが更新されます。Upsert-Mode:falseが指定されたPOSTリクエストは、カスタム・ヘッダーのないPOSTとして動作し、CREATE操作のみを実行します。
|
Prefer |
このヘッダーを使用して、レスポンス・ペイロードの圧縮ビューに含まれるフィールドのみを受信できます。値 |
REST-Pretty-Print |
RESTレスポンスには適切な書式設定があり、その結果、空白が多くなります。gzipを使用すると、圧縮されたレスポンス・コンテンツをトランスポートできます。「ADF RESTペイロード圧縮のサポート」を参照してください。ただし、クライアントで抽出されたコンテンツには、依然として空白が含まれるため、このヘッダーを使用することでクライアントで大幅に処理時間を短縮できます。「ADF RESTレスポンスの形式の制御方法」を参照してください。 |
Metadata-Context |
実行時に使用されるMDSラベルを示すメタデータ・リビジョン。メタデータ・リビジョンは、MDS MARデプロイメントや統合サンドボックスの公開など、メインライン・メタデータを更新するイベントの最後に作成されます。 環境で統合サンドボックスが有効になっている場合、値にサンドボックスのプロパティを使用する必要があり、これが統合サンドボックスIDとして扱われます。Metadata- Contentヘッダーは、ApplSessionFilterがADFContextを初期化する最初のフィルタの場合にのみ適用されます。このヘッダーが存在する場合、ADFSessionOptionsのモードは常に「編集」に設定されます。 リビジョンを指定した場合、ADFSessionOptionsはメタデータ・リビジョンに従って構成されます。 特定のメタデータ・リビジョンのコンテキストでRESTサービスを実行する場合は、次の構文を使用します。これにより、RESTクライアントで変更を使用する準備が整うまで、RESTサービスの実行がアプリケーション内で行われる他のメタデータの変更から隔離されます。 Metadata-Context: revision="<metadata revision ID>" サンドボックスでRESTサービスの変更をテストする場合は、次の構文を使用します。 Metadata-Context: sandbox="<unified sandbox ID>" |
ADF REST HTTPメソッドおよびペイロードのサポート
ADF RESTフレームワークでは、次のHTTPメソッドでの操作をサポートしています。
-
GET -
POST -
PATCH -
DELETE
GETメソッドの操作
ADF RESTフレームワークでは、GETメソッドを使用した、次に示すURIを含む次の操作をサポートしています。
-
リソース・コレクション、リソース・アイテム、またはリソース・コレクションやリソース・アイテムが省略されている場合はリソース・カタログを記述します。
http://server/demo/rest/
{version}/[{resourceCollectionPath}|{resourceItemPath}]/describe -
問合せ文字列パラメータを含む、または含まないリソース・コレクション表現を取得します。
http://server/demo/rest/
{version}/{resourceCollectionPath}[?{queryStringParam}[&{queryStringParam}]] -
問合せ文字列パラメータを含む、または含まないリソース・アイテム表現を取得します。
http://server/demo/rest/
{version}/{resourceItemPath}[?{queryStringParam}[&{queryStringParam}]] -
特定のバージョンのリソース・コレクション、または(バージョン識別子やリソース・コレクションが省略されている場合は)使用可能なすべてのリソースを取得します。
http://server/demo/rest/[
{version}/{resourceCollectionPath}]
リクエスト・パラメータ
-
GETメソッドでは、リソース表現の問合せ、フィルタ処理、ページングおよびソートを実行する問合せ文字列パラメータをサポートしています。サポートされているパラメータを次の表に示します。GETメソッドのすべてのURIパラメータは、表内の他の任意のパラメータと組み合せることができますが、
expandパラメータとfieldパラメータには例外が記載されています。問合せ文字列パラメータはリソース・メディア・タイプでのみ使用できることに注意してください。たとえば、リソースの記述時には使用できません。
ノート:
クライアント・リクエストに使用されるADF RESTフレームワーク・バージョンによって、GETメソッドの結果または問合せ構文が異なる場合があります。次の表に、問合せ文字列パラメータを使用する際にフレームワーク・バージョンに注意することが重要な場合を示します。フレームワーク・バージョンの詳細は、「ADF RESTフレームワークのバージョニングに関する必知事項」を参照してください。
表22-10 リソース・コレクション専用にサポートされているGETメソッド問合せ文字列パラメータ
| GET URIパラメータ | 値 | 説明 |
|---|---|---|
|
ADF RESTフレームワーク・バージョン2以降では、複雑なRowMatch式が |
フレームワーク・バージョン1では、問合せパラメータはWHERE句の中で使用し、セミコロンで区切られたquery by exampleタイプの式が1つ以上含まれます。 形式: 例: フレームワーク2以降では、問合せのサポートが強化されたため、リソースからどの行を取得するかを指定するRowMatch式形式を問合せパラメータで使用できます。フィルタは単一式のような簡素なものから、複数の式を組み合せた複雑なものまで使用でき、複雑なフィルタの場合は たとえば、次の式は結合を使用し、3つのフィールドを使用してしてリソースの問合せを実行しています。 問合せパラメータ値に特殊文字(';'、'、'、'、'='など)が含まれる場合、値(式)を引用符で囲んでリテラル値を定義する必要があります。リテラル値に引用符が含まれる場合、さらに、引用符をフレームワーク・バージョンで定義されているとおりにエスケープする必要があります。
また、バージョン1では、問合せパラメータ値に予約語(
フレームワークバージョン2以降、予約語を含む文字列照合フィルタを区切るために空白文字を使用する必要はなくなりました。 バージョン1では、値に特殊文字と予約語の両方が含まれる場合、値を一重引用符(
RowMatch式形式の例は、「ADF RESTフレームワーク・バージョン2の拡張問合せ構文に関する必知事項」を参照してください。 |
指定された式を使用して、リソース・コレクションの問合せが実行されます。 フレームワーク・バージョン1以降でサポートされる演算子は次のとおりです。
フレームワーク・バージョン2以降でサポートされる演算子には次も含まれます。
フレームワーク・バージョン1で使用できる特殊文字は次のとおりです。
フレームワーク・バージョン2以降で使用できる特殊文字は次のとおりです。
ADF RESTフレームワーク・バージョン1およびバージョン2でサポートされる使用方法の例は、「問合せパラメータによるリソース・コレクションのフィルタ処理」を参照してください。 RowMatch式の例は、「ADF RESTフレームワーク・バージョン2の拡張問合せ構文に関する必知事項」を参照してください。 |
|
|
主キー属性値の定義を含む式。 形式: 例: または: 行検索およびその検索属性に関する情報を含む式。 形式: 例: 検索属性値に「;」、「,」「=」(または同様の文字)などの特殊文字が含まれる場合は、問合せをリテラルとして定義して二重引用符で囲む必要があります。次に例を示します。 検索属性値がリテラル値(二重引用符で囲まれた値)で、値に二重引用符
|
リソース・コレクションは、指定された主キーおよび属性値の定義を使用して問い合せます。 または、指定された行検索および属性の定義を使用して問い合せます。 タイプが 使用可能な検索(主キー検索および行検索)のリストが記述で提供されます。 フレームワーク・バージョン1以降で使用できる特殊文字は次のとおりです。
主キー検索の例については、「主キー値によるリソース・コレクションのフィルタ処理」を参照してください。 行検索の例については、「行検索によるリソース・コレクションのフィルタ処理」を参照してください。 |
|
|
ブール デフォルト: |
例については、「リソース・アイテムの推定カウントを返す」を参照してください。 |
|
|
整数 デフォルト: ADF RESTリソース定義ファイルのイテレータ・バインディング |
このパラメータは、リソース・コレクション内に返されるリソース数を制限します。この制限がリソースの合計結果を超える場合、フレームワークは使用可能なリソースを返します。 例については、「リソース・コレクションのページング」を参照してください。 |
|
|
整数 デフォルト: 0 (最初の位置) |
リソース・コレクションの開始位置の定義に使用されます。offsetがリソース数より大きい場合、リソースは返されません。 例については、「リソース・コレクションのページング」を参照してください。 |
表22-11 リソース・コレクションまたはリソース・アイテム用にサポートされているGETメソッド問合せ文字列パラメータ
| GET URIパラメータ | 値 | 説明 |
|---|---|---|
|
ADF RESTフレームワーク・バージョン3以降から、 詳細は、「実行時に行われる処理: ADF RESTフレームワーク・バージョンの起動」を参照してください。 |
リソース・アイテム属性の単純なカンマ区切りリスト。 形式: 例: 子リソースに対して使用できます。 形式: < 例: アクセッサ・ドット表記法を使用するネストされたリソースに対して使用できます。 形式: < 例: ネストされたリソース内の両方のリソースに対して。 形式: < 例: |
このパラメータは、リソース・アイテム属性をフィルタ処理します。指定した属性のみが返されます。 アクセッサ・ドット表記法( このパラメータは ADF RESTフレームワークのバージョン3 (以降)と比較した、バージョン1または2を使用する例は、「属性のフィルタ処理による問合せ(部分取得)」を参照してください。 |
|
|
ブール デフォルト: |
この表現は、データのみを含める(たとえば、 例については、「ペイロードのリソース・データのみを返す」を参照してください。 |
|
ADF RESTフレームワーク・バージョン3以降から、 詳細は、「実行時に行われる処理: ADF RESTフレームワーク・バージョンの起動」を参照してください。 |
すべての子を表示します。形式: アクセッサのカンマ区切りリストを使用して1つ以上の子リソースを表示します。 形式: < 例: アクセッサ・ドット表記を使用してネストされたリソースを表示します。 形式: < 例: |
このパラメータが指定されている場合は、(リンクではなく)指定された子がリソース・ペイロードに含まれます。
アクセッサ・ドット表記法( ADF RESTフレームワークのバージョン3 (以降)と比較した、バージョン1または2を使用する例は、「ネストされた子リソースのフェッチ」を参照してください。 |
|
|
依存属性のセット。 形式: 例: |
依存性は、レスポンス生成の前に設定され、レスポンス生成の後にロールバックされる属性です。一般に、LOV有効属性のカスケードに適用されるため、属性変更の影響をプレビューするために使用されます。依存属性は、該当するリソース・アイテムで常に設定されます。 子リソース・コレクションがリクエストされた場合、 |
|
|
昇順または降順を指定するソート・フラグが含まれるorder-by属性のカンマ区切りリスト。 形式: 例: デフォルト: リソースの基礎となるビュー・オブジェクト問合せで定義されているORDERBY属性が適用されます。 リソース・コレクションで大/小文字を区別しないソートを実行する場合、属性リストでは、
または
|
リソース・コレクションをその属性に基づいてソートします。 order-by問合せリクエストで 例については、「リソース・コレクションのソート」を参照してください。 |
|
|
例: |
|
表22-12 リソース・カタログの記述用にサポートされているGETメソッド問合せ文字列パラメータ
| GET URIパラメータ | 値 | 説明 |
|---|---|---|
|
|
|
すべての詳細を含めるかどうかに関係なく、リソースの記述を取得する場合に使用します。デフォルトでは、すべてのリソースに関する情報の全セット(ネストされた子リソースを含む)を返す完全な記述を実行して、完全なカタログが取得されます。したがって、完全なカタログ記述には、リソースごとに次の情報セクションが含まれます。 タイトル、属性、コレクション、アイテム、注釈、子およびリンク 注釈はADF RESTリソース開発者がアプリケーション内に定義する必要があり、リソース上に存在しないことがあります。 URLパラメータ レスポンスにメタデータは不要だがセルフ・リンクのみを追加する場合は、記述リクエストに 問合せパラメータ 例については、「最小限のカタログ記述の取得」を参照してください。 |
|
|
(デフォルトは、完全または最小限のいずれのカタログを取得するかによって異なります) |
アプリケーション内の指定に従って、リソース注釈を除外または含める場合に使用します。デフォルトは、
注釈はADF RESTリソース開発者がアプリケーション内に定義する必要があり、リソース上に存在しないことがあります。 このパラメータは、 |
|
|
|
アプリケーション内の宣言に従って、特定の可視性のリソースの説明を取得する場合に使用します。このURLパラメータ値では、パブリック・リソースのみ( 例については、「リソースの可視性の宣言に基づいたカタログ記述の取得」を参照してください。 アプリケーション開発者がリソース定義で可視性を宣言する方法の詳細は、「カタログ記述からリソースを非表示にする方法」を参照してください。 |
|
|
リソース・コレクション名のカンマ区切りリスト。 形式: 例: |
名前付きリソースの説明を取得して、リソースをカタログ・レベルでフィルタ処理する場合に使用します。 |
表22-13 リソース・カタログの記述またはリソース・アイテムの記述用にサポートされているGETメソッド問合せ文字列パラメータ
| GET URIパラメータ | 値 | 説明 |
|---|---|---|
|
|
(デフォルトは、完全または最小限のいずれのカタログを取得するかによって異なります) |
親リソース内にネストされた使用可能なすべての子リソースを除外または含める場合に使用します。デフォルトは、
このパラメータは、 リソース・カタログの記述の例については、「最小限のカタログ記述の取得」を参照してください。
|
ADF RESTデータ型でサポートされる問合せ文字列演算子
次の表は、ADF RESTデータ型および問合せパラメータ文字列で使用できる有効な演算子を示します。演算子BETWEEN、NOT BETWEEN、IN、NOT INおよびワイルドカード文字%は、ADF RESTフレームワーク・バージョン2以降でのみ使用可能です。
表22-14 問合せ(q)パラメータ文字列でサポートされる演算子
| ADF RESTデータ型 | サポートされる演算子 |
|---|---|
|
整数 |
|
|
数値 |
|
|
文字列 |
|
|
日付 |
|
|
時間 |
|
|
日時 ノート: UTCおよびローカルの両方の日時書式がサポートされています。返される値は、VMに対して構成されたタイムゾーンによって決まります。 |
|
|
ブール |
|
サポートされているメディア・タイプ
-
リクエスト
-
なし
-
-
レスポンス
-
application/vnd.oracle.adf.resourcecollection+json: リソース・コレクションを取得する場合。 -
application/vnd.oracle.adf.resourceitem+json: リソース・アイテムを取得する場合。 -
application/vnd.oracle.adf.description+json: リソースを記述する場合。 -
application/vnd.oracle.adf.version+json: 使用可能なすべてのリソース・バージョンを取得する場合。
-
ユースケースのサンプル
ADF RESTフレームワーク・バージョンの概要
POSTメソッドの操作
ADF RESTフレームワークでは、POSTメソッドを使用した、次に示すURIを含む次の操作をサポートしています。
-
新しいリソースを作成します。
http://server/demo/rest/
{version}/{resourceCollectionPath} -
1回のラウンドトリップで、親リソース・アイテムを作成し、ネストされた子リソース・コレクションを作成します。
http://server/demo/rest/
{version}/{resourceCollectionPath} -
Upsert-Modeヘッダーを使用したリソース・アイテムの更新または作成
http://server/demoapp/rest/
{version}/{resourceCollectionPath} -
リソース・コレクションまたはリソース・アイテムに対するアクションを実行します。
http://server/demo/rest/
{version}/{resourceCollectionPath}|{resourceItemPath} -
バッチ・リクエストを実行します。
http://server/demo/rest/
{version}/{resourceCollectionPath}
リクエスト・パラメータ
-
なし
サポートされているメディア・タイプ
-
リクエスト
-
application/vnd.oracle.adf.resourceitem+json: リソースを作成する場合、またはHTTPメソッドをオーバーライドして更新を実行する場合。 -
application/vnd.oracle.adf.resourceitem+json: Upsertを使用してリソース・アイテムを更新または作成する場合。 -
application/vnd.oracle.adf.action+json: アクションを実行する場合。 -
application/vnd.oracle.adf.batch+json: バッチ・リクエストを実行する場合。
-
-
レスポンス
-
application/vnd.oracle.adf.resourceitem+json: アクションを実行する場合、またはリソースを作成する場合。 -
application/vnd.oracle.adf.resourceitem+json: Upsertを使用してリソース・アイテムを更新または作成する場合。 -
application/vnd.oracle.adf.actionresult+json: オブジェクトを返すアクションを実行する場合。 -
application/vnd.oracle.adf.batch+json: バッチ・リクエストを実行する場合。
-
ユースケースのサンプル
PATCHメソッドの操作
ADF RESTフレームワークでは、PATCHメソッドを使用した、次に示すURIを含む次の操作をサポートしています。
-
リソース・アイテムの更新。
http://server/demo/rest/
{version}/{resourceItemPath}
リクエスト・パラメータ
-
なし
サポートされているメディア・タイプ
-
リクエスト
-
application/vnd.oracle.adf.resourceitem+json: 更新されるリソース・アイテム。
-
-
レスポンス
-
application/vnd.oracle.adf.resourceitem+json: 更新されたリソース・アイテム。
-
ユースケースのサンプル