Oracle® Fusion Middleware Oracle Application Development FrameworkによるFusion Webアプリケーションの開発 12c (12.2.1) E70030-02 |
|
![]() 前 |
![]() 次 |
この章の内容は次のとおりです。
REpresentational State Transfer (REST)は、WebサービスがそれらのURLによって識別されるリソースとして表示されるステートレス・クライアント/サーバー・アーキテクチャをサポートします。GETやPOSTなどのHTTPリクエスト・メソッドは、HTTP URLによって表現されるリソースに対して実行する必要がある、作成、読取り、更新および削除(CRUD)アクションを記述するために、Webサービス・クライアント・リクエスト・メッセージで開発者が使用できる動詞です。RESTでは、HTTP、URL、URI、XML、HTMLなどの規格の使用やリソース・タイプおよびMIMEタイプを規定しています。そのため、RESTは規格ではなく、Webサービスのアーキテクチャ・スタイルの提案となります。
RESTの設計制約に準拠するWebサービスはRESTfulと呼ばれます。このタイプのWebサービスでは、HTTPクライアントとHTTPサーバーがURLによって識別されるリソース情報を交換できます。リクエストおよびレスポンスには、特定の形式でリソースの表現が含まれ、これにより、実際のリソースの状態が定義されます。
Fusion Webアプリケーションにおいては、RESTful Webサービスによって操作されるADF RESTリソースは、ADFビジネス・コンポーネント・モデル・プロジェクトのデータ・モデルで公開されるビュー・オブジェクト・インスタンスが基礎となっています。ADFモデル・プロジェクトで作業するADFビジネス・コンポーネント開発者は、基礎となるビュー・オブジェクトから公開する属性のセット、使用可能にするアクション(標準CRUD操作、およびビュー・オブジェクト・インタフェースまたはビュー行インタフェースのいずれかで定義されているカスタム・メソッドの両方)、および結果として生成されたリソースを保存するビュー・リンク関係を決定できます。
注意:
ADF RESTリソースとして公開する目的でビュー・オブジェクトを作成する場合、ビュー・オブジェクトの作成・ウィザードで「問合せ」ページのDeclarativeオプションを使用して、宣言SQLモード・オプションが有効なビュー・オブジェクトを作成します。設計時に宣言SQLモードで作成されたビュー・オブジェクトは、ADF RESTフレームワーク実行時最適化をサポートし、リソース・コレクションは、URL問合せパラメータfields
で作成されたクライアント・リクエストを使用して効果的にフィルタ処理されます。
ADFビジネス・コンポーネント開発者による設計時の選択内容は、RESTリソース定義XMLファイルで取得されます。Webサービス・クライアントの開発者は、ADF RESTランタイムで有効化されているREST APIによってこれらのリソース定義と対話できます。これにより、使用するサービス・クライアントはCRUD操作を起動して、RESTリソースおよびADFビジネス・オブジェクトと対話できます。データは、親子関係はそのままで、リソースの基礎となるビュー・オブジェクト・インスタンスによって形成されます。
ADFビジネス・コンポーネント・プロジェクトでの最初のRESTリソースを作成するとき、JDeveloperによって、ADF RESTサーブレットを登録する個別のRESTful Webサービス・プロジェクトも生成されます。図16-1に、JDeveloperによって生成されるweb.xml
ファイルを示します。このプロジェクトを使用してRESTful Webサービスを実行およびデプロイします。
図16-1 RESTful Webサービス・プロジェクトを表示する「アプリケーション」ウィンドウ
ADF RESTリソースのセキュリティは、Fusion Webアプリケーションを保護する方法に類似したRESTful Webサービスで適用されます。JDeveloperで、ADFセキュリティの構成ウィザードを実行して、ADFモデル・プロジェクトにセキュリティを適用します。ウィザードを実行した後、デプロイされたRESTful WebサービスのRESTリソースはデフォルトで保護されているため、このサービスの操作に対してアクセス権を付与することが必要になります。
JDeveloperでセキュリティをテストするには、テスト・ユーザーを作成してこれらのユーザーにリソースへのアクセス権限を付与します。次に、これらのアクセス権を付与するセキュリティ・ポリシーをアプリケーション・レベルからドメイン・レベルのセキュリティ・ポリシー・ストアに移行します。セキュリティ・ポリシー・ストアで、エンタープライズ・ユーザーにアクセス権がプロビジョニングされます。
開発チームはADF RESTリソースを公開し、Fusion Webアプリケーションに提供できます。
クライアントとサーバーによるリソース情報の交換をサポートするADF RESTフレームワークの固有のランタイム機能には、次のものがあります。
RESTリソースとの対話は、リソース、アクション実行、およびアクション実行の結果に対して、個別のJSONベース・メディア・タイプ構造によってサポートされています。
GET、POST、PATCH、DELETEなどの標準HTTPリクエスト・メソッドを使用してRESTリクエストと対話します。
クライアントでの制限によりRESTリソースとの対話に標準HTTPメソッドを使用できない場合は、POSTリクエスト・メソッドを使用するX-HTTP-Method-Overrideヘッダーを使用してHTTPメソッドを実行します。
RESTリソース・アイテム(特定の従業員など)やRESTリソース・コレクション(すべての従業員のコレクションなど)の特定は、ADFビジネス・コンポーネント・モデル・プロジェクトで定義されているリソース名に基づくREST準拠のURIパス名によってサポートされます。
RESTリソース(リソース属性および使用可能なアクションなど)の説明の取得は、特定のメディア・タイプとdescribeアクションによってサポートされます。
正規RESTリソースへのリンクは、更新可能エンティティのスーパーセットを持つリソースが定義されている場合にサポートされます。正規のリンクでは、基礎となるビュー・オブジェクトの代替リンクがサポートされます。
RESTリソースのフィルタ処理は、クライアントが特定のリソースにアクセスするために指定されたURIの問合せ文字列パラメータによりサポートされています。
圧縮および解凍を有効化するために、エンコーディング形式がRESTリソースでサポートされています。
RESTリソースにより公開されるBLOB属性とCLOB属性のコンテンツのストリーミングは、ADF RESTフレームワークでサポートされています。
RESTful Webサービス起動時のデータ整合性チェックの実行は、ADF RESTフレームワークでサポートされています。この機能では、データベースのバージョン履歴を使用して、クライアントがリソース自体の更新に応じてHTTPペイロードを管理できるようにします。
ユーザーに対するRESTリソースへのアクセスの認可は、ADFセキュリティ権限の付与によって有効化されます。
RESTful Webサービスを使用する前に、他のOracle ADF機能を理解しておくと役立つ場合があります。次に、関連するサポート機能へのリンクを示します。
推奨される宣言SQLモードでビュー・オブジェクトを作成し、実行時に効果的にリソース・コレクションのフィルタ処理をサポートする方法の詳細は、「宣言SQLモードでのビュー・オブジェクトの使用」を参照してください。
サービス・クライアントでデータの一貫性チェックがサポートされるようにする場合に、エンティティ・オブジェクトに対して更新識別子属性を有効にする方法の詳細は、「同時更新によるデータの消失を防ぐ方法」を参照してください。
ADF RESTリソースのファインダを公開する場合に、ビュー・オブジェクトで行検索を作成する方法の詳細は、「行検索の使用」を参照してください。
ADF RESTリソースのLOVリンクを公開する場合に、LOVの有効なビュー・オブジェクト属性を作成する方法の詳細は、「ビュー・オブジェクト属性の値リスト(LOV)での作業」を参照してください。
ADF RESTリソースのカスタム・メソッドを公開する場合に、ビュー・オブジェクトのクライアント・インタフェースでカスタム・メソッドを作成する方法の詳細は、「UIクライアントへのカスタム・サービス・メソッドの公開」を参照してください。
ADF RESTリソースのサブタイプ・ビューのビュー行を公開する多相ビュー・オブジェクトの作成の詳細は、「多相ビュー行関連の作業」を参照してください。
REST APIを使用したADF RESTリソースへの実行時アクセスを有効にするADF RESTフレームワークの詳細は、「ADF RESTフレームワークを使用したRESTful Webサービスの使用方法」を参照してください。
ADF RESTデータ・コントロールを使用したユーザー・インタフェースの設計の詳細は、「ADF RESTデータ・コントロールを使用したRESTful Webサービスの使用方法」を参照してください。
アプリケーション・モジュールは、ビュー・オブジェクト・インスタンスおよびカスタム・メソッドとして公開される、一連の関連するビジネス機能としてビジネス・ロジックをカプセル化する、ADFビジネス・コンポーネント・フレームワーク・コンポーネントです。アプリケーション・モジュールのデータ・モデルに出現する1つ以上のビュー・オブジェクト・インスタンスをADF RESTリソースにマップできます。アプリケーション・モジュールの概要エディタを使用して、ADF RESTリソースを作成します。ADFモデル・プロジェクトに追加するRESTリソースは、RESTアーキテクチャ・スタイルに従うWebサービスとして公開される場合があります。
注意:
ADF RESTリソースとして公開する目的でビュー・オブジェクトを作成する場合、ビュー・オブジェクトの作成・ウィザードで「問合せ」ページのDeclarativeオプションを使用して、宣言SQLモード・オプションが有効なビュー・オブジェクトを作成します。設計時に宣言SQLモードで作成されたビュー・オブジェクトは、ADF RESTフレームワーク実行時最適化をサポートし、リソース・コレクションは、URL問合せパラメータfields
で作成されたクライアント・リクエストを使用して効果的にフィルタ処理されます。
ビュー・オブジェクト・インスタンスは、Fusion Webアプリケーションで操作するビジネス・オブジェクトです。ADFアプリケーション・モジュールは、それが定義するデータ・モデルでこれらのビジネス・オブジェクトを公開して、サービス・クライアントが表示および操作できるデータを指定します。ADF RESTリソースは、アプリケーション・モジュールの概要エディタを使用して、ビュー・オブジェクト・インスタンスに対して直接定義します。
ADF RESTリソースの追加は、アプリケーション・モジュールの概要エディタの「Webサービス」ページに表示されるオプションです。図16-2に、AppModule
アプリケーション・モジュールのビュー・オブジェクト・インスタンスに作成されているRESTリソースがエディタでどのように表示されるかを示します。エディタでは、アプリケーション・モジュールのRESTリソースは割り当てられたリリース固有のバージョン名(この例では、11.0
、11.1
および11.2
)ごとに編成されていることに注意してください。
図16-2 アプリケーション・モジュールに定義されているADF RESTリソース
注意:
ADF RESTリソースを作成する場合は、JDeveloperによってリソースのバージョン・リリース名を指定するように求められます。バージョンは、複数のリリース間でADFモデル・プロジェクトに追加するリソースの現在および後続のバージョンの管理に役立つ英数字識別子です。
ビュー・オブジェクト・インスタンスを選択し、RESTリソースに名前を付けてバージョンを選択すると、RESTリソースの概要エディタでリソースが開きます。概要エディタを使用して、ビュー・オブジェクト・アクセッサ、使用可能な操作およびカスタム・メソッドをRESTful Webサービスのペイロード・オブジェクトおよびアクションとして公開することによって、RESTリソース表現を編集します。JDeveloperでは、RESTリソース定義ファイルは、割り当てられたリリース・バージョン名によって編成された、ADFアプリケーション・モジュールのサブパッケージとして保存されます。
RESTリソースのカスタマイズの詳細は、「ADF RESTリソース定義の編集方法」を参照してください。
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、Webサービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールの作成方法」の説明に従い、RESTリソースで公開するビュー・オブジェクト・インスタンスを含むアプリケーション・モジュールのデータ・モデルを作成します。
adf-config.xml
ファイルでリリース・バージョン識別子を作成し、作成するADF RESTリソースを特定のバージョンに関連付けます。「ADF RESTリソースのバージョニング」の説明に従い、ADFモデル・プロジェクトに追加するADF RESTリソースの現在および後続のバージョンの管理に役立つように、各RESTリソースをリリース・バージョンに関連付ける必要があります。
ADF RESTリソースを作成する手順は次のとおりです。
「アプリケーション」ウィンドウで、ADF RESTリソースを作成するビュー・インスタンスを含むアプリケーション・モジュールをダブルクリックします。
概要エディタで、「Webサービス」ナビゲーション・タブをクリックして「REST」タブをクリックし、「RESTサービスのサポートの有効化」追加アイコンをクリックします。
最初のRESTリソースを作成するとき、JDeveloperによって、ADF RESTサーブレットを登録する個別のRESTful Webサービス・プロジェクトも生成されます。
「RESTリソースの作成」ダイアログで、RESTful Webサービスで公開するルート・ビュー・インスタンスを選択します。
ダイアログに、アプリケーション・モジュールのデータ・モデルで定義されたビュー・インスタンスが表示されます。マスター/ディテール階層のルート・ビュー・インスタンスのみ選択できます。
RESTリソース・コレクションの「リソース名」を入力し、ドロップダウン・リストからリリース・バージョンを選択して「OK」をクリックします。
リソース名は、サービス・クライアントがビュー・インスタンスとの対話に使用する識別子です。たとえば、次の図に示すように、DeptView1
ビュー・インスタンスに基づくコレクションに名前を付ける場合、完全なコレクション名を示すために名前にDepartments
を入力できます。ネーミングの詳細は、「ADF RESTリソースのネーミングに関する必知事項」を参照してください。
リリース・バージョンは、JDeveloperでリソースの作成を管理するためにadf-config.xml
ファイル内に作成する必要がある識別子です。「ADF RESTリソースのバージョニング」で説明するように、バージョンは、サービス・クライアントが特定のRESTリソースの操作を起動するために使用するURLの一部となります。
図16-3 ADF RESTリソースのリリース・バージョンへの割当て
RESTリソースの概要エディタで、次のいずれかのタスクを実行することによって、リソースとその構造の編集に進むことができます。
ビュー・リンク・アクセッサで定義された子リソースを追加および削除します。詳細は、「ADF RESTリソース定義の編集方法」を参照してください。
同じ基礎となるビュー・インスタンスで定義されたリソースを追加および削除します。詳細は、「同じビュー・インスタンスに基づくリソースを追加および削除する方法」を参照してください。
属性を追加および削除します。詳細は、「ADF RESTリソースの属性を非表示にしたり公開したりする方法」を参照してください。
HTTPメソッド、正規のリンク、行検索フィルタ、サブタイプ・ビューの慣用名およびカスタム・メソッドで定義された標準操作へのアクセスを変更します。詳細は、「ADF RESTリソース表現およびメソッドのカスタマイズ」を参照してください。
「ファイル」、「すべて保存」の順にクリックして、このリソースの選択を保存します。
「ADFビジネス・コンポーネント・プロジェクトのRESTリソースを作成する場合の処理」で説明するように、JDeveloperでは、概要エディタで行われるRESTリソース選択をリソースのリソース定義ファイルに保存します。
JDeveloperによってRESTリソースが生成され、図16-4に示すように、モデル・プロジェクトで編成された「アプリケーション」ウィンドウで、これらのリソースがバージョン・リリース名ごとに表示されます。
また、JDeveloperによって、ADF RESTサーブレットを登録する個別のRESTful Webサービス・プロジェクト(RESTWebService)も生成されます。図16-4に、JDeveloperによって生成されるweb.xml
ファイルを示します。このプロジェクトを使用してRESTful Webサービスを実行およびデプロイします。
モデル・プロジェクトに含まれているResourceRegistry.rpx
ファイルでは、RESTful Webサービスとして公開されるRESTリソースのリストを指定するために、メタデータ注釈を使用しています。
adf-config.xml
ファイルは、バージョン・リリース名を作成すると更新されます。このファイルは、「アプリケーション」ウィンドウの「アプリケーション・リソース」パネルで、「ディスクリプタ」および「ADF META-INF」ノードの下に表示されます。ADFビジネス・コンポーネントを初めて作成すると、同じフォルダにconnections.xml
ファイルが作成されます。
図16-4 アプリケーション・モジュール・ノードの下に表示されるRESTリソース
ADFモデル・プロジェクトにADF RESTリソース定義を追加すると、アプリケーション・モジュールの概要エディタのRESTセクションに、作成したリソースの名前が表示されます。リスト内のリソース名をクリックすることによって、個別のエディタでRESTリソース定義を開くことができます(図16-2を参照)。
RESTリソースの概要エディタに、リソースの構造を編集するためのオプションが表示されます。RESTful Webサービスの観点から、RESTリソース構造によって実行時にRESTコールによって起動される使用可能なデータが決定されます。
設計時に、リソースの基礎となるビュー・オブジェクト階層から、公開する必要があるリソースのみを選択するようにRESTリソース定義を編集できます。RESTリソースを初めて作成するときには、アプリケーション・モジュールのデータ・モデルによって公開される、リソースの基礎となるビュー・オブジェクトを選択する必要があります。この元のビュー・オブジェクトの選択によりRESTリソースのルート・リソースが定義されます。オプションで、追加の子ビュー・オブジェクトを公開できます(存在する場合)。
たとえば、図16-5に示すRESTリソース・エディタの左側には、リソースDepartments
のデフォルトの構造が表示されています。リソース構造はルート・リソースを表すルート・ノードを持つツリーとして表示されます(この場合はDepartmentsView1
)。ツリーのリーフ・ノードは子リソースを表します。この例では、Departments
リソースは、ルート・リソースDepartmentsView1
および様々な子リソース(Employees
およびJobHistory
など)で構成されています。DepartmentsView1
、Employees
およびJobHistory
のリソースはデータ・モデルのビュー・インスタンスとして関連付けられているため、階層に表示されます。リーフ・ノードの横のチェックボックスを使用して、リソース構造に対して子リソースを追加および削除できます。
図16-5 リソース構造が表示されている概要エディタ
注意:
RESTリソース・エディタの右側に、「構造」ツリーで行うノード選択に対応する使用可能なオプションが表示されます。
表16-1に、リソース構造ツリーのノードの概要を示します。
表16-1 リソース構造ツリーのノード
ノード | 説明 | 編集オプション |
---|---|---|
ルート・リソース・ノード: ![]() |
ルート・リソースの選択の基礎となるビュー・オブジェクト・インスタンスを表します。 |
ルート・リソースの基礎となるビュー・オブジェクト・インスタンスを変更または削除することはできません。 このノードを選択すると、ルート・リソースでオプションを選択できます。これらのオプションの詳細は、「ADF RESTリソース表現およびメソッドのカスタマイズ」を参照してください。 |
子リソース・ノード: ![]() |
ルート・リソースの選択の基礎となるビュー・オブジェクト・インスタンスに対して定義されている、マスター/ディテール関係を定義するためにデータ・モデルで使用されているビュー・リンク・アクセッサを表します。 注意: 子ノードは、ルート・リソースのビュー・オブジェクト・インスタンスがマスター/ディテール関係に含まれていない場合は表示されません。 |
子リソースはデフォルトでは無効です。リソース表現で子リソースを公開するには、チェックボックスを選択します。リソース表現から子リソースを削除するには、チェックボックスの選択を解除します。 子リソース・ノードを選択すると、子リソースでオプションを選択できます。これらのオプションの詳細は、「ADF RESTリソース表現およびメソッドのカスタマイズ」を参照してください。 |
始める前に:
ADF RESTによって、アプリケーション・モジュールがどのようにサポートされ、Webサービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。
ADF RESTリソース構造を編集する手順は次のとおりです。
アプリケーション・モジュールのデータ・モデルで1つ以上の階層のマスター/ディテール関係を指定する場合は、ADF RESTリソースで子リソースを公開できます。データ・モデルの各マスター/ディテール関係に対して、ADFビジネス・コンポーネント・モデル・プロジェクトでは、関連する親と子のビュー・オブジェクトを指定するビュー・リンク・アクセッサを定義する必要があり、これにより、親、つまりマスター・ビュー・オブジェクト・インスタンス内に、子、つまりディテール・ビュー・オブジェクト・インスタンスをネストします。
実行時に、ネストされたビュー・インスタンスを公開するRESTリソースでは、1回のラウンドトリップで、マスターおよびディテールのコレクションを戻すことをサポートします。このため、マスター/ディテール・データの操作が必要なサービス・クライアントについては、設計時に子リソースを公開することが役立ちます。
JDeveloperのRESTリソースの概要エディタでは、マスター/ディテール関係が、ルート・リソースのリーフ・ノードとして子リソースが表示される、リソース構造ツリーとして表示されます。たとえば、図16-6は、概要エディタでの、次のネストされたリソース構造を持つDepartments
リソースを示しています。
DepartmentsView1
は、マスター・ビュー・インスタンスとして、ルート・リソースの基礎となります。
Employees
はDepartmentsView1
の下にネストされたディテール・ビュー・インスタンスであり、ツリー・ノードのチェックボックスが選択され、Departments
リソースで子リソースが公開されていることを示します。
JobHistory
は、EmployeesView
の下にネストされた別のディテール・ビュー・インスタンスであり、ツリー・ノードのチェックボックスが選択され、Departments
リソースで子リソースが公開されていることを示します。
デフォルトでは、選択された基礎となるビュー・インスタンスに基づき、JDeveloperによってRESTリソースが作成されますが、子リソースは含められません。リソース構造ツリーで、デフォルトでは、子リソースは選択されていない状態で表示され、これらのリソースが公開されていないことを示します。このチェックボックスを選択または選択解除することによって、子リソースを公開したり非表示にしたりすることができます。
図16-6 概要エディタで有効な子リソース
注意:
子リソースはデフォルトでは公開されないため、リソースでこれらを公開するには、概要エディタで選択する必要があります。
始める前に:
ADF RESTがアプリケーション・モジュールをどのようにサポートし、サービス・クライアントのデータ行アクセスやサービス操作の実行をどのように有効化するかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。
ネストされたリソースを公開する手順は次のとおりです。
JDeveloperで、RESTリソースの概要エディタを使用して、同じビュー・インスタンスに対して複数のリソースを定義できます。1つのリソース定義がサービス・クライアントのすべてのユースケースをサポートしていない場合は、リソースを追加できます。リソースを追加した後で、目的のユースケースをサポートするために、操作、属性のリストおよびリソース構造の他のアイテムを変更できます。定義する各リソースは、サービス・クライアントに対して一意のリソース・コレクションを表すため、リソース名がその違いを反映している必要があります。
RESTリソースの概要エディタでは、「リソース」ドロップダウンに、追加するリソースのリストが表示されます。たとえば、図16-7では、同じ基礎となるビュー・オブジェクトEmployeesView
について、概要エディタに、Employees
リソースおよびEmployeesAllAttrs
リソースが表示されています。
図16-7 RESTリソース定義で複数のリソースをサポートするリソース・リスト
注意:
JDeveloperでは、RESTリソースの概要エディタで追加されているリソース定義を削除できます。ただし、空の定義ファイルが「アプリケーション」ウィンドウに表示されます。
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、リソースを追加または削除するRESTリソースを作成します。
概要エディタでリソースを追加および削除する手順は次のとおりです。
「アプリケーション」ウィンドウで、リソースを追加または削除するADF RESTリソースが定義されているリソース定義ファイルをダブルクリックします。
RESTリソースの概要エディタで、「リソース」ドロップダウンからリソースを選択し、「リソースの削除」をクリックして、ビュー・オブジェクトに対してすでに定義されているリソースを削除します。
「リソースの削除」を使用してルート・リソース定義を削除するとリソースは削除されますが、空の定義ファイルが「アプリケーション」ウィンドウに表示されます。
RESTリソースの概要エディタで、ビュー・オブジェクトに対して作成するリソースを追加するには、「リソースの追加」をクリックします。
「ビュー・オブジェクト」ダイアログの「リソースの追加」で、選択したルート・ビュー・インスタンスに対して追加するRESTリソース・コレクションの「リソース名」を入力し、「OK」をクリックします。
RESTリソースの概要エディタで、「リソース」ドロップダウンから新規リソースを選択し、そのリソース定義を編集します。
ビュー・リンク・アクセッサで定義された子リソースを追加および削除します。詳細は、「ADF RESTリソース定義の編集方法」を参照してください。
属性を追加および削除します。詳細は、「ADF RESTリソースの属性を非表示にしたり公開したりする方法」を参照してください。
HTTPメソッド、正規のリンク、行検索フィルタ、サブタイプ・ビューの慣用名およびカスタム・メソッドで定義された標準操作へのアクセスを変更します。詳細は、「ADF RESTリソース表現およびメソッドのカスタマイズ」を参照してください。
ADF RESTリソースの開発中、RESTリソースの概要エディタを使用して、リソース定義ファイルでリソースの名前を変更できます。サービス・クライアントでは、必要なRESTリソース・コレクションとの対話にリソース名を使用するため、サービスを本番環境にデプロイする前に、ADF RESTリソースの名前を確定することが重要です。
デプロイ後にADF RESTリソースの名前を変更する必要がある場合は、「ADF RESTリソースのバージョニング方法」で説明するように、リソースの完全な新規バージョンを作成することで、このことを最適に処理できます。
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、RESTリソースを作成します。
本番デプロイメントの前にリソースの名前を変更する手順は次のとおりです。
RESTリソース名は、サービス・クライアントが、公開されているリソース・コレクションを識別して対話する手段です。通常、RESTリソース名で、利用するクライアントがアクセスするビュー・オブジェクトを識別します。そのため、RESTリソース名は動詞ではなく名詞です。
JDeveloperで、RESTリソースの概要エディタを使用して、同じビュー・インスタンスに対して複数のリソースを定義できます。1つのリソース定義がサービス・クライアントのすべてのユースケースをサポートしていない場合は、リソースを追加できます。リソースを追加した後で、目的のユースケースをサポートするために、必要に応じて、公開されている属性のリストおよびリソース構造の他のアイテムを変更できます。
RESTリソースの概要エディタでは、「属性」タブに、公開されている属性のリストが表示されます。リストは、ルート・リソースの基礎となるビュー・オブジェクトで定義した、RESTサービス形状の選択によって移入されます。たとえば、図16-8は、EmployeesView
ビュー・オブジェクトに対して2つの属性以外をすべて公開するサービス形状定義EmployeesView_ForHR
を示しています。
図16-8 RESTサービス形状定義の選択によって公開される属性
注意:
公開されている属性のリストはRESTリソースの概要エディタで直接変更しません。かわりに、基礎となるビュー・オブジェクトでサービス形状定義を作成し、対象の「REST形状」定義を現在の「リソース」ドロップダウン選択に適用する必要があります。
サービス・クライアントのユースケースをサポートするには、各ビュー・オブジェクトに対して必要な数のサービス形状定義を定義できます。「アプリケーション」ウィンドウでは、ビュー・オブジェクト・ノードの下のpersdefフォルダに、そのビュー・オブジェクトに対して作成したサービス形状定義が表示されます。たとえば、図16-9では、EmployeesViewビュー・オブジェクトの下に2つのサービス形状定義ファイルEmployeesView_forHR.xmlおよびEmployeesView_ForBenefits.xmlが表示されています。
図16-9 「アプリケーション」ウィンドウでのRESTサービス形状定義ファイル
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、RESTリソースを作成します。
RESTサービス形状定義をRESTリソースに適用する手順は次のとおりです。
図16-11に示すように、リソースを作成してバージョン識別子を割り当てると、RESTリソースの概要エディタの右上隅にバージョンが表示され、編集中のバージョンの識別に役立ちます。
図16-11 バージョンが表示されているRESTリソース・エディタ
開発サイクル中は、リソースをバージョニングする必要なく、ADF RESTリソースに変更を加えることができます。ただし、RESTful Webサービスをデプロイした後、ADF RESTリソースにアクセスするサービス・クライアントでそれらのユースケースが満たされることは、リソース・コレクションの安定性に依存します。
時間の経過に伴い、ユースケースが変化したり、RESTリソースの基礎となるビュー・オブジェクトが変化したりすることによって、すでにデプロイされているリソースのリソース構造を変更することが必要になる場合があります。このとき、既存のADF RESTリソースに対する変更に、デプロイされているRESTサービスとの後方互換性がない場合があり、新しいバージョン識別子およびそのバージョンのADF RESTリソースを作成することが必要になる場合があります。RESTリソースをバージョニングするタイミングの詳細は、「ADF RESTリソースのバージョニングに関する必知事項」を参照してください。
JDeveloperでは、ADF META-INFフォルダにあるadf-config.xml
ファイルの概要エディタの「リリース・バージョン」ページでリソースのバージョンを管理できます。ADF RESTリソースの新規バージョンの作成方法の詳細は、「ADF RESTリソースのバージョニング」を参照してください。
BLOBまたはCLOBタイプ属性を公開するリソースには、実行時にストリーミング・メディアとしてアクセスできます。デフォルトでは、ビュー・オブジェクト属性は、一般的なコンテンツ・タイプapplication/octet-stream
を使用してADF RESTランタイムによって処理されます。特定のコンテンツ・タイプをサポートする場合は、LOBタイプ属性のカスタム・プロパティとして特別なプロパティcontentType
を構成できます。たとえば、PNGイメージ・ファイルを使用する場合は、設計時に次のコンテンツ・タイプを構成できます。
カスタム・プロパティ: contentType
値: image/png
図16-12に示すように、カスタム・プロパティcontentType
は、ビュー・オブジェクトの概要エディタでPicture
属性のビュー・オブジェクト定義ファイルに追加されています。
図16-12 LOB属性に対して構成されているカスタム・コンテンツ・タイプ
値リスト(LOV)属性は、そのデータソースを別のビュー・オブジェクトに依存するビュー・オブジェクトの属性です。通常、データソース・ビュー・オブジェクトでは、LOV有効属性に対して使用可能な値の固定リストを指定します。ビュー・オブジェクトでLOV有効属性を明示的に定義すると、ADF RESTランタイムがADF RESTリソースでLOV子リソースとして自動的に公開するLOVビュー・アクセッサが、ADFビジネス・コンポーネントによって定義されます。このため、実行時にリソースでLOV有効属性が検出されると、サービス・クライアントによってLOVビュー・アクセッサが起動され、LOV有効属性のデータソースが取得されて、エンド・ユーザーに選択項目が表示される場合があります。
注意:
デフォルトでは、LOVアクセッサ・リソースはリソースで公開され、リソース概要エディタの構造ツリーには表示されません。LOV有効属性の作成の詳細は、「ビュー・オブジェクト属性の値リスト(LOV)での作業」を参照してください。
ADF RESTリソースの概要エディタを使用して、ADF RESTリソース定義を編集します。リソース構造ツリーで選択することによって、HTTPアクションを有効にし、行検索を公開し、ツリーの各ノードに対する正規のリソース・リンクを有効にできます。
ADFモデル・プロジェクトでRESTリソースに行うカスタマイズは、最終的に、実行時にこれらのリソースと対話するサービス・クライアントの機能に影響します。このため、この項では様々なデザインタイム・カスタマイズについて説明していますが、必要なADF RESTランタイム機能をサポートするサービス・クライアントのユースケースの要件を理解することが重要です。
ADF RESTランタイムの詳細は、「ADF RESTフレームワークを使用したRESTful Webサービスの使用方法」を参照してください。
ADF RESTリソース表現では、実行時のレスポンスで返される属性が、リソースの基礎となるビュー・オブジェクトによって問い合わされた属性に制限されます。そのため、設計時にビュー・オブジェクト問合せを定義する場合は、サービス・クライアントの特定のユースケースをサポートするために必要な属性のみを公開することが重要になります。ただし、サービス・クライアントが部分的なRESTリソース表現から同じデータの完全表現に移動できるようにするために、正規リソースへのリンクを構成できます。
通常、正規リソースは真のソースとみなされるため、特定のデータソースの完全表現を指定します。正規リソースの例は、manager
インスタンスを記述するリソースへのリンクを持つemployees
リソースによって示すことができます。このシナリオ(マネージャ名のみが必要な一般的なユースケース)では、非正規のmanager
リソースに名前属性のみが含まれています。さらに、名前がマネージャの識別には十分でない場合は、非正規リソースがmanager
インスタンスのすべての属性(名前、ID、部門、入社日など)を公開する正規リソースにリンクする場合があります。したがって、正規リソースと非正規リソースは次のような状態で存在します。
非正規リソースと正規リソースは、同じデータソースの異なる表現を公開します。
非正規リソースはサービス・クライアントのユースケースのサポートに必要なデータソースの表現のみを公開するため、部分表現となります。
非正規リソースを定義するときには、その正規の完全表現へのリンクが含められます。
リソースの概要エディタで、リソース構造ツリーの各リソース・ノードに対して、ADFモデル・プロジェクトによって定義されている既存のRESTリソースから正規リソースを選択するか、アプリケーションのconnections.xml
ファイルの既存のURL接続によって定義されている外部リソースを選択できます。
RESTリソースの概要エディタで選択できる内部正規リソースは、次の基準を満たす必要があります。
ADFモデル・プロジェクトでは、既存の部分的な表現リソースの基礎となる、同じデータソースにアクセスするビュー・オブジェクトを定義する必要があります。ビュー・オブジェクトはエンティティ・ベースまたは非エンティティ・ベースとなります。
ビュー・オブジェクトでは、非正規リソースによって問い合わされた使用可能な属性のスーパーセットを問い合わせる必要があります。
スーパーセットの表現ビュー・オブジェクトは、アプリケーション・モジュールのデータ・モデルでビュー・インスタンスとして指定する必要があります。
図16-13に、概要エディタのEmployeesView
ルート・リソース・ノードの選択および「リソース」ドロップダウンの選択HREmployees
を示します(内部正規リソースEmployees
が有効化されています)。この場合、各基礎となるビュー・オブジェクトによって指定されるデータベース表は、HREmployees
とEmployees
リソースで同じになります。この例では、Employees
は正規リソースで、基礎となるビュー・オブジェクトのすべての属性が含まれる一方、HREmployees
リソースは同じビュー・オブジェクトに基づきますが、特定のユースケースのサポートに必要な属性のみを問い合わせます。
図16-13 概要エディタで有効な正規リソース
注意:
リソース(resource_partial)が正規(resource_full)として別のリソースを選択できるのは、resource_fullにresource_partialが公開するすべての属性が含まれている場合のみです。
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。
RESTリソースの正規リンクで内部正規リソースが公開されるようにする場合は、データソース(非正規RESTリソースと同じデータソースである必要があります)から使用可能な属性のスーパーセットを問い合わせるビュー・オブジェクト定義を作成して、データ・モデルでそのビュー・オブジェクトを公開し、内部正規リソースのためのリソースを作成します。リソースの作成の詳細は、「ビュー・オブジェクト・インスタンスからのADF RESTリソースの作成方法」を参照してください。
RESTリソースの正規リンクで外部正規リソースが公開されるようにする場合は、アプリケーション接続ファイル(connections.xml
)でURL接続を作成します(JDeveloperのオンライン・ヘルプのURL接続の作成ダイアログに関するトピックを参照)。
正規リソース・リンクを公開する手順は次のとおりです。
サービス・クライアントがリソースの主キー(ほとんどの場合は数値)を使用してリソースの問合せができないようにする場合は、ビジネス・コンポーネント開発者は、名前によって一意に識別できる値を持つビュー・オブジェクト属性に基づく行検索キーを指定する行検索を作成できます。この例の1つとして、電子メール属性の最初の文字による従業員の検索があります。
行検索がADF RESTリソースで名前が付けられているビュー・オブジェクトで明示的に定義されている場合は、ADF RESTリソースの概要エディタで、リソース・コレクションをフィルタ処理する行検索を有効にするオプションを使用できます。行検索はデフォルトでは有効化されていません。名前による行検索キーを選択し、これをリソース構造の現在のノード選択に適用する必要があります。
JDeveloperのADF RESTリソースの概要エディタでは、「Rowfinderキー」ドロップダウンに使用可能な行検索のリストが表示されます。リストは、リソース構造ツリーにおけるノード選択の基礎となるビュー・オブジェクト定義で定義されている行検索によって移入されます。たとえば、図16-14は、Employees
が行検索EmpByEmailFinder
を含むビュー・インスタンスを定義するノードであるEmpByEmailFinder
行検索キーを示しています。
図16-14 ADF RESTリソースのルートで有効な行検索キー
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。
「アプリケーション・モジュールの作成方法」の説明に従い、RESTリソースで公開するビュー・オブジェクト・インスタンスを含むアプリケーション・モジュールのデータ・モデルを作成します。
「行検索の使用」の説明に従い、RESTリソースで公開するビュー・インスタンスで行検索を作成します。
行検索フィルタを公開する手順は次のとおりです。
実行時、行検索キーが有効化されているADF RESTリソースには、サービス・クライアントで行検索キー属性によってアクセスする必要があります。行検索は、行検索キー属性のみを使用して、行検索が有効なリソースについて、コレクションまたはインスタンスを戻すことをサポートします。このため、エンド・ユーザーに対してデータベースの主キー値の知識を要求することなく、サービス・クライアントがRESTリソースにアクセスできます。たとえば、Employees
リソース・コレクションの特定の従業員を取得する次の2つのGETリクエストを比較します。
行検索なし:
http://localhost:7101/RESTSample_App/rest/11.1/Employees/101
行検索あり:
http://localhost:7101/RESTSample_App/rest/11.1/Employees/NSMITH
行検索キーが定義されていない最初のURLでは、従業員のリソース・アイテムの特定に従業員のIDが必要です。2つ目のURLでは、リソース・パスに行検索キー値(従業員の電子メール・アドレス)を使用します。行検索キーが設計時にリソースで有効化されていると、サービス・クライアントは、ADF RESTランタイムによってリクエスト・ペイロード内に生成されたリンクを使用して、行検索キー値でリソースにアクセスできます。
オプションで、ADF RESTリソースで定義した正規リソースに行検索を適用できます。行検索キーを含む正規リソースが、行検索キーが有効化されているADF RESTリソースで定義されている場合は、両側が同じキー構造によって定義されている必要があります。キー属性は、同じ型で、同じ順序である必要があります。行検索キーを含む正規リソースを作成した後、正規のリンクを含む部分リソースを作成すると、ADF RESTリソースの概要エディタで行検索キー・フィールドが無効になり、部分リソースに行検索キーが自動的に反映されます。正規リソースの詳細は、「ADF RESTリソースでの正規リソースの公開方法」を参照してください。
サブタイプ・ビュー・オブジェクトは、継承階層のベース・ビュー・オブジェクトを拡張するビュー・オブジェクトです。サブタイプ・ビュー・オブジェクトは、ベース・ビュー・オブジェクトから属性のそのリストを継承し、サブタイプに固有の独自の属性を提供します。このようなサブタイプ・ビュー・オブジェクトは多相ビュー・オブジェクトと呼ばれます。実行時、多相ビュー・オブジェクトによって、ベース・ビュー・オブジェクトの属性および定義サブタイプ・ビュー・オブジェクトの属性で構成されるサブタイプ・ビュー行が定義されます。
サブタイプ・ビュー行を問い合わせるには、サブタイプ・ビュー・オブジェクトで特定のタイプを判別する識別子属性を指定する必要があります。たとえば、識別子属性JobId
を含むEmployeesView
ベース・ビュー・オブジェクトは、使用可能なジョブ(経理担当者、営業担当者など)に基づいてサブタイプ・ビュー行をインスタンス化でき、サブタイプ・ビュー行の属性は、指定されたジョブID値によって決定されます。たとえば、ジョブIDがSA_REP
の営業担当者には、サブタイプ・ビュー行属性CommissionPct
がありますが、他のジョブ・タイプのサブタイプ・ビュー行ではこの属性は省略されます。
ノードの基礎となるビュー・オブジェクトによって識別子属性が定義される場合は、RESTリソースの概要エディタで、構造ツリーの各ノードのサブタイプ・ビュー・オブジェクトを公開できます。たとえば、図16-7では、概要エディタでEmployees
リソースとEmployeesView2
リソース・ノードが選択されています。基礎となるビュー・オブジェクトEmployeesView
は、識別子属性JobId
を定義し、サブタイプ・ビュー・オブジェクトSalesEmployeeView
は、サブタイプSA_REP
を定義しています。エディタで、「識別子サブタイプを含める」を有効にし、「識別子名」を指定して識別子属性値を省略することによって、SalesEmployeesView
サブタイプ・ビュー・オブジェクトが公開されます。JobId
識別子属性値を省略することにより、リクエストされた従業員のJobId
値に基づくEmployees
のサービス・クライアント・リクエストで、確実にサブタイプ属性が返されます。
図16-15 RESTリソース定義での識別子属性の定義
注意:
識別子属性は基礎となるビュー・オブジェクトで定義され、サブタイプ・ビュー行をサポートします。サブタイプ・ビュー・オブジェクトは設計時にADF RESTリソースとして公開されません。サブタイプ定義はアプリケーション・モジュールで、ADF RESTランタイムによって指定されます。
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
ビュー・オブジェクトでサブタイプ・ビュー行がどのようにサポートされるかを理解しておくと役立つ場合があります。詳細は、「多相ビュー行関連の作業」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「多相ビュー行を持つビュー・オブジェクトの作成方法」の説明に従って、多相ビュー・オブジェクトを作成します。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、リソースを追加または削除するRESTリソースを作成します。
リソース定義でサブタイプ・ビュー行を公開する手順は次のとおりです。
ADF RESTリソースで公開する標準のデータ処理操作は、リソースの基礎となるビュー・インスタンスのアクションに対応しています。実行時、サービス・クライアントは、RESTful Webサービスでこれらの操作をHTTPアクションとして起動します。
表16-2に、RESTリソースの概要エディタにおいてデフォルトで公開される標準操作をリストします。リソース・ツリーで行った各リソース選択のリストから操作を選択解除することにより、別の操作セットを公開できます。GETメソッドは常にリソースに対して公開されることに注意してください。
表16-2 標準ビュー・インスタンス・データ処理操作
操作選択 | HTTPメソッド名 | 操作の説明 |
---|---|---|
作成 |
POST |
1つのADFビジネス・コンポーネント・ビュー行またはビュー行セットを作成します。 |
更新 |
PATCH |
1つのADFビジネス・コンポーネント・ビュー行の指定されたアイテムを更新します。成功するには、この操作に対してビュー行が存在する必要があります。 |
削除 |
DELETE |
1つのADFビジネス・コンポーネント・ビュー行またはビュー行セットを削除します。 |
なし |
GET |
1つのADFビジネス・コンポーネント・ビュー行またはビュー行セットを読み取ります。この操作は、リソースの作成時にデフォルトで使用できることに注意してください。 |
注意:
ADF RESTリソース・リクエストでHTTP PUTメソッドを実行する機能は推奨されていないことに注意してください。現在のリリースでは、基礎となるビュー・オブジェクトで更新操作が有効になっている場合は、ADF RESTリソースの記述でPUTアクションが引き続き表示されています(操作でPUTおよびPATCHメソッドを有効にします)が、この機能は今後のリリースではサポートされないため、ADF RESTサービス・クライアントで、PUTリクエスト(ビュー行のすべてのアイテムが置き換えられます)を行わないでください。
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。
HTTPアクションを公開する手順は次のとおりです。
すべてのADF RESTリソースでは、サービス・クライアントによる読取り操作がサポートされます。効率的な読取り操作(HTTP GETリクエスト)をサポートするには、ADF RESTリソースの基礎となるビュー・オブジェクト定義で、HTTPリクエスト・ペイロードでのコレクションのページングをサポートするように設定されたアクセス・モードを定義する必要があります。範囲ページングの詳細は、「ビュー・オブジェクトの範囲ページ移動を有効にする方法」を参照してください。
ADF RESTリソースで公開するカスタム・メソッドは、リソースの基礎となるビュー・インスタンスのクライアント・インタフェースによって公開されるカスタム・メソッドに対応しています。実行時、サービス・クライアントは、RESTful WebサービスでHTTP POSTを使用してこれらのメソッドを起動します。
JDeveloperのRESTリソースの概要エディタでは、「カスタム・メソッド」タブにカスタム・メソッドのリストが表示されます。リストは、ルート・リソースの基礎となるビュー・オブジェクト定義で定義されているメソッドによって移入されます。たとえば、図16-16は、EmployeesView1
ビュー・インスタンスのクライアント行インタフェースで公開されているmultipleSalary
メソッドを示しています。
図16-16 RESTリソースのルートで公開されるカスタム・メソッド
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「UIクライアントへのカスタム・サービス・メソッドの公開」の説明に従い、RESTリソースで公開するビュー・オブジェクトのクライアント・インタフェースまたはクライアント行インタフェースでカスタム・メソッドを作成します。
カスタム・メソッドを公開する手順は次のとおりです。
開発サイクル中は、リソースをバージョニングする必要なく、ADF RESTリソースに変更を加えることができます。ただし、RESTful Webサービスをデプロイした後、ADF RESTリソースにアクセスするサービス・クライアントでそれらのユースケースが満たされることは、リソース・コレクションの安定性に依存します。
時間の経過に伴い、ユースケースが変化したり、RESTリソースの基礎となるビュー・オブジェクトが変化したりすることによって、すでにデプロイされているリソースのリソース構造を変更することが必要になる場合があります。このとき、既存のADF RESTリソースに対する変更に、デプロイされているRESTサービスとの後方互換性がない場合があり、新しいバージョン識別子およびそのバージョンのADF RESTリソースを作成することが必要になる場合があります。
adf-config.xml
ファイルの概要エディタを使用して、新しいバージョン識別子を作成し、既存のバージョンのライフサイクル・ステータスを更新します。ライフサイクル・ステータスは、active
、deprecated
またはdesupported
のいずれかになります。サービス・クライアントが、リクエストされたバージョンに存在しないリソースをリクエストすると、ADF RESTランタイムによって、ステータスがactive
またはdeprecated
になっている前のバージョンにフォールバックされます
リリース・バージョン・リスト内のリリース名識別子の順序は重要です。ADF RESTランタイムは、最上位のリリース名を最新バージョンとして認識します。リストの最上位の名前の下に続くリリース名は、バージョンの順序リストを形成します。図16-17に示すように、11.0
は最初のバージョンであるため、リストの一番下に表示される必要があり、後続のバージョンはその上にリストされます。ここでは、
11.2
が最新バージョンです。
図16-17 ADF RESTリソースのバージョン管理
注意:
バージョンの順序リストでリリース識別子の位置を変更するには、概要エディタの「リリース・バージョン」ページで矢印を使用して、識別子をリストの上(より新しいバージョン)または下(以前のバージョン)に移動できます。
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、どのような編集によって、後方互換性のない変更がリソースに発生し、新規バージョンのリソースの作成が必要となるかを理解しておくと役立つ場合があります。詳細は、「ADF RESTリソースのバージョニングに関する必知事項」を参照してください。
また、サービス・クライアントによるリクエストがリソースのバージョン識別子にどのように依存するかについても、理解しておくと役立つ場合があります。詳細は、「実行時に行われる処理: ADF RESTリソースのバージョンの起動」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
ADF RESTのバージョンを管理する手順は次のとおりです。
次に、すでにデプロイされているRESTful Webサービスと後方互換性がないとみなす必要があるADF RESTリソース構造への変更の例を示します。
公開されている属性の名前変更
すでに公開されている属性の削除または非表示
すでに公開されている子リソースの削除
標準操作の無効化またはカスタム・メソッドの削除
LOVビュー・アクセッサの無効化または別のビュー・オブジェクトに対するLOVの変更
特定の状況では、リソースをバージョニングしないで、ADF REST構造を変更できます。次の変更は後方互換性があるとみなされるため、すでにデプロイされているADF RESTリソースの新規バージョンを作成する必要はありません。
属性を必須として定義しない新規属性および基礎となるビュー・オブジェクトの公開
必須として定義された属性を公開する場合は、リソースをバージョニングする必要があることに注意してください。
標準操作の公開または新しいカスタム・メソッドの公開
新しい子リソースの公開
すでに公開されている属性に対するLOVビュー・アクセッサの定義
指定するバージョン識別子は、サービス・クライアントがRESTリソースの操作の起動に使用するURLを形成します。たとえば、次のGETリクエストでは、URLパラメータ11.0
および11.1
を指定して、Departments
リソースの2つの異なるバージョンにアクセスします。
http://localhost:7101/RESTSample_App/rest/11.0/Departments
http://localhost:7101/RESTSample_App/rest/11.1/Departments
adf-config.xml
ファイルの概要エディタを使用して、既存のバージョンのライフサイクル・ステータスを更新する場合は、各バージョンにactive
、deprecated
またはdesupported
のいずれかのタグを付けます。ステータスdeprecated
は実行時の影響はなく、ドキュメントの目的で提供されていますが、ステータスをdesupported
にすると、デプロイされているリソースにアクセスできなくなります。
adf-config.xml
ファイルのリリース・バージョン・リスト内のリリース名識別子の順序は重要です。ADF RESTランタイムは、最上位のリリース名を最新バージョンとして認識します。リストの最上位の名前の下のリリース名は、バージョンの順序リストを形成します。たとえば、次のGETリクエストでは、URLパラメータlatest
を指定して、Departments
リソースの11.1
を取得します。ここで、11.1
は、リリース・バージョン・リストの最上位です。
http://localhost:7101/RESTSample_App/rest/latest/Departments
サービス・クライアントが、リクエストされたバージョンに存在しないリソースをリクエストすると、ADF RESTランタイムによって、ステータスがactive
またはdeprecated
になっている前のバージョンにフォールバックされます。このため、Departments
リソースのバージョン11.0
および11.1
が存在し、11.2が存在しない場合は、バージョン11.2
へのリクエストに対して、次に最新のリソースであるバージョン11.1
が返されます。
RESTリクエストでのアクションの起動に対してユーザー認証が要求されるようにする場合は、ADF RESTリソースに対してセキュリティを有効にできます。ADFセキュリティの構成ウィザードを実行し、ウィザードでWebプロジェクトとしてRESTWebService.jprを選択すると、セキュリティはすべてのFusion Webアプリケーションのように処理され、有効化されます。Webサービス・プロジェクトでADFセキュリティを有効にすることは、デプロイされているサービスにデフォルトではアクセスできず、ユーザーには特定のアクセス権限を付与するセキュリティ権限が必要となることを意味します。
RESTful Webサービスのユーザーに付与できる権限は、次のクラスによって定義されます。
RESTリソースで定義されている標準のアクションに対する認可付与を定義するoracle.adf.share.security.authorization.RestServicePermission
。
表16-3に、ユーザーに付与できるADF REST権限クラスによって定義されているアクションをリストします。
表16-3 ADF RESTリソースのセキュリティ保護されたアクション
許可できるアクション | RESTリソースへの影響 |
---|---|
|
RESTリソースのコレクションおよびインスタンスを記述できるようにします。 |
|
RESTリソースのコレクションまたはインスタンスを返すことができるようにします。 |
|
RESTリソースのコレクションまたはインスタンスを更新できるようにします。 |
|
RESTリソースのコレクションまたはインスタンスを削除する権限。 |
|
RESTリソースのコレクションまたはインスタンスを作成できるようにします。 |
|
この権限で、RESTリソースのカスタム・メソッドを起動できるようにします。このアクションは、個々のメソッドではなく、すべてのカスタム・メソッドへのアクセス権を付与することに注意してください。 |
ADF RESTリソースのアクションを起動するユーザーを認証する一般的なプロセスは、次のとおりです。
RESTリソースに対する必要な標準のアクションを有効にします。
RESTリソースに対する必要なカスタム・メソッドを有効にします。
RESTWebServiceプロジェクトで、ADFセキュリティ・ウィザードを実行します。
RESTリソースのためのリソース権限を作成します。
セキュリティ・ポリシーの概要エディタを使用して、リソースで公開した操作をセキュリティ保護する権限を作成します。JDeveloperによって、リソース・タイプの定義とOPSS権限クラスoracle.adf.share.security.authorization.RestServicePermission
が照合されます(表16-3を参照)。
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「ビュー・オブジェクト・インスタンスからのADF RESTリソースの作成方法」の説明に従い、必要なRESTリソースを作成します。
「ADF RESTリソースで標準のHTTPアクションを公開する方法」の説明に従い、RESTリソースでセキュリティ保護する標準操作を有効にします。
「ADF RESTリソースでカスタム・メソッドを公開する方法」の説明に従い、必要なカスタム・メソッドを作成してADF RESTリソース表現で公開します。
ADFセキュリティの構成ウィザードを実行してセキュリティを適用し、RESTリソース・メソッドがデフォルトで保護されるようにします。ウィザードの「認証タイプ」ページで、ViewControllerを選択するかわりに、「ADFセキュリティの有効化」で説明するように、ADF RESTリソースを定義するADFビジネス・コンポーネント・モデル・プロジェクトを選択します。
ADF RESTリソース権限を作成する手順は次のとおりです。
JDeveloperの統合WebLogic ServerまたはスタンドアロンOracle WebLogic Serverに、RESTful Webサービスをデプロイできます。
図16-19に示すように、RESTWebServiceプロジェクトで選択したデフォルトの「実行」オプションを使用して、JDeveloperの統合WebLogic ServerにRESTful Webサービスをデプロイできます。
図16-19 RESTWebServiceプロジェクトでのデフォルトの「実行」オプションの使用
統合WebLogic Serverにサービスをデプロイすると、「ログ」ウィンドウでターゲットURLをクリックして、JDeveloperのHTTPアナライザ・ツールでサービスにアクセスし、リクエスト(GETまたはPOSTなど)を作成する構文を使用してテストを実行できます。RESTful Webサービスのテストの詳細は、「統合WebLogic Serverを使用したADF RESTリソースのテスト」を参照してください。
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。
オプションで、デフォルト・ドメインの使用に関する項の説明に従い、統合WebLogic Server接続を作成し、デフォルト・ドメインを構成します。接続が作成されていない場合は、JDeveloperにより接続を作成するように要求されます。
オプションで、デプロイされているRESTful Webサービスへのアクセスに使用されるターゲットURLに出現するように、RESTサーブレットのURLパターンおよびコンテキスト・ルートを編集します。URLパターンの編集の詳細は、「サービス・クライアントによって使用されるターゲットURLの変更に関する必知事項」を参照してください。
Webサービスを統合WebLogic Serverにデプロイする手順は次のとおりです。
RESTful WebサービスをスタンドアロンOracle WebLogic Serverにデプロイする前に、ADF RESTリソースのデプロイメント・プロファイルを構成し、ADF RESTアプリケーションEARファイルの依存モジュールとしてRESTWebServiceプロジェクトを宣言する必要があります。このプロジェクトには、サービス・クライアントが確実にRESTリソースにアクセスできるようにするweb.xml
ファイルおよびweblogic.xml
ファイルが含まれています。
JDeveloperで、「EARデプロイメント・プロファイルのプロパティの編集」ダイアログの「アプリケーション・アセンブリ」ページを使用して、モジュールの依存性をアプリケーションに追加します。次に、ADF RESTアプリケーションをデプロイすると、選択したRESTWebServiceプロジェクトの2つのファイルが、デプロイされているEARファイルにWARファイルとしてアセンブルされます。
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。
デプロイメント・プロファイルを構成する手順は次のとおりです。
RESTWebServiceプロジェクトをアプリケーションのEARデプロイメント・プロファイルの依存性として追加します。
「アプリケーション」ウィンドウで、アプリケーションを選択し、メイン・メニューから「アプリケーション」→「アプリケーション・プロパティ」を選択します。
「アプリケーション・プロパティ」ダイアログで、「デプロイメント」を選択してからアプリケーション・モジュール・デプロイメント・プロファイルを選択し、「プロファイルの編集」をクリックします。
「EARデプロイメント・プロファイルのプロパティの編集」ダイアログで、「アプリケーション・アセンブリ」を選択してRESTWebService.jprモジュールを開き、図16-22に示すようにプロジェクトを選択して「OK」をクリックします。
図16-22 RESTWebServiceプロジェクトへのデプロイメントの依存性の追加
スタンドアロンOracle WebLogic ServerにRESTful Webサービスをデプロイできます。
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。
「スタンドアロンOracle WebLogic Serverのデプロイメントに対するADF RESTリソースのデプロイメント・プロファイルの構成方法」の説明に従い、デプロイメント・プロファイルを変更して、依存性としてRESTWebServiceプロジェクトを追加し、Webサービスをデプロイします。
Oracle Metadata Services (MDS)フレームワークによって提供されるカスタマイズ機能がアプリケーションで使用され、かつ形成定義がADF RESTリソースに適用されている場合は、「ADF RESTリソースのデプロイとMDSカスタマイズ・サポートに関する必知事項」の説明に従い、カスタマイズ機能のMARプロファイルを変更する必要があります。
オプションで、デプロイされているRESTful Webサービスへのアクセスに使用されるターゲットURLに出現するように、RESTサーブレットのURLパターンおよびコンテキスト・ルートを編集します。URLパターンの編集の詳細は、「サービス・クライアントによって使用されるターゲットURLの変更に関する必知事項」を参照してください。
スタンドアロンOracle WebLogic ServerにWebサービスをデプロイする手順は次のとおりです。
サービス・クライアントがサービスへのアクセスに使用するURLに出現するように、RESTサーブレットのURLパターンを編集できます。デフォルトでは、サーブレット・マッピングでURLパターンのrest
を使用します。
http://localhost:7101/RESTSample_App-context-root/rest/11.1/Departments
サーブレット・マッピング・パターンを編集するには、「アプリケーション」ウィンドウで、RESTWebServiceプロジェクトを開いてweb.xml
ファイルをダブルクリックし、図16-23に示すように、web.xml
ファイルのエディタでRESTサーブレットのURLパターンを編集します。
図16-23 RESTサーブレット・マッピングのURLパターンの編集
サービスにアクセスするURLに出現するように、コンテキスト・ルートも編集できます。デフォルトでは、コンテキスト・ルートはアプリケーション名に基づいており、必要に応じて短縮できます。コンテキスト・ルートを編集するには、「アプリケーション」ウィンドウで、RESTWebServiceプロジェクトを右クリックして「プロジェクト・プロパティ」を選択し、「プロジェクト・プロパティ」ダイアログで「Java EEアプリケーション」をクリックして、図16-24に示すように「Java EEコンテキスト・ルート」を編集して「OK」をクリックします。
図16-24 RESTWebServiceプロジェクトでのデフォルトのコンテキスト・ルートの編集
モデル・プロジェクトでビュー・オブジェクト形成定義を定義し、アプリケーションでOracle Metadata Services (MDS)フレームワークの機能を使用してエンド・ユーザーのカスタマイズをサポートする場合は、user
ディレクトリに/persdef/
を含むMARプロファイルを作成する必要があります。
ADF REST形成定義で共有するネームスペース・パスがMDSカスタマイズによって定義されるため、このことが必要になります。
<namespace path="/persdef/" metadata-store-usage="reposX"/>
この場合、adf-config.xml
ファイルでは、対応するmetadata-store-usage
要素に対してdeploy-target="true"
を定義する必要があります。
カスタマイズしたメタデータをパッケージ化する方法の詳細は、「カスタマイズしたアプリケーションをパッケージ化してデプロイする方法」を参照してください。
JDeveloperを使用して、RESTful Webサービスを統合WebLogic Serverにデプロイし、デプロイメント・プロセスによって生成されるターゲットURLを使用してADF RESTリソースにアクセスします。生成されたURLを使用すると、ADFモデル・プロジェクトのADF RESTリソースをテストするリクエストを実行できます。
次のいずれかの方法を使用して、必要なペイロードを返すようにデプロイされているサービスのURLを変更することによって、デプロイされているRESTful Webサービスをテストできます。
JDeveloperのHTTPアナライザで、「HTTPリクエストの作成」オプションを使用
Webブラウザ(通常GETリクエストに限定されています)
コマンド・ウィンドウからのcURLコマンド行ツール
cURLはサードパーティ・ツールで、これをインストールして、コマンド・ウィンドウを使用してRESTリクエストを実行するように構成できます。
デプロイされているRESTful Webサービスを使用したADFリソースをテストするには、ADF RESTランタイムによって有効化されているREST API構文を理解していることが必要です。ただし、このドキュメントの手順を使用すると、基本的なGETリクエストを実行してリソース・コレクションを表示できます。
たとえば、すべてのリソースのすべてのバージョンを返すGETリクエストは次のようになります。
http://<server>
/<context-root>
/rest
たとえば、特定のバージョンのすべてのリソースを返すGETリクエストは次のようになります。
http://<server>
/<context-root>
/rest/<versionID>
/describe
たとえば、特定のリソース・コレクションの特定のバージョンを返すGETリクエストは次のようになります。
http://<server>
/<context-root>
/rest/<versionID>
/<resourceName>
始める前に:
ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。
ADF RESTフレームワークおよびHTTPメソッドを使用してAPIコールを行う構文も理解しておくと役立つ場合があります。詳細は、「ADF RESTフレームワークを使用したRESTful Webサービスの使用方法」を参照してください。
また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。
次のタスクを完了する必要があります。
「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。
「統合WebLogic ServerへのADF RESTリソースのデプロイ方法」の説明に従い、ADF RESTリソースを統合WebLogic Serverにデプロイします。
RESTリソースに対してRESTful Webサービス操作をテストするためのツールを使用するには、コマンド行ツールcURLをダウンロードします。
HTTP GETを使用してWebサービスをテストする手順は次のとおりです。