Oracle® Fusion Middleware Oracle Application Development FrameworkによるFusion Webアプリケーションの開発 12c (12.2.1.2.0) E82918-03 |
|
![]() 前 |
![]() 次 |
この章の内容は次のとおりです。
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モデル・プロジェクトで作業するADFビジネス・コンポーネント開発者は、ADF RESTリソースを公開し、Fusion Webアプリケーションに提供できます。
クライアントとサーバーによるリソース情報の交換をサポートするADF RESTフレームワークの固有のランタイム機能には、次のものがあります。
RESTリソースとの対話は、リソース、アクション実行、およびアクション実行の結果に対して、個別のJSONベース・メディア・タイプ構造によってサポートされています。
カスタム・ヘッダーを渡して、リクエストの処理に使用するADF RESTランタイム・フレームワークのバージョンを指定します。バージョン・ヘッダーにより、サービス・クライアントではRESTアプリケーションによって定義されたデフォルトのバージョン宣言をオーバーライドできます。JDeveloperリリース12.2.1.2.0では、バージョン1、2、3が存在します。
GET、POST、PATCH、DELETEなどの標準HTTPリクエスト・メソッドを使用してRESTリクエストと対話します。
クライアントでの制限によりRESTリソースとの対話に標準HTTPメソッドを使用できない場合は、POSTリクエスト・メソッドを使用するX-HTTP-Method-Overrideヘッダーを使用してHTTPメソッドを実行します。
RESTリソース・アイテム(特定の従業員など)やリソース・コレクション(すべての従業員のコレクションなど)の特定は、ADFビジネス・コンポーネント・モデル・プロジェクトで定義されているリソース名に基づくREST準拠のURIパス名によってサポートされます。
RESTリソースの記述(リソース・コレクション属性および使用可能なアクションなど)の取得は、特定のメディア・タイプとdescribeアクションでサポートされています。
正規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が存在します。
URLリソース・パスのLOVアクセッサ・リンクを公開するために、リソースの基礎となるビュー・オブジェクトで値リスト(LOV)属性を定義します。
URLリソース・パスの行検索キー値を使用してリソースを検索するために、行検索を定義します。
HTTPメソッドでリクエスト・ペイロードを使用して起動可能なカスタム・アクションを公開するために、ビュー・クライアント・インタフェースまたはビュー行クライアント・インタフェースでクライアント・メソッドを定義します。
URLリソース・パスの正規のリンクを公開するために、更新可能属性のスーパーセットを使用してアプリケーション・データ・モデルのビュー・インスタンスを定義します。
サーバーのリソースにアクセスするリクエストを行う場合にデータ整合性チェックを有効化するために、リソースの基礎となるエンティティ・オブジェクトで更新識別子属性を構成します。
リソースで公開されているリンクを使用するコンテンツ・ストリーミングをサポートするために、リソースの基礎となるビュー・オブジェクトのBLOB属性またはCLOB属性でカスタム・コンテンツ・タイプを構成します。
リソースへのアクセスを許可する前にユーザーを認証するために、セキュリティを構成します。
RESTful Webサービスを使用する前に、関連するOracle ADF機能を理解しておくと役立つ場合があります。次に、関連するサポート機能へのリンクを示します。
ADFビジネス・コンポーネント、およびADFビジネス・コンポーネント・モデル・プロジェクトの作成の詳細は、「ADFビジネス・コンポーネントのスタート・ガイド」を参照してください。
ADFビジネス・コンポーネント・プロジェクトでのRESTful Webサービスの作成(LOVリンク、行検索、カスタム・メソッド、正規リソース、更新識別子、LOB属性のカスタム・コンテンツ・タイプ、セキュリティの有効化を含む)の詳細は、「アプリケーション・モジュールによるRESTful Webサービスの作成」を参照してください。
ADF RESTデータ・コントロールを使用したユーザー・インタフェースの設計の詳細は、「ADF RESTデータ・コントロールを使用したRESTful Webサービスの使用方法」を参照してください。
この章では、ADF RESTリソースとの対話およびADF RESTリソースの操作の一般的なユースケースについて説明します。すべてのサンプルは、Oracle HRスキーマのDEPARTMENTS表、EMPLOYEES表、JOBHISTORY表およびJOBS表に基づきます。図22-1は、ADFビジネス・コンポーネント・モデル・プロジェクトのこれらの表から生成されるビュー・オブジェクトを示しています。
図22-1 RESTサンプル・プロジェクト - ADFビジネス・コンポーネントのビュー・インスタンス
図22-2に示すように、モデル・プロジェクトおよびそのプロジェクトで定義されたビジネス・コンポーネントには、ADF RESTリソース定義ファイルが含まれます。JDeveloperでは、JDeveloperでのリソースの実行とテストを有効化するためにRESTWebServiceプロジェクトも生成されます。
図22-2 RESTサンプル・アプリケーション - ADFビジネス・コンポーネント
図22-3に示すように、Departments
リソースは、DepartmentsView
ビュー・オブジェクトが基礎となっており、子リソースEmployees
が有効化されています。
図22-3 RESTサンプル・プロジェクト - アプリケーション・モジュールのデータ・モデル
図22-4に示すように、アプリケーションでは3つのバージョン・リリース名を定義します。各ADF RESTリソースは、これらのバージョン識別子のいずれかに割り当てられ、実行時にバージョン・リリース名でアクセスされます。たとえば、複数バージョンのEmployees
リソースが作成された場合、1つのバージョンではサポートされる操作セットが限定されており、もう一方のバージョンではより完全な操作セットが提供されます。
バージョン識別子の順序によりバージョンの順序が決まり、最新バージョンがリストの最上位に表示されることに注意してください。RESTサンプルでは、複数バージョンのEmployees
リソースが存在する場合、リリース名11.2
が最新バージョンとして識別されます。
図22-4 RESTサンプル・プロジェクト - リソース・バージョン
図22-3に示すように、アプリケーション・モジュールは、作成されたリソースを、それらに割り当てられたバージョン・リリース名で編成します。Employees
リソースは、最初にバージョン11.0
で作成され、それ以降のバージョン11.1
および11.2
では新しい必須属性を追加して改訂されます。11.1
で追加されたJobs
リソースでは、LOV有効属性を含むEmployees
リソースに対する作成操作がサポートされています。
図22-5 RESTサンプル・プロジェクト - アプリケーション・モジュール・リソース名
図22-6に示すように、Departments
リソースはDepartmentsView
ビュー・オブジェクトが基礎となっており、子リソースEmployees
とJobHistory
が有効化されています。
子リソースEmployees
の名前はビュー・リンク定義のリンク先ビュー・インスタンス名から導出されることに注意してください。このサンプルでは、リンク先ビュー・インスタンスの名前がEmployeesView1
からEmployees
に変更されています。これにより、デフォルト名EmployeesView1
ではなく名前Employees
をURLリソース・パスで使用して子リソースにアクセスできます。
図22-6 RESTサンプル・プロジェクト - Departmentsリソース
図22-7に示すように、バージョン11.0
のEmployees
ルート・リソースは、EmployeesView
ビュー・オブジェクトが基礎となっています。Employees
はルート・リソースとして作成されているため、子リソース・アクセッサを持ちません。
図22-7 RESTサンプル・プロジェクト - Employeesリソース・バージョン11.0
図22-8に示すように、EmployeesView
ビュー・オブジェクトには、バージョン11.0
のEmployees
ルート・リソースで定義された複数のリソースがあります。HREmployees
リソースとBenefitsEmployees
リソースは、一意のビュー・オブジェクト形成定義が基礎となっており、これらの各リソースによりEmployees
リソースが正規リソースとして定義されます。
図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-9 RESTサンプル・プロジェクト - Employeesリソース・バージョン11.1
図22-10に示すように、バージョン11.2のEmployees
ルート・リソースは、EmpByEmailFinder
行検索を追加して、従業員を電子メール・アドレスで検索できるようにしています。
図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-11 RESTサンプル・プロジェクト - Employees LOV有効属性
図22-12に示すように、EmployeesView
ビュー・オブジェクトは、EmpByEmailFinder
行検索を定義します。行検索では、従業員IDではなく従業員の電子メール・アドレス(Email
属性)を使用して従業員を取得します。
行検索は、デフォルトですべてのバージョンのリソースで公開されることに注意してください。ただし、行検索キー属性が特定のリソース定義で定義されている場合は、その検索名をURLリソース・パスで使用する必要があります。行検索キーがリソース定義で明示的に定義されるまでは、URLリソース・パスでキー属性(このサンプルではEmployeeId
)が必要となります。
図22-12 RESTサンプル・プロジェクト - Employees行検索
図22-13に示すように、EmployeesView
ビュー・オブジェクトでは、Picture
属性でカスタム・コンテンツ・タイプimage/png
を定義します。このコンテンツ・タイプにより、属性のデフォルトのapplication/octet-stream
コンテンツ・タイプ定義が置換され、イメージ・コンテンツのストリーミング時に期待される受入れタイプになります。
図22-13 RESTサンプル・プロジェクト - Employees BLOBコンテンツ・タイプ
図22-14に示すように、EmployeesView
ビュー・オブジェクトでは、Employees
リソースで使用するカスタム・サービス・メソッドmultiplySalary
を定義します。このメソッドはビュー行インタフェースで定義されているため、リソース・コレクション(すべての従業員)ではなくリソース・アイテム(特定の従業員)のレベルでカスタム・アクションとして公開されます。ビュー・オブジェクト・クライアント・インタフェースで定義されているメソッドのみが、リソース・コレクションに対して機能します。
図22-14 RESTサンプル・プロジェクト - Employeesビュー行インタフェース・カスタム・メソッド
図22-15に示すように、Departments
エンティティ・オブジェクトでは、データ整合性チェックを有効化する更新識別子属性RelState
を定義します。属性のエディタでは、更新識別子を構成するために「更新識別子」フィールドと「履歴列」 - 「バージョン番号」フィールドが有効になっています。
図22-15 RESTサンプル・プロジェクト - Departments更新識別子属性
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つ以上の行で構成されるビュー・オブジェクト・インスタンス。 |
|
ビュー・オブジェクト行。特定の部門 |
RESTful Webサービスの記述により、ADF RESTful Webサービスで許可されている形状とアクションを識別できます。RESTリソース定義で定義されている属性、アクションおよびリンクを含むJSONオブジェクトを返します。
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メソッドを使用した、アプリケーション・エンド・ポイントの使用可能なすべてのリソースの記述をサポートしています。
リソース・カタログ内の使用可能なすべてのリソースを調査する手順は次のとおりです。
リソース・カタログの記述を実行し、その記述内でリソースの名前を検索します。children
属性により、ネストされたリソースを識別します。
これらのリソース・オブジェクトを調査して、各リソースの形状を理解します。
attributes
では、使用可能なリソース・コレクション属性のリストを指定します。
collection
では、コレクションの形状を指定し、finder
(行検索の場合)、links
、および使用可能なactions
(メディア・タイプを含む)を指定します。
item
では、コレクションのインスタンスの形状を指定し、item自体ではlinks
と使用可能なactions
を指定します。
children
では、ネストされたリソースを指定します(children自体にはattributes
オブジェクト、collection
オブジェクトおよびitem
オブジェクトが含まれます)。
注意:
include
問合せパラメータをカタログ記述に使用して、特定の可視性のリソースの説明を含めることができます。たとえば、http://server/demo/rest/v1/describe?include=all
を使用できます。all、unlistedまたはpublicをinclude
問合せパラメータの値として使用できます。値は?include=all, unlistedのようなカンマ区切りリストとして使用できます。 可視性の詳細は、「カタログ記述からリソースを非表示にする方法」を参照してください。
たとえば、Departments
リソースと子Employees
リソースを含むサービスの記述は、次のオブジェクトを返します。
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { ... } ], "collection" : { ... } ], "finders" : [ { } ] "links" : [ { } ] "actions" : [ { } ] }, "item" : { "links" : [ { } ] "actions" : [ { } ] }, "children" : { "Departments" ... } ], ... "links" : [ { } ] } }
次のサンプルは、リソース・カタログ内のバージョン11.0
のすべてのリソースを記述します。URLバージョン・パラメータ11.0
は、アプリケーション固有のバージョン識別子に置き換えられる場合があることに注意してください。リソース・バージョンの指定の詳細は、「リソース・バージョンの取得」を参照してください。
リクエスト
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" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "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" : "replace", "method" : "PUT", "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" : "replace", "method" : "PUT", "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" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "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" : "replace", "method" : "PUT", "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メソッドを使用したリソース・コレクションの記述をサポートしています。
リソース・コレクションを調査する手順は次のとおりです。
リソース・コレクションの記述を実行し、その記述内でリソースの名前を検索します。
これらのリソース・オブジェクトを調査して、各リソースの形状を理解します。
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" : "replace", "method" : "PUT", "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" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "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" : "replace", "method" : "PUT", "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" : "replace", "method" : "PUT", "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" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "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" : "replace", "method" : "PUT", "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" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "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" : "replace", "method" : "PUT", "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" } ] } } }
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
属性は、現在のリソースとリンクが指すリソースとの間のリンク関係のタイプを定義します。関係は、表22-2に示すいずれかの値で指定できます。
表22-2 ADF RESTリソースの記述でのリンク関係
リンク関係 | 説明 |
---|---|
|
常にリソース用に生成されます。 |
|
常に生成されます。 |
|
常にネストされたリソース用に生成されます。 |
|
リソースにネストされた子が存在する場合に生成されます。 |
|
リソース・アイテムでLOV(値リスト)有効属性用に生成されます。2つのタイプの 最初のタイプはLOVビュー・アクセッサおよびリソース・アイテムの基礎となるLOV有効属性によって、モデル・プロジェクト内で定義されます。2つ目のタイプはLOVアクセッサ上のLOVリソースによってモデル・プロジェクト内で定義され、リソースがリソース・アイテムの基礎となるLOV有効属性に関連付けられます。 |
|
BLOB属性とCLOB属性用にデフォルトで生成されます。この関係では、サポートされているペイロード・タイプで表すことができないリソースを指すリンクを示します。この関係の例として、JSONで表すことができないイメージがあります。 |
|
フレームワーク・ドメインの外部に存在するリソース用に生成されます。 |
|
複数のリソース・バージョン識別子が存在する場合にリソース・バージョンの記述内に生成されます。 |
|
複数のリソース・バージョン識別子が存在する場合にリソース・バージョンの記述内に生成されます。 |
|
複数のリソース・バージョン識別子が存在する場合にリソース・バージョンの記述内に生成されます。 |
|
リソース・バージョンの記述内に生成されます。 |
cardinality
属性は、ソース・リソースと宛先リソースとの間のカーディナリティを定義するオプションの属性です。この属性は、rel
属性値がchild
で、リソース・タイプがvnd.oracle.adf.description+json
である場合にのみ使用可能です。このカーディナリティ属性には次の属性があります。
value
: カーディナリティの値。例: "1 to *
"
sourceAttributes
: 宛先リソースへのリンクに使用される、ソース・リソース内の属性。
destinationAttributes
: ソース・リソースへのリンクに使用される、宛先リソース内の属性。
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_identfier", "allowedFrameworkVersions" : [ "framework_identfier1", "framework_identfier2", ... ] }, "links" : [ { "rel" : "self", ... }, { "rel" : "canonical", ... }, { "rel" : "predecessor-version", ... }, { "rel" : "describe", ... } ] }, { "version" : "version_identifier_previous", "adf:extension" : { "defaultFrameworkVersion" : "framework_identfier", "allowedFrameworkVersions" : [ "framework_identfier1", "framework_identfier2", ... ] }, "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" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "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" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "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ランタイムでは、次のGETメソッドのユースケースをサポートしています。
リソース・コレクションのフェッチ。
ページ・リソース・コレクションのフェッチ。
主キー・ファインダ・パラメータを使用したリソース・ペイロードのフィルタ処理。
問合せパラメータを使用したリソース・ペイロードのフィルタ処理。
リソース・アイテムのフェッチ。
ネストされた子リソースのフェッチ。
ソートされたリソース・コレクションのフェッチ。
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" : 25 "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
リソース・コレクションのフィールドをフェッチします。
注意:
デフォルトでは、問合せパラメータ操作で使用されるリソースおよびリソース・アイテムの名前は大/小文字が区別されます。大/小文字を区別しないフィルタリングが必要な場合は、adf-config.xml
ファイルのフラグrestV1QueryCaseSensitive
をfalse
に設定できます。フラグのデフォルト値は、大/小文字を区別するフィルタリングを意味するtrue
です。
ADF RESTフレームワーク・バージョン2 (以降)
ADF RESTフレームワークのバージョン2から、サービス・クライアントでは、拡張問合せ構文(RowMatch式とも呼ばれる)を使用してリソースをフェッチできます。バージョン2 (以降)で使用できる問合せ構文の詳細は、「ADF RESTフレームワーク・バージョン2の拡張問合せ構文に関する必知事項」を参照してください。
次のサンプルでは、SA
で始まる名前(SALESなど)の部門またはLocation
がBOSTON
の部門をフェッチします。
フレームワーク・バージョン2を使用して作成したリクエスト
URL
http://server/demo/rest/11.1/Departments?q=DepartmentName like 'SA*' or Location = 'BOSTON'
HTTPメソッド
GET
コンテンツ・タイプ
なし
ペイロード
なし
ADF RESTフレームワーク・バージョン1
ADF RESTフレームワークのバージョン1では、Query-by-Example構文をサポートしています。バージョン1でのみサポートされるこの構文を使用するのにアプリケーション構成の変更は必要ありません。ADF RESTフレームワークのバージョン1で使用可能な問合せ構文の説明は、「GETメソッドの操作」を参照してください。
次のサンプルは、30
未満のDepartmentId
値が割り当てられた部門をフェッチします。
フレームワーク・バージョン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:asc,attribute2
次のサンプル(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ランライムでは、次の作成ユースケースをサポートしています。
コレクションでのリソース・アイテムの作成。
子リソース・アイテムの作成。
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/child/Employees/99999
ペイロード 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" } ] }
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ビジネス・コンポーネント・エンティティ・オブジェクトが基礎となっているリソース・アイテムを、PATCHメソッドを使用して更新する際のデータ整合性チェックをサポートしています。
ETagヘッダーおよび条件付きヘッダー・フィールドを使用してデータ整合性をチェックする手順は次のとおりです。
次に示すように、リソース・アイテムのGETリクエストのヘッダーからETag値を取得します。
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
がレスポンス・ヘッダーで返されます。
リクエスト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ビジネス・コンポーネント・エンティティ・オブジェクトが基礎となっているリソース・アイテムを、GETメソッドを使用して取得する際のデータ整合性チェックをサポートしています。
ETagヘッダーおよび条件付きヘッダー・フィールドを使用してデータ整合性をチェックする手順は次のとおりです。
次に示すように、リソース・アイテムのGETリクエストのヘッダーからETag値を取得します。
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"
} ]
}
リソース・アイテムのGETリクエストを実行し、次の条件付きヘッダー・フィールドを指定してデータ整合性をチェックします。
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
{
"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"
} ]
}
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
リンクを示します。
{ "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
ペイロード
ストリーミングされたコンテンツ
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"
} ]
}
ADF RESTランタイムでは、LOV有効属性の次のユース・ケースがサポートされます。
既存のリソース・アイテムのコンテキストでLOV属性値を取得します。
ユーザーに既存のリソース・アイテムの更新を許可する場合で、そのリソース・アイテムでLOV有効属性が定義されている場合は、このユース・ケースを参照してください。
既存のリソース・アイテムのコンテキストが存在しない場合に、LOV属性値を取得します。
リソース・アイテムを作成する必要がある場合で、そのリソース・アイテムでLOV有効属性が定義される場合は、このユース・ケースを参照してください。
ADF RESTランタイムでは、GETメソッドを使用した、既存のリソース・アイテムでのLOV有効属性値の取得をサポートしています。
LOV有効属性の既存のリソース・アイテムはLOV子リソースをネストし、この子リソースは、含まれるリソース・アイテムのコンテキストに基づいて適切な値リストを取得するために使用できます。
新しいリソース・アイテムを作成し、LOV値を取得する必要がある場合は、リソース・コレクション内にネストされていないLOVリソースにアクセスします。ネストされていないLOVリソースのアクセス方法の詳細は、「リソース・アイテム作成時のLOV有効属性値の取得」を参照してください。
既存のリソース・アイテムでLOV有効属性を使用する手順は次のとおりです。
リソースの記述を実行し、LOVに関する次の詳細を検索します。
リソース属性のlov
記述でchildRef
プロパティを検索し、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
の値の例です)。
リクエスト
URL
http://server/demo/rest/11.0/Employees/101/lov/JobsLOV?onlyData=true&fields=JobTitle
HTTPメソッド
GET
コンテンツ・タイプ
なし
ペイロード
レスポンス
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" } ] }
ADF RESTランタイムでは、リソース・コレクションに存在しない新しいリソース・アイテムを作成する際の、GETメソッドを使用したLOV有効属性値の取得をサポートしています。
すでに存在するリソース・アイテムの場合は、リソース・アイテム・リンクを使用して、そのアイテムに定義されているLOV子リソースにアクセスします。LOV子リソースへのアクセスの詳細は、「既存のリソース・アイテムのLOV有効属性値の取得」を参照してください。
リソース・アイテムの作成時にLOV有効属性を使用する手順は次のとおりです。
リソースの記述を実行し、LOVに関する次の詳細を検索します。
属性のlov
記述でlovResourcePath
プロパティを検索し、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
の値の例です)。
リクエスト
URL
http://server/demo/rest/11.0/Jobs?onlyData=true&fields=JobTitle
HTTPメソッド
GET
コンテンツ・タイプ
なし
ペイロード
レスポンス
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" } ] }
サービス・クライアントでは、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ではリソース・バージョンの記述内にデフォルトのフレームワーク・バージョンを返します。
{ "items" : [ { "version" : "11.2", "isLatest" : true, "adf:extension" : { "defaultFrameworkVersion" : "2", }, "links" : [ ...
各フレームワーク・バージョンでサポートされる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フレームワークのバージョンを把握します。
たとえば、2つのリリース・バージョンを持つサービス・エンドポイントの記述は次のオブジェクトを返します(各リリース・バージョンが特定のADF RESTフレームワーク・バージョンに関連付けられています)。
{ "items" : [ { "version" : "version_identifier_latest", "isLatest" : true, "adf:extension" : { "defaultFrameworkVersion" : "framework_identfier", }, "links" : [ { "rel" : "self", ... }, { "rel" : "canonical", ... }, { "rel" : "predecessor-version", ... }, { "rel" : "describe", ... } ] }, { "version" : "version_identifier_previous", "adf:extension" : { "defaultFrameworkVersion" : "framework_identfier", }, "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" : "2", }, "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", }, "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", }, "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ランタイムでは、次の高度なユースケースをサポートしています。
既存のリソース・アイテムのコンテキストで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ランタイムでは、GETメソッドを使用した、リソース・コレクション内のリソース・アイテムの推定数の取得をサポートしています。
次のサンプルは、Employees
コレクションに関して推定合計結果5
を返します。問合せパラメータ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" } ] }
ADF RESTランライムでは、POSTメソッドを使用した、リソースの基礎となるビュー・オブジェクトのクライアント・インタフェースで定義された1つ以上のカスタム・アクションの実行をサポートしています。
次のサンプルは、Employees
コレクションのインスタンスでカスタム・アクションmultiplySalary
を実行します。この場合、カスタム・アクションは基礎となるビュー・オブジェクトのビュー行クライアント・インタフェースで定義されており、このため、行レベル・インスタンスでのアクションの実行が可能になります。
リクエスト
URL
http://server/demo/rest/11.1/Employees/101
HTTPメソッド
POST
コンテンツ・タイプ
application/vnd.oracle.adf.action+json
ペイロード
{ "name": "multiplySalary", "parameters": [ { "multiplicand": "2" } ] }
レスポンス
HTTPコード
200
コンテンツ・タイプ
application/vnd.oracle.adf.actionresult+json
ペイロード
{ "result" : 4000.0 }
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つのリクエスト部分が失敗した場合は、すべての変更がロールバックされ、エラー・レスポンスが返されます。
次のサンプルは、3つの部分の操作を実行する、成功したバッチ操作を示しています。
リクエスト
URL
http://server/demo/rest
HTTPメソッド
POST
コンテンツ・タイプ
application/vnd.oracle.adf.batch+json
ペイロード
{ "parts": [ { "id": "part1", "path": "/11.1/Employees/101", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part2", "path": "/11.1/Employees/102", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part3", "path": "/11.1/Employees/103", "operation": "update", "payload": { "Salary": 10000 } } ] }
レスポンス
HTTPコード
200
コンテンツ・タイプ
application/vnd.oracle.adf.batch+json
ペイロード
{"parts": { { "id" : "part1", "path" : "/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" : "/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" : "/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" } ] } } ] }
ADF RESTフレームワークでは、HTTPメソッド、HTTPヘッダー、リクエストURLパラメータ、メディア・タイプおよびその他の概念をサポートして、リソースに対するREST APIコールの作成を可能にしています。
サーバーとクライアント間で交換されるHTTPペイロードをエンコードできます。この機能は、クライアントがサービス・リクエストでAccept-Encoding: gzip
ヘッダーまたはContent-Encoding
ヘッダーを指定した場合に有効になります。
リソースのエンコーディング・サポートを無効化するには、カスタム・プロパティadf.rest.enablecompression
をfalse
に設定します。JDeveloperでは、このプロパティはFusion WebアプリケーションのADF構成ファイル(adf-config.xml
)で設定されています。
表22-3は、ADF RESTフレームワークでサポートされているコンテンツ・エンコーディング・トークンを示しています。
表22-3 サポートされているコンテンツ・エンコーディング・トークン
コンテンツ・エンコーディング | 説明 |
---|---|
|
ペイロードを圧縮しません。動作は、エンコーディングが省略されている場合と同じです。 |
|
RFC 1952 [25]で説明されているように、ファイル圧縮プログラム |
|
FRC 1950 [31]で定義されている |
MIMEタイプまたはコンテンツ・タイプとも呼ばれるメディア・タイプは、クライアントとサーバー間で交換されるペイロードの使用可能なリソース構造を定義します。すべてのADF RESTメディア・タイプはJSONに基づいています。クライアント・アプリケーションでアクセスされるリソースは、application
タイプとjson
サブタイプに分類されます。
REST APIを起動するサービス・クライアントは、表22-4にリストされているいずれかのメディア・タイプを使用してRESTful Webサービスと対話します。これらのタイプでは、リソースの基礎となるビュー・オブジェクト定義によってメディア・タイプが変わらないことが定義されています。accept
ヘッダーの値は、起動のコンテキストに応じて変わることに注意してください。ADF RESTフレームワーク・メディア・タイプのJSONトークン構造へのリンクを次の表に示します。
注意:
サポートされているメディア・タイプを指定するかわりに、サービス・クライアント・リクエストのacceptヘッダーは、サポートされるすべてのメディア・タイプのスーパーセットがレスポンスで受け入れられる場合にapplication/json
を指定できます。
表22-4 ADF RESTフレームワークでサポートされるメディア・タイプ
メディア・タイプ | 起動コンテキスト | 説明 |
---|---|---|
|
GETメソッド POSTメソッド |
ADF RESTランタイムで返されるすべてのリソース・コレクションの形式を表します。 すべての属性がフレームワークにより自動的に生成されます。 例については、「リソース・コレクションの記述」を参照してください。 |
|
GETメソッド POSTメソッド DELETEメソッド PATCHメソッド |
ADF RESTランタイムで返されるすべてのリソース・アイテムの形式を表します。 属性 例については、「リソース・アイテムの記述」を参照してください。 |
|
POSTメソッド |
カスタム・アクション実行およびそれらのパラメータを記述します。 公開されたカスタム・アクションは、ビュー・オブジェクト・インタフェースまたはビュー行インタフェースのメソッドが基礎となっています。 例については、「カスタム・アクションの実行」を参照してください。 |
|
POSTメソッド |
アクションの実行結果を記述します。 例については、「カスタム・アクションの実行」を参照してください。 |
|
GETメソッド |
リソースおよびその要素を記述します。 例については、「使用可能なすべてのリソースの記述」を参照してください。 |
|
POSTメソッド |
実行される一連の操作を記述します(操作は部分のセットで構成され、各部分はリクエストを表します)。バッチ・リクエストは、単一のトランザクションで実行されます。 例については、「バッチ・リクエストの実行」を参照してください。 |
|
GETメソッド |
すべてのバージョンのリソースを取得するリクエストの結果を記述します。 例については、「使用可能なすべてのバージョン・リリース名の取得」を参照してください。 |
ADF RESTデータ型は、ADF RESTフレームワークによってADF RESTリソース・アイテムとそれらの基礎となるADFビジネス・コンポーネント・エンティティ・オブジェクト属性との間でマップされます。実行時に、フレームワークは、フェッチされたADF RESTリソース・アイテムのデータ型を記述属性type
として公開します。
表22-5は、ADF RESTリソースのビュー・オブジェクトの基礎となるエンティティ・オブジェクト属性でサポートされているADFビジネス・コンポーネント・データ型と、ADF RESTフレームワークが定義するADF RESTデータ型との間の関係を示しています。一般に、フレームワークではリソース・アイテムの基礎となる属性のSQLタイプに基づいてADF RESTリソース・アイテムのデータ型を定義しますが、次の2つの例外があります。
基礎となる属性がブール型マップとして定義されている場合、ADF RESTタイプは常にブールになります。
基礎となる属性のJavaタイプがblobまたはclobである場合、ADF RESTタイプは添付ファイルになります。
表22-5 ADF RESTフレームワークでサポートされるデータ型
ADFの基礎となる属性 | ADF RESTデータ型 |
---|---|
属性が次のいずれかの型マップで構成される場合:
|
boolean |
Javaクラス:
将来のリリースではSQLタイプがJavaクラスのかわりに使用されることに注意してください。 |
attachment |
SQLタイプ: Char |
string |
SQLタイプ: Number |
桁数が指定されていないため、将来のリリースでこのADF RESTタイプは |
SQLタイプ: Number (precision = *、scale > 0) |
number |
SQLタイプ: Number (precision < 10、scale = 0) |
integer |
SQLタイプ: Number (precision >= 10、scale = 0) |
整数が9桁を超えることはないため、将来のリリースでこのADF RESTタイプは |
SQLタイプ: Date およびTimestamp |
|
ADF RESTフレームワークでは、次の表にリストされているHTTPコードをサポートしています。返される特定のコードは、Webサービスで起動されたHTTPメソッドによって異なります。
表22-6 ADF RESTフレームワークでサポートされているHTTPコード
HTTPコード | 説明 |
---|---|
|
リクエストが正常に実行され、レスポンスにコンテンツが含まれます。 |
|
リソースが正常に作成されました。レスポンスには作成されたリソースが含まれます。 |
|
リクエストが正常に実行され、レスポンスにはコンテンツが含まれません。 |
|
指定されたETagに応じて、リソースは変更されませんでした。 |
|
構文の形式が正しくないため、サーバーがリクエストを理解できませんでした。 |
|
リクエストのリソースがセキュリティによって保護されており、認証がまだ提供されていないため、サーバーはリクエストの処理を拒否しています。 |
|
リクエストされたリソースが見つかりませんでした。 |
|
リクエストによって識別されたリソースは、リクエストで送信されたAcceptヘッダーによって受入れ不可となったコンテンツ特性を含むレスポンス・エンティティを生成することのみが可能です。 |
|
サーバー側のリソース状態は指定されたETagと一致しません。 |
|
リクエストされたメソッドに対するリクエストのエンティティが、リクエストされたリソースではサポートされていない形式であるため、サーバーはリクエストの処理を拒否しています。 |
|
サーバーに予期しない状況が発生し、リクエストを遂行できなくなりました。 |
ADF RESTフレームワークでは、次の表にリストされているHTTPヘッダーをサポートしています。
表22-7 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メソッドのオーバーライドおよび更新の実行」を参照してください。 |
|
フレームワーク・ペイロードをキャッシュ/保存する中間プロキシを回避する場合に使用します。このヘッダーはすべてのHTTPレスポンスに構成されます。有効な値は
より細かく制御する場合は、値をリソース・ツリーで設定すると、それに応じてヘッダーが設定されます。リソース・ツリーで設定する場合、現時点で <pageDefinition ...> <parameters/> <executables/> <bindings> <tree ....> <ServiceConfiguration> <CacheControl> <MaxAge>30</MaxAge> </CacheControl> </ServiceConfiguration> <nodeDefinition ../> </tree> </bindings> </pageDefinition>
このリソース定義値はデフォルト設定および |
ADF RESTフレームワークでは、次のHTTPメソッドでの操作をサポートしています。
GET
POST
PATCH
DELETE
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}
|latest/{resourceCollectionPath
}]
リクエスト・パラメータ
GETメソッドでは、リソース表現の問合せ、フィルタ処理、ページングおよびソートを実行する問合せ文字列パラメータをサポートしています。サポートされているパラメータを次の表に示します。GETメソッドのすべてのURIパラメータは、表内の他の任意のパラメータと組み合せることができますが、expand
パラメータとfield
パラメータには例外が記載されています。問合せ文字列パラメータはリソース・メディア・タイプでのみ使用できることに注意してください。たとえば、リソースの記述時には使用できません。
表22-8 サポートされているリソース・メディア・タイプのGETメソッド問合せ文字列パラメータ
GET URIパラメータ | リソース・タイプ(アイテム/コレクション) | 値 | 説明 |
---|---|---|---|
ベース・バージョンのADF RESTフレームワーク、バージョン1でのみサポートされます。フレームワーク・バージョン2 (以降)で提供される フレームワーク・バージョンの詳細は、「ADF RESTフレームワークのバージョニングに関する必知事項」を参照してください。 |
リソース・コレクションのみ |
セミコロンで区切られた1つ以上のQuery-by-Exampleタイプの式。 形式: 例: |
指定された式を使用して、リソース・コレクションの問合せが実行されます。 サポートされる演算子:
特殊文字:
ADF RESTフレームワーク・バージョン1でサポートされる使用方法の例は、「問合せパラメータによるリソース・コレクションのフィルタ処理」を参照してください。 |
ADF RESTフレームワーク・バージョン2以降でサポートされます。 この構文では、サービス・クライアントでADF RESTフレームワーク・バージョン2以降を使用する必要があります。 詳細は、「実行時に行われる処理: ADF RESTフレームワーク・バージョンの起動」を参照してください。 |
リソース・コレクションのみ |
問合せのサポートが強化されたため、リソースからどの行を取得するかを指定するRowMatch式形式を問合せパラメータで使用できます。フィルタは単一式のような簡素なものから、複数の式を組み合せた複雑なものまで使用でき、複雑なフィルタの場合は たとえば、次の式は結合を使用し、3つのフィールドを使用してしてリソースの問合せを実行しています。 |
指定された式を使用して、リソース・コレクションの問合せが実行されます。 サポートされる演算子:
特殊文字:
ADF RESTフレームワーク・バージョン2でのRowMatchの使用方法の例は、「問合せパラメータによるリソース・コレクションのフィルタ処理」を参照してください。 RowMatch式のその他の例は、「ADF RESTフレームワーク・バージョン2の拡張問合せ構文に関する必知事項」を参照してください。 |
|
リソース・コレクションのみ |
ファインダおよびそのパラメータに関する情報を含む式。 形式: 例: |
指定されたファインダ/パラメータを使用して、リソース・コレクションの問合せが実行されます。使用可能なファインダのリストが記述で提供されます。 タイプが 例については、「行検索によるリソース・コレクションのフィルタ処理」を参照してください。 |
ADF RESTフレームワーク・バージョン3以降から、 詳細は、「実行時に行われる処理: ADF RESTフレームワーク・バージョンの起動」を参照してください。 |
両方 |
リソース・アイテム属性の単純なカンマ区切りリスト。 形式: 例: 子リソースに対して使用できます。 形式: < 例: アクセッサ・ドット表記法を使用するネストされたリソースに対して使用できます。 形式: < 例: ネストされたリソース内の両方のリソースに対して。 形式: < 例: |
このパラメータは、リソース・アイテム属性をフィルタ処理します。指定した属性のみが返されます。 アクセッサ・ドット表記法( このパラメータは ADF RESTフレームワークのバージョン3 (以降)と比較した、バージョン1または2を使用する例は、「属性のフィルタ処理による問合せ(部分取得)」を参照してください。 |
|
両方 |
ブール デフォルト: |
この表現は、データのみを含める(たとえば、 例については、「ペイロードのリソース・データのみを返す」を参照してください。 |
|
リソース・コレクションのみ |
ブール デフォルト: |
例については、「リソース・アイテムの推定カウントを返す」を参照してください。 |
ADF RESTフレームワーク・バージョン3以降から、 詳細は、「実行時に行われる処理: ADF RESTフレームワーク・バージョンの起動」を参照してください。 |
両方 |
すべての子を表示します。形式: アクセッサのカンマ区切りリストを使用して、複数の子リソースを表示します。 形式: < 例: アクセッサ・ドット表記を使用してネストされたリソースを表示します。 形式: < 例: |
このパラメータが指定されている場合は、(リンクではなく)指定された子がリソース・ペイロードに含まれます。
アクセッサ・ドット表記法( ADF RESTフレームワークのバージョン3 (以降)と比較した、バージョン1または2を使用する例は、「ネストされた子リソースのフェッチ」を参照してください。 |
|
リソース・コレクションのみ |
整数 デフォルト: ADF RESTリソース定義ファイルのイテレータ・バインディング |
このパラメータは、リソース・コレクション内に返されるリソース数を制限します。この制限がリソースの合計結果を超える場合、フレームワークは使用可能なリソースを返します。 例については、「リソース・コレクションのページング」を参照してください。 |
|
リソース・コレクションのみ |
整数 デフォルト: 0 (最初の位置) |
リソース・コレクションの開始位置の定義に使用されます。offsetがリソース数より大きい場合、リソースは返されません。 例については、「リソース・コレクションのページング」を参照してください。 |
|
両方 |
依存属性のセット。 形式: 例: |
依存性は、レスポンス生成の前に設定され、レスポンス生成の後にロールバックされる属性です。一般に、LOV有効属性のカスケードに適用されるため、属性変更の影響をプレビューするために使用されます。依存属性は、該当するリソース・アイテムで常に設定されます。 子リソース・コレクションがリクエストされた場合、 |
|
両方 |
昇順または降順を指定するソート・フラグが含まれるorder-by属性のカンマ区切りリスト。 形式: 例: デフォルト: リソースの基礎となるビュー・オブジェクト問合せで定義されているORDERBY属性が適用されます。 |
リソース・コレクションをその属性に基づいて順序付けします。 例については、「リソース・コレクションのソート」を参照してください。 |
|
両方 |
例: |
|
|
リソース・カタログ記述 |
|
1つ以上の可視性タイプを指定した リソース定義の <pageDefinition ...> <parameters/> <executables/> <bindings> <tree ....> <ServiceConfiguration Visibility="unlisted"/> <nodeDefinition ../> </tree> </bindings> </pageDefinition> |
|
リソース・アイテム記述 |
ブール デフォルト: 例: |
例については、「リソース・アイテムの記述」および「ネストされたリソースの記述」を参照してください。 |
ADF RESTデータ型でサポートされる問合せ文字列演算子
次の表は、ADF RESTデータ型および問合せパラメータ文字列で使用できる有効な演算子を示します。演算子BETWEEN、NOT BETWEEN、IN、NOT INおよびワイルドカード文字%は、ADF RESTフレームワーク・バージョン2以降でのみ使用可能です。
表22-9 問合せ(q)パラメータ文字列でサポートされる演算子
ADF RESTデータ型 | サポートされる演算子 |
整数 |
|
数値 |
|
文字列 |
|
日付 |
|
時間 |
|
日時 |
|
ブール |
|
サポートされているメディア・タイプ
リクエスト
なし
レスポンス
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フレームワーク・バージョンの概要
ADF RESTフレームワークでは、POSTメソッドを使用した、次に示すURIを含む次の操作をサポートしています。
新しいリソースを作成します。
http://server/demo/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.action+json
: アクションを実行する場合。
application/vnd.oracle.adf.batch+json
: バッチ・リクエストを実行する場合。
レスポンス
application/vnd.oracle.adf.resourceitem+json
: アクションを実行する場合、またはリソースを作成する場合。
application/vnd.oracle.adf.actionresult+json
: オブジェクトを返すアクションを実行する場合。
application/vnd.oracle.adf.batch+json
: バッチ・リクエストを実行する場合。
ユースケースのサンプル
ADF RESTフレームワークでは、PATCHメソッドを使用した、次に示すURIを含む次の操作をサポートしています。
リソース・アイテムの更新。
http://server/demo/rest/{version}
/{resourceItemPath
}
リクエスト・パラメータ
なし
サポートされているメディア・タイプ
リクエスト
application/vnd.oracle.adf.resourceitem+json
: 更新されるリソース・アイテム。
レスポンス
application/vnd.oracle.adf.resourceitem+json
: 更新されたリソース・アイテム。
ユースケースのサンプル