RESTful Webサービスの作成

4.6 RESTful Webサービスの作成

「モジュール」、「テンプレート」および「ハンドラ」ページを使用して、RESTful Webサービスを作成します。

RESTful Webサービスを作成するには、次の操作を実行する必要があります。

リソース・モジュールの定義
リソース・テンプレートの定義
GET、PUT、POST、DELETEなど、1つ以上のリソース・ハンドラの定義。オプションで、リソース・ハンドラに渡す必要があるパラメータを定義します。

次の各項では、リソース・モジュール、リソース・テンプレートおよびリソース・ハンドラの作成方法について説明します。

関連項目:

RESTワークショップの概要ビデオ
『Oracle REST Data Servicesクイック・スタート・ガイド』のRESTfulサービスの作成に関する項

4.6.1 リソース・モジュールの管理

「モジュール」ページで、リソース・モジュールを定義、編集および削除できます。

「モジュール」ページに移動するには、RESTの概要ページで、「オブジェクト」の「モジュール」をクリックするか、ヘッダーのメニューから「モジュール」を選択します。

次の図に、カード・ビューにデフォルトで表示されるモジュール属性を示します。

図module_card.pngの説明

モジュール・ステータスは公開または非公開にできます。ステータスが非公開の場合、アイコンは赤色で表示されます。

カード・ビューでモジュール名をクリックすると、そのモジュールの「テンプレート」ページにナビゲートします。コンテキスト・メニューから「テンプレート」ページにナビゲートすることもできます。

コンテキスト・メニューで使用できるアクションは次のとおりです。

関連項目:

REST検索ツールバーについて

4.6.1.1 リソース・モジュールの作成

この項では、リソース・モジュールの作成方法について説明します。

「モジュール」ページで、「モジュールの作成」をクリックします。
次のフィールドに入力します。アスタリスク(*)の付いたフィールドは必須です。
「モジュール定義」タブ
- モジュール名: モジュールの名前を入力します。このフィールドには大/小文字区別があります。
- ベース・パス: RESTfulサービスにアクセスするためのURIのベースを入力します。たとえば: hr/は、hr/で始まるすべてのURIがこのリソース・モジュールで処理されることを意味します。ベース・パスを入力したときの、「プレビューURL」の変化に注目してください。
- 公開: RESTfulサービスを使用可能にします。
- ページ区切りサイズ: データベース問合せに基づいて各ページに返される結果の数を入力または選択します。デフォルト値は25です。
- 権限によって保護済: ドロップダウン・リストからモジュールを保護する権限を選択します。
- コメント: 説明的なコメントを入力します。
- 作成後モジュールに移動: モジュールの作成後に「テンプレート」ページに移動する場合は、このオプションを選択します。
「使用可能な起点」タブ
- リソース・テンプレートへのアクセスを許可される起点を入力します。各起点を追加するには、「追加」(+)をクリックします。たとえば:
  
  http://example1.org
  
  https://*.example2.com
コードの表示: 「モジュールの作成」スライダと同等のPL/SQLコードを表示するには、このオプションを選択します。このPL/SQLコードをワークシートにコピーして実行し、「モジュールの作成」スライダで「作成」をクリックしたときと同じアクションを実行できます。
「作成」をクリックします。

新しいモジュールが「モジュール」ページに表示されます。表示されない場合は、「検索」フィールドを使用してモジュールを探します。

4.6.1.2 リソース・モジュールのインポート

この項では、リソース・モジュールのインポート方法について説明します。

ノート:

OpenAPIバージョン2.0または3.0ドキュメントはJSON形式でのみインポートできます。

「モジュール」ページで、右上にある「モジュールのインポート」をクリックします。
インポートするJSONファイルを参照して選択します。「開く」をクリックします。

「モジュールのインポート」スライダが表示され、「ベース・パス」および「プレビューURL」フィールドが事前に入力されています。必要に応じてベース・パスを編集します。「ベース・パス」フィールドを編集すると、スライダに表示されるJSON形式のベース・パスも更新されます。
「インポート」をクリックします。

モジュールがインポートされると、特権構成が作成され、モジュールを保護するように設定されます。権限の名前は、ベース・パスを使用し、ベース・パス文字列の最後に「_priv」を追加し、ベース・パス内のすべてのスラッシュ「/」をアンダースコア「_」に置き換えることによって生成されます。
モジュールを編集する準備ができました。

モジュールのインポート後、テンプレートおよびハンドラが作成されますが、モジュールは公開されません。各ハンドラにSQLおよびPL/SQLブロックを指定し、テストまたは本番の準備ができたらモジュールを公開する必要があります。

4.6.1.3 リソース・モジュールの編集

この項では、リソース・モジュールの編集方法について説明します。

「モジュール」ページで、特定のモジュールのをクリックし、「編集」を選択します。
必要なフィールドを編集して、「保存」をクリックします。フィールドの説明は、リソース・モジュールの作成を参照してください。

4.6.1.4 リソース・モジュールの削除

この項では、リソース・モジュールの削除方法について説明します。

「モジュール」ページで、特定のモジュールのをクリックし、「削除」を選択します。

確認を求めるプロンプトが表示されます。
「OK」をクリックして削除します。

4.6.1.5 リソース・モジュールの公開/非公開

この項では、リソース・モジュールを使用可能または使用不可にする方法について説明します。

「モジュール」ページで、特定のモジュールのをクリックし、「公開」または「非公開」を選択します。

確認を求めるプロンプトが表示されます。
「OK」をクリックします。

4.6.1.6 リソース・モジュールのエクスポート

リソース・モジュールまたはRESTfulサービスのAPIまたはOpen API (Swagger) JSONコードのPL/SQLソース・コードをエクスポートできます。モジュールにテンプレート、ハンドラ、パラメータ、ロールなどがある場合は、これらのオブジェクトも表示およびエクスポートされます。

「モジュール」ページで、特定のモジュールのをクリックし、「モジュールのエクスポート」を選択します。
「PL/SQL」を選択して、APIのPL/SQLソースをコピーまたはエクスポートします。「OpenAPI」を選択して、モジュールのOpen API (Swagger) JSONコードをコピーまたはエクスポートします。

ノート:
オープンAPIを使用してエクスポートされたモジュールは、常に未公開ステータスでインポートされます。
「クリップボードにコピー」をクリックしてコードをコピーするか、「ダウンロード」をクリックしてローカル・コンピュータにダウンロードします。

4.6.1.7 OpenAPIビューでのモジュールの表示

この項では、Open APIビューでモジュールを開く方法について説明します。

「OpenAPIビュー」オプションは、公開されており保護されていないモジュールに使用できます。

「モジュール」ページで、特定のモジュールのをクリックし、「OpenAPIビュー」を選択します。
モジュールはSwagger UIの実装として表示されます。
ハンドラを表示して実行し、パラメータをハンドラに渡して、応答をコピーまたはダウンロードできます。
Swagger UIの実装の詳細は、Swagger UIの公式Webサイトを参照してください。

4.6.2 リソース・テンプレートの管理

「テンプレート」ページで、モジュールのリソース・テンプレートを定義、編集および削除できます。

このページにナビゲートするには、「モジュール」ページで、モジュールのをクリックして「テンプレート」を選択するか、カード・ビューでモジュールの名前をクリックします。

ページ上部にある「編集」、「削除」、「公開」、「エクスポート」などのコンテキスト・メニュー・オプションではモジュール・カードを使用できます。

次の図に、カード・ビューにデフォルトで表示されるテンプレート属性を示します。

図template_card.pngの説明

カード・ビューでテンプレート名をクリックすると、ハンドラ・ページに移動します。コンテキスト・メニューから「ハンドラ」ページにナビゲートすることもできます。

コンテキスト・メニューで使用できるアクションは次のとおりです。

4.6.2.1 リソース・テンプレートの作成

この項では、リソース・テンプレートの作成方法について説明します。

モジュールの「テンプレート」ページで、「テンプレートの作成」をクリックします。
次のフィールドに入力します。アスタリスク(*)の付いたフィールドは、必須のフィールドであることを示しています。
- URIテンプレート: リソース・テンプレートのURIパターンを入力します。
  
  たとえば、/objects/:object/:id?のパターンは、/objects/emp/101 (idが101のempリソースのアイテムに対するリクエストに一致)や/objects/emp/ (:idパラメータにidパラメータがオプションであることを示す?修飾子の注釈があるのでempリソースに対するリクエストに一致)にも一致します。
  
  URIテンプレートを入力したときに、「プレビューURL」が変化することに注意してください。
- 優先度: リソース・テンプレートの評価方法の優先度を入力または選択します(1は低優先度、9は高優先度)。
- HTTPエンティティ・タグ・タイプ: リソース・テンプレートで使用するエンティティ・タグのタイプを選択します。エンティティ・タグとは、リソースのバージョン識別子として動作するHTTPヘッダーです。
  
  オプションは次のとおりです。
  - セキュア・ハッシュ(デフォルト): 戻されたリソース表現の内容は、特定のリソース・バージョンの一意のフィンガープリントを提供するためのセキュア・ダイジェスト・ファンクションを使用してハッシュ化されています。
  - 問合せ: リソース・バージョンを一意に識別する問合せを手動で定義します。手動で定義した問合せによって、リソース表現全体をハッシュ化するより効率的にエンティティ・タグが生成されることが多いです。
  - なし: エンティティ・タグを生成しません。
- コメント: 説明的なコメントを入力します(ある場合)。
- 作成後ハンドラに移動: テンプレートの作成後に「ハンドラ」ページに移動する場合は、このオプションを選択します。
コードの表示: 「テンプレートの作成」スライダと同等のPL/SQLコードを表示するには、このオプションを選択します。このPL/SQLコードをワークシートにコピーして実行し、「テンプレートの作成」スライダで「作成」をクリックしたときと同じアクションを実行できます。
「作成」をクリックします。

モジュールの新しいテンプレートが「テンプレート」ページに追加されます。

「作成後ハンドラに移動」を選択した場合は、ページ上部にあるブレッドクラムのモジュール名を使用して、モジュールのテンプレートのリストを表示できます。

4.6.2.2 リソース・テンプレートの編集

この項では、リソース・テンプレートの編集方法について説明します。

「テンプレート」ページで、特定のテンプレートのをクリックし、「編集」を選択します。
必要なフィールドを編集して、「保存」をクリックします。

フィールドの説明は、リソース・テンプレートの作成を参照してください。

4.6.2.3 リソース・テンプレートの削除

この項では、リソース・テンプレートの削除方法について説明します。

「テンプレート」ページで、特定のテンプレートのをクリックし、「削除」を選択します。

確認を求めるプロンプトが表示されます。
「OK」をクリックして削除します。

4.6.3 リソース・ハンドラの管理

「ハンドラ」ページで、テンプレートのリソース・ハンドラを作成、編集および削除できます。

このページにナビゲートするには、「テンプレート」ページで、テンプレートのをクリックして「ハンドラ」を選択するか、カード・ビューでテンプレートの名前をクリックします。

ページ上部にある「編集」や「削除」などのコンテキスト・メニュー・オプションではテンプレート・カードを使用できます。

次の図に、カード・ビューにデフォルトで表示されるハンドラ属性を示します。

図handler_card.pngの説明

HTTPメソッドは、GET、PUT、POSTおよびDELETEのいずれかです。

ハンドラ名をクリックしてHTTPメソッド・ページに移動するか、コンテキスト・メニューを使用してHTTPメソッド・ページにナビゲートすることもできます。

コンテキスト・メニューで使用できるアクションは次のとおりです。

リソース・ハンドラの作成

ノート:
テンプレートで4つのハンドラすべてが作成されている場合(GET、POST、PUT、DELETE)、このオプションは使用できません。
リソース・ハンドラの編集
リソース・ハンドラの削除
ハンドラの「HTTPメソッド」ページへのナビゲート

4.6.3.1 リソース・ハンドラの作成

この項では、リソース・ハンドラの作成方法について説明します。

「ハンドラ」ページで、「ハンドラの作成」をクリックします。
リソース・ハンドラのプロパティを指定します。具体的なオプションは、メソッド・タイプに応じて異なります。
「ハンドラ定義」タブ
- メソッド: このハンドラのHTTPリクエスト・メソッドを入力します。GET (リソースの表現を取得します)、POST (新規リソースを作成またはコレクションにリソースを追加します)、PUT (既存のリソースを更新します)またはDELETE (既存のリソースを削除します)。各HTTPメソッドに許可されるハンドラは1つのみです。
- ページ当たりのアイテム数: デフォルトのページ区切りサイズ、またはデータベース問合せに対して返される行数を入力または選択します。このオプションはGETハンドラでのみ使用できます。この値が定義されていない場合、ページ当たりのアイテム数はモジュールで定義されている数になります。
- ソース・タイプ: 選択したHTTPメソッドのソース実装を選択します。デフォルトは「収集問合せ」です。
  - 収集問合せ: SQL問合せを実行し、結果セットをJSON表現に変換します。HTTPメソッドがGETの場合に使用可能です。
  - コレクション・アイテム: 1行分のデータをJSON形式で返すSQL問合せを実行します。HTTPメソッドがGETの場合に使用可能です。
  - メディア: 特定の書式に準拠したSQL問合せを実行し、結果セットを、表現のインターネット・メディア・タイプを識別する付随のHTTP Content-Typeヘッダーで、バイナリ表現に変換します。
  - PL/SQL: 匿名のPL/SQLブロックを実行し、OUTまたはIN/OUTパラメータをJSON表現に変換します。
- ソース: HTTPメソッドのSQL問合せまたはPL/SQLブロックを入力します。ハンドラの詳細ページでは、ハンドラ・エディタでSQLまたはPL/SQLハンドラ・コードをテストできます。
- 作成後ハンドラに移動: ハンドラの作成後に詳細ページに移動する場合は、このオプションを選択します。
「使用可能なMIME」タブ

HTTPリクエスト本文に含まれる情報のタイプを識別します。たとえば、POSTハンドラがリクエストにJSONを予期している場合は、MIMEタイプとして「Application/JSON」を追加します。

コードの表示: 「ハンドラの作成」スライダと同等のPL/SQLコードを表示するには、このオプションを選択します。このPL/SQLコードをワークシートにコピーして実行し、「ハンドラの作成」スライダで「作成」をクリックしたときと同じアクションを実行できます。
「作成」をクリックします。

ハンドラが、特定のテンプレートの「ハンドラ」ページに表示されます。

RESTクライアントまたはcURLなどのコマンドライン・ツールを使用して、RESTサービス・エンドポイントをテストできます。

4.6.3.2 リソース・ハンドラの編集

この項では、リソース・ハンドラの編集方法について説明します。

「ハンドラ」ページで、特定のハンドラのをクリックし、「詳細」をクリックします。
必要なフィールドを編集して、「保存」をクリックします。

フィールドの説明は、リソース・ハンドラの作成を参照してください。

4.6.3.3 リソース・ハンドラの削除

この項では、リソース・ハンドラの削除方法について説明します。

「ハンドラ」ページで、特定のハンドラのをクリックし、「削除」をクリックします。

確認を求めるプロンプトが表示されます。
「OK」をクリックして削除します。

4.6.4 例: POSTハンドラを使用したレコードの挿入

次の例は、DEPT表にレコードを挿入する方法を示しています。

前提条件

「SQL」ページのワークシートを使用して、DEPT表を作成します。

CREATE TABLE DEPT(  
  DEPTNO     number(2,0),  
  DNAME      varchar2(14),  
  LOC        varchar2(13),  
  CONSTRAINT PK_DEPT PRIMARY KEY (DEPTNO)  
)

exampleという名前のモジュールを作成します。リソース・モジュールの作成を参照してください
モジュールのemp/という名前のテンプレートを作成します。リソース・テンプレートの作成を参照してください

レコードを挿入するには:

「ハンドラ」ページで、「ハンドラの作成」をクリックします。
次の詳細を入力します。
- 「メソッド」フィールドで、「POST」を選択します。
- 「ソース・タイプ」フィールドで、「PL/SQL」を選択します。
- 「ソース」フィールドに、次のPL/SQLブロックを入力します。
```
DECLARE  
   id number;
BEGIN
    INSERT INTO DEPT (DEPTNO, DNAME, LOC) VALUES (:DEPTNO, :DEPTNAME, :DEPTLOC) RETURNING DEPTNO INTO id;
    :status_code := 201;
    :forward_location := id;
END;
```
  説明
  - RETURNING DEPTNO INTO idは、DEPTNOに割り当てられた値を変数idに戻します。
  - :status_codeは暗黙的なパラメータで、リソースが作成されたことを示すために201が割り当てられます。
  - :forward_locationは暗黙的なパラメータで、DEPTNOの値を含むidが割り当てられます。このパラメータは、POSTリクエストのレスポンスを生成するために、GETリクエストを転送する場所を指定します。
- 作成後ハンドラ・ページに移動が選択されていることを確認します。
- 「使用可能なMIME」タブで、ドロップダウン・リストから「application/json」を選択し、「追加」(+)をクリックします。
- 「作成」をクリックします。
ハンドラのPOSTページが表示されます。

図example_handler_sourceの説明

ソース・エディタで「実行」をクリックして、ソース・コードをテストできます。
GETリソース・ハンドラを作成して、POSTリクエストのレスポンスを生成します。
「例」モジュールで、emp/:idという名前のテンプレートを作成します。

「ソース・タイプ」が「コレクション・アイテム」で、「ソース」に次の問合せが含まれるGETリソース・ハンドラを作成します。
```
SELECT * FROM DEPT WHERE DEPTNO = :id
```
図example_get_handler.pngの説明
cURLで次のコマンドを使用して、RESTfulサービス・エンドポイントをテストします。上部にあるPOSTハンドラ・カードの「クリップボードにコピー」アイコンを使用して、URL (http://xyz.us.comp.com:1234/ords/pdbdba/example/emp)をコピーできます。
```
curl --location --request POST --header "Content-Type: application/json" 
--data '{"DEPTNO": 54, "DEPTNAME": "HR", "DEPTLOC": "America" }' 'http://xyz.us.comp.com:1234/ords/pdbdba/example/emp/'
```
出力は次のとおりです。
```
{"deptno":54,"dname":"HR","loc":"America","links":[{"rel":"collection",
"href":"xyz.us.comp.com:1234/ords/pdbdba/example/emp/"}]}
```
「SQL」ページで、DEPT表をチェックし、次の文を使用して新しいレコードが挿入されているかどうかを確認します。
```
SELECT * FROM DEPT;
```

4.6.5 リソース・ハンドラの詳細の表示およびパラメータの管理

「HTTPメソッド」ページで、リソース・ハンドラの詳細を表示し、パラメータを管理できます。

このページにナビゲートするには、特定のハンドラのをクリックして「詳細」を選択するか、カード・ビューでハンドラの名前をクリックします。

ページ上部にある「編集」や「削除」などのコンテキスト・メニュー・オプションではハンドラ・カードを使用できます。

ハンドラの「HTTPメソッド」ページには、次の2つの主要セクションがあります。

リソース・ハンドラで定義されたSQLまたはPL/SQLソース・コードを実行するためのコード・エディタ。コードを実行し、出力を保存、元に戻す、やり直し、ダウンロードおよびクリアできます。エディタの詳細は、コード・エディタでのSQL文の実行を参照してください。

RESTサービス・ハンドラで使用される暗黙的パラメータは、エディタの右側にあるスクロール・リストに表示されます。詳細は、「暗黙的パラメータ」を参照してください
HTTPメソッドの実行に必要なパラメータを管理するためのセクション。

デフォルトでは、パラメータはグリッド・ビューに表示されます。カード・ビューのパラメータに表示される属性を、次の図に示します。

図parameter_card.pngの説明

コンテキスト・メニューで使用できるアクションは次のとおりです。

関連項目:

REST検索ツールバーについて

4.6.5.1 パラメータの作成

この項では、リソース・ハンドラのパラメータの作成方法について説明します。

ハンドラの「HTTPメソッド」ページで、「パラメータの作成」をクリックします。
次のフィールドに入力します。アスタリスク(*)の付いたフィールドは必須です。
- パラメータ名: URIテンプレートまたはHTTPヘッダーで指定されているパラメータの名前を入力します。この名前によって、受信リクエストでパラメータがどのように識別されるか、またはレスポンスでパラメータがどのように指定されるかが定義されます。
- バインド変数名: SQLで参照されるパラメータの名前を入力します。NULLが指定された場合、パラメータはバインドされません。
- ソース・タイプ: パラメータの発生元がURIテンプレートかHTTPヘッダーかを識別するタイプを選択します。
- パラメータ・タイプ: パラメータのネイティブ型を選択します。
- アクセス方法: パラメータのアクセス方法を選択します。パラメータが入力値か、出力値か、またはその両方かどうかを示します。
コードの表示: 「パラメータの作成」スライダと同等のPL/SQLコードを表示するには、このオプションを選択します。このPL/SQLコードをワークシートにコピーして実行し、「パラメータの作成」スライダで「作成」をクリックしたときと同じアクションを実行できます。
「作成」をクリックします。

パラメータが「パラメータ」セクションに追加されます。

4.6.5.2 パラメータの編集

この項では、パラメータの編集方法について説明します。

「パラメータ」セクションで、特定のパラメータのをクリックし、「編集」を選択します。
必要なフィールドを編集して、「保存」をクリックします。

フィールドの説明は、パラメータの作成を参照してください。

4.6.5.3 パラメータの削除

この項では、パラメータの削除方法について説明します。

「パラメータ」セクションで、特定のパラメータのをクリックし、「削除」を選択します。

確認を求めるプロンプトが表示されます。
「はい」をクリックして削除します。

4.6.5.4 暗黙的パラメータ

この項では、リソース・ハンドラの詳細ページの暗黙的パラメータについて説明します。これらのパラメータは、リソース・ハンドラに自動的に追加されます。

表4-1 暗黙的パラメータ

名前	タイプ	アクセス・モード	HTTPヘッダー	説明
`:body`	BLOB	IN	該当なし	リクエストの本文を一時BLOBとして指定します。
`:body_text`	CLOB	IN	該当なし	リクエストの本文を一時CLOBとして指定します。
`:content_type`	VARCHAR	IN	`Content-Type`	Content-Typeリクエスト・ヘッダーで示されるリクエスト本文のMIMEタイプを指定します。
`:current_user`	VARCHAR	IN	該当なし	リクエストの認証済ユーザーを指定します。ユーザーが認証されていない場合、値はnullに設定されます。
`:forward_location`	VARCHAR	OUT	`X-ORDS-FORWARD-LOCATION`	このリクエストのレスポンスを作成するためにOracle REST Data ServicesがGETリクエストを転送する必要がある場所を指定します。
`:fetch_offset`	NUMBER	IN	該当なし	ページに表示する最初の行のゼロ基点のオフセットを指定します。
`:fetch_size`	NUMBER	IN	該当なし	ビューに取り込む最大行数を指定します。
`:page_offset`	NUMBER	IN	該当なし	ページ区切りリクエストのゼロ基点のオフセットを指定します。ノート: `:page_offset`パラメータは非推奨です。かわりに、`:row_offset`パラメータを使用してください。
`:page_size`	NUMBER	IN	該当なし	ビューに取り込む最大行数を指定します。 `:page_size`パラメータは非推奨です。かわりに、`:fetch_size`パラメータを使用してください。
`:row_offset`	NUMBER	IN	該当なし	ページ区切りリクエストで表示する最初の行の1基点の索引を指定します。
`:row_count`	NUMBER	IN	該当なし	ページ区切りリクエストで表示する最後の行の1基点の索引を指定します。
`:status_code`	NUMBER	OUT	`X-ORDS-STATUS-CODE`	リクエストのHTTPステータス・コードを指定します。

暗黙的なパラメータの詳細は、『Oracle REST Data Services開発者ガイド』を参照してください。