3 暗黙的パラメータ

この章では、明示的には宣言されない、RESTサービス・ハンドラで使用される暗黙的パラメータについて説明します。Oracle REST Data Services(ORDS)はこれらのパラメータをリソース・ハンドラに自動的に追加します。

• 暗黙的パラメータのリスト
  

3.1 暗黙的パラメータのリスト

次の表では、暗黙的パラメータを示します。

ノート:

パラメータ名では大/小文字が区別されます。たとえば、:CURRENT_USERは有効な暗黙的パラメータではありません。

表3-1 暗黙的パラメータのリスト

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

• 自動バインディングのサポート
  
• :body_textパラメータについて
  
• :bodyパラメータについて
  
• :body_jsonパラメータについて
  
• :content_typeパラメータについて
  
• :current_userパラメータについて
  
• :status_codeパラメータについて
  
• :forward_locationパラメータについて
  
• ページ区切り暗黙的パラメータについて
  

3.1.1 自動バインディングのサポート

ORDSでは、次のものの自動バインディングもサポートされています:

• 問合せパラメータ
• フォーム・データ
• JSONオブジェクト

問合せパラメータが指定されているときは、それらが常に自動的にリソース・ハンドラによってバインドされます。一方、フォーム・データとJSONオブジェクトの自動バインディング動作は、次の2つの要因によって決まります:

• :body、:body_textおよび:body_json暗黙的パラメータがどこでどのように使用されているか
• 使用されているメディアタイプまたはMIMEタイプ:
  • application/x-www-form-urlencoded
  • application/json
  • 単一のファイルがあるmultipart/form-data
  • 複数のファイルがあるmultipart/form-data

例

例3-1 問合せパラメータの自動バインディング

ORDSでは、すべてのコンテンツ・タイプでのPOSTリクエストについて、問合せパラメータの自動バインディングがサポートされています。次のものが該当します:

• application/x-www-form-urlencoded
• application/json
• 単一のファイルがあるmultipart/form-data
• 複数のファイルがあるmultipart/form-data

発行されたHTTPリクエストの例:

https://localhost:8443/ords/my_schema/demo/etc?shape=triangle

次のPL/SQLハンドラ・コード例で示すように、値triangleには、自動バインド:shapeを指定したORDSハンドラでアクセスできます。

Begin
  HTP.p('RESULT: ' || :shape);
End;

RESULT: triangle

フォーム・データの自動バインディング

ORDSでは、様々な条件下でPOSTリクエスト本文のフォーム・データの自動バインディングがサポートされています。次の例では、前述の:body_暗黙的パラメータがないORDSリソース・ハンドラに対して発行されるPOSTリクエストを想定しています。

curlコマンドの形式で発行されたHTTPリクエスト:

curl 'https://localhost:8443/ords/my_schema/demo/etc'
  --header 'Content-Type: application/x-www-form-urlencoded'
  --data-url-encode 'last_name=Ever'
  --data-url-encode 'first_name=Greatest'

last_nameおよびfirst_nameの値には、自動バインド:last_nameおよび:first_nameを指定したORDSハンドラでアクセスできます。次のPL/SQLハンドラ・コード例でそれを示します:

BeginHTP.p('Hello: '|| :first_name || :last_name);
End;

Hello: Greatest Ever

関連項目:

• :bodyパラメータについて
• :body_textパラメータについて
• :body_jsonパラメータについて

JSONオブジェクトの自動バインディング

次の条件が満たされている場合は、ORDSで、POSTリクエストでのJSONオブジェクトの自動バインディングがサポートされます:

• Content-Typeがapplication/jsonタイプである
• リソース・ハンドラで次の暗黙的バインド・パラメータが使用されていない:
  • :body
  • :body_text
  • :body_json

curlコマンドの形式で発行されたHTTPリクエスト:

curl 'https://localhost:8443/ords/my_schema/demo/etc'
  --header 'Content-Type: application/json'
  --data '{username: "clark", "password: "superman1234"}'

usernameおよびpasswordの値には、自動バインド:usernameおよび:passwordを指定したこのORDSハンドラからアクセスできます。次のPL/SQLハンドラ・コード例でそれを示します:

BeginHTP.p('Hello: '|| :username);
  Htp.p('Your password: '|| :password);
End;

Hello: clark
Your password: superman1234

3.1.2 :body_textパラメータについて

:body_text暗黙的パラメータは、リクエスト本文のコンテンツを一時CLOBとして受信するためにリソース・ハンドラ内で使用されます。通常、リクエスト本文のコンテンツはテキスト(JSONまたはHTMLコンテンツなど)であるため、リクエスト本文をCLOBとして受け取ることで、リソース・ハンドラの作成者は:body BLOBパラメータをCLOBインスタンスに変換する必要がなくなります。

ノート:

:body_text暗黙パラメータは、PL/SQLブロック全体で1回だけ間接参照する必要があります。この値を複数回必要とする場合は、これをローカル変数に割り当て、かわりにローカル変数を間接参照します。

暗黙的なパラメータ:bodyまたは:body_textのいずれかを使用できます。それ以外の場合は、PL/SQLブロックに、「ストリーム・パラメータが重複しています」というエラー・メッセージが表示されます。

特にPL/SQLブロックでJSONファンクションを使用してリクエスト本体を効率的に処理する場合は、:body (バイナリ表現)ではなく:body_text (文字表現)を使用することをお薦めします。

3.1.3 :bodyパラメータについて

:body暗黙的パラメータは、リクエスト本文のコンテンツを一時BLOBとして受信するためにリソース・ハンドラ内で使用されます。

ノート:

POSTリクエストまたはPUTリクエストのみがリクエスト本文を持つことができます。HTTP仕様では、GETリクエストまたはDELETEリクエストでのリクエスト本文の使用は許可されません。

例3-2 例

次の例は、データベース表にリクエスト本文を格納するPL/SQLブロックを示しています。

begin
 insert into tab (content) values (:body);
end;

ノート:

:body暗黙的パラメータは、PL/SQLブロック内で一度だけ間接参照されるようにしてください。複数回間接参照された場合、2番目以降の間接参照は空になります。これは、リクエスト本文はクライアントから一度しか送信されないためです。この値を複数回必要とする場合は、これをローカル変数に割り当て、かわりにローカル変数を間接参照します。

暗黙的なパラメータ:bodyまたは:body_textのいずれかを使用できます。それ以外の場合は、PL/SQLブロックに、「ストリーム・パラメータが重複しています」というエラー・メッセージが表示されます。

:bodyまたは:body_textを使用する場合は、:bind表記を使用してリクエストのJSONペイロードの属性を読み取ることはできません。

次の例は、:bodyパラメータが2回間接参照されているため、意図したとおりに機能しません。

begin
 insert into tab1(content) values (:body); -- request body will be inserted
 insert into tab2(content) values (:body); -- an empty blob will be inserted
end;

この制限を回避するには、使用前に:bodyパラメータの値をローカルPL/SQL変数に割り当てます。これにより、ローカル変数を2回以上間接参照できます。

declare
 l_content blob := :body;
begin
 insert into tabl(content) values(l_content);
 insert into tab2(content) values(l_content);
end;

3.1.4 :body_jsonパラメータについて

:body_json暗黙的パラメータをPOSTリソース・ハンドラとともに使用すると、リクエスト本文の内容をJSONオブジェクトとして受け取ることができます。これにより、リソース・ハンドラでJSONプロパティ(つまり、{"key": "value"}ペア)を直接参照できるようになります。

また、:body_json暗黙的パラメータは、フォーム・データと1つ以上のファイルがマルチパートまたはフォーム・データのPOSTリクエストに含まれている場合に使用できます。:body_json暗黙的パラメータにバインドされたフォーム・データは引き続きJSONオブジェクトとして受け取られ、1つ以上のファイルはORDS.BODY_FILE_COUNT LOOPファンクションとORDS.GET_BODY_FILEプロシージャで処理できます。

:bodyおよび:body_text暗黙的パラメータと同様に、:body_json暗黙的パラメータがリソース・ハンドラに含まれている場合は、それを起動して、使用できるようにする必要があります。:body_jsonパラメータは、次のいずれかの方法で呼び出すことができます:

• DBMS_OUTPUTパッケージ(dbms_output.put_line(:body_json);など)
• ハイパーテキスト・プロシージャ(htp)およびファンクション(htf)のパッケージ(htp.print(:body_json);など)
• :body_json暗黙的パラメータを変数として割り当てる。たとえば、l_body_json := :body_json;のようにします

• 例
  

3.1.4.1 例

BODY_JSON_DEMO_TABLE表の作成

表BODY_JSON_DEMO_TABLEを、次の属性を指定して作成します:

CREATETABLEBODY_JSON_DEMO_TABLE (
    ID              NUMBER(*, 0)
        GENERATED BY DEFAULT AS IDENTITY ( START WITH 1 CACHE 20 )
    NOT NULL,
    FILE_NAME       VARCHAR2(200),
    FILE_BODY       BLOB,
    CONTENT_TYPE    VARCHAR2(200),
    FILE_VISIBILITY VARCHAR2(10),
    SUBMITTED_BY    VARCHAR2(200),
    SUBMITTED_ON    TIMESTAMP DEFAULT SYSTIMESTAMP,
    SHAPE           VARCHAR2(20)
);

図3-1 表BODY_JSON_DEMO_TABLEの作成

「図3-1 表BODY_JSON_DEMO_TABLEの作成」の説明

ノート:

FILE_VISIBILITY、SUBMITTED_BY、SUBMITTED_ONなどの列は、デモンストレーションの目的でのみ用意されています。

ORDSエンドポイントの作成(リソース・ハンドラ)

ORDSエンドポイントを、次の要件を満たす、次のリソース・ハンドラ・コードを使用して作成します:

• このエンドポイントでは、複数のファイルと、JSON形式でのフォーム・データが想定されています。つまり、:body_json暗黙的パラメータを使用します。
• ORDS.BODY_FILE_COUNTファンクションを、POSTリクエストでファイルの合計数をカウントするために使用します。
• ORDS.GET_BODY_FILEプロシージャを、データベース・セッションのファイル名、詳細および内容を現在のメモリーに一時的に格納するために使用します。これにより、ORDSリソース・ハンドラで、単一のPOSTリクエストで複数のファイルを処理できるようになります。

図3-2 ORDSエンドポイントの作成

「図3-2 ORDSエンドポイントの作成」の説明

INSERTリソース・ハンドラ・コード

次のリソース・ハンドラ・コード例により、その後、BODY_JSON_DEMO_TABLE表に対してINSERTを実行し、様々なHTPプロシージャを使用して結果をユーザー、クライアントまたはアプリケーションに出力します:

DECLARE 
    L_PARAMETER_NAME VARCHAR2(4000);
    L_FILE_NAME      VARCHAR2(4000);
    L_CONTENT_TYPE   VARCHAR2(200);
    L_FILE_BODY      BLOB;
    L_BODY_JSON      CLOB;
BEGIN
    L_BODY_JSON := :BODY_JSON;
    HTP.PARAGRAPH;
    HTP.PRINT('Submitted by: ' || JSON_VALUE(L_BODY_JSON, '$.submitted_by'));
    HTP.BR;
    HTP.PARAGRAPH;
    HTP.PRINT('File visibility status: ' || JSON_VALUE(L_BODY_JSON, '$.file_visibility'));
    HTP.BR;
    HTP.PARAGRAPH;
    HTP.PRINT('Shape selected: ' || :shape);
    FOR i IN 1..ORDS.BODY_FILE_COUNT LOOP
        ORDS.GET_BODY_FILE(
            P_FILE_INDEX     => i,
            P_PARAMETER_NAME => L_PARAMETER_NAME,
            P_FILE_NAME      => L_FILE_NAME,
            P_CONTENT_TYPE   => L_CONTENT_TYPE,
            P_FILE_BLOB      => L_FILE_BODY
        );
        HTP.PARAGRAPH;
        HTP.PRINT('Inserted file #' || i || ': ' || L_FILE_NAME);
        HTP.BR;
        INSERT INTO BODY_JSON_DEMO_TABLE (
            FILE_NAME,
            FILE_BODY,
            CONTENT_TYPE,
            FILE_VISIBILITY,
            SUBMITTED_BY,
            SHAPE
        ) VALUES ( L_FILE_NAME,
                   L_FILE_BODY,
                   L_CONTENT_TYPE,
                   JSON_VALUE(L_BODY_JSON, '$.submitted_by'),
                   JSON_VALUE(L_BODY_JSON, '$.file_visibility'),
                   :shape );
    END LOOP;
END;

:body_json暗黙的パラメータのテスト

1. :body_json暗黙的パラメータをテストするには、次のcurlコマンドを使用します:

   ノート:

   この例では、どのようにORDS POSTリソース・ハンドラでオプションで問合せパラメータの自動バインディング(たとえば: shape=triangle)を使用できるかを示します。

   curl --location 'https://localhost:8443/ords/ordsdocs/binds/body_json_demo?shape=triangle' \
   --form 'files=@"demo-3.sql"' \
   --form 'files=@"demo-2.sql"' \
   --form 'submitted_by="chris"' \
   --form 'file_visibility="public"'

   クライアントからのレスポンスは次のようになります:

   <p>
   Submitted By: chris
   <br />
   <p>
   File visibility status: public
   <br />
   <p>
   Shape: triangle
   <p>
   Inserted File: demo-3.sql
   <br />
   <p>
   Inserted File: demo-2.sql
   <br />

2. PostmanなどのAPIテスト・ツールを使用してテストすることもできます:

   図3-3 Postmanテスト・ツールを使用した:body_json暗黙的パラメータのテスト

   
   

   
   「図3-3 Postmanテスト・ツールを使用した:body_json暗黙的パラメータのテスト」の説明。

   
   

テスト結果

前述のテストを実行した後に、ターゲット・データベースに問い合せると、次の更新が示されます:

図3-4 ターゲット・データベースの問合せ後の結果

「図3-4 ターゲット・データベースの問合せ後の結果」の説明

3.1.5 :content_typeパラメータについて

:content_type暗黙的パラメータは、リクエストで渡されたContent-Typeリクエスト・ヘッダーの値を提供します。リクエストにContent-Typeヘッダーが存在しない場合、null値が返されます。

3.1.6 :current_userパラメータについて

:current_user暗黙的パラメータは、リクエストで認証されたユーザーの身元を提供します。

ノート:

ユーザー認証が行われないシナリオでは、値はnullに設定されます。たとえば、パブリック・リソースに対するリクエストの場合、値はnullに設定されます。

3.1.7 :status_codeパラメータについて

:status_code暗黙的パラメータにより、レスポンスにHTTPステータス・コード値が含まれることをリソース・ハンドラで示すことができます。値は、HTTP仕様ドキュメントで定義されている数値のいずれかである必要があります。

3.1.8 :forward_locationパラメータについて

:forward_location暗黙的パラメータは、PL/SQLベースのリソース・ハンドラがリクエストに対するレスポンスを生成できるようにするためのメカニズムを提供します。

新しいリソースを作成するPOSTリクエストについて考えてみます。通常、REST APIに対するPOSTリクエストのレスポンスには、新しく作成されたリソースの場所(Locationレスポンス・ヘッダー内)と新しいリソースの表現が含まれています。レスポンスにLocationヘッダーが存在することは、指定した場所に対するレスポンスを生成できるGETリソース・ハンドラがあることを示しています。

POSTリソース・ハンドラにロジックを適用するかわりに、既存のGETリソース・ハンドラにタスクを委任して新しいリソースの表現をレスポンスに表示することができます。

次のリソース・ハンドラはPOSTハンドラを定義することで、レスポンスの生成をGETリソース・ハンドラに委任しています。

ords.define_handler(
  p_module_name => 'tickets.collection',
  p_pattern => '.',                     
  p_method  => 'POST',
  p_mimes_allowed => 'application/json',
  p_source_type => ords.source_type_plsql,
  p_source => '
   declare
    l_owner varchar2(255);
    l_payload clob;
    l_id number;
   begin
    l_payload := :body_text;
    l_owner := :current_user;
    l_id := ticket_api.create_ticket(
      p_json_entity => l_payload,
      p_author => l_owner
    );
    :forward_location := ''./'' || l_id;
    :status_code := 201;
   end;
  '
);

説明:

• ords.define_handler APIを使用して、tickets.collectionという名前の既存のリソース・モジュールにPOSTハンドラを追加しています。

• 値が'.'のp_patternは、POSTハンドラをリソース・モジュールのルート・リソースにバインドする必要があることを示しています。tickets.collectionのベース・パスが/tickets/の場合、POSTハンドラは/tickets/ URLパスにバインドされます。

• p_mimes_allowedの値は、POSTリクエストのContent-Typeヘッダー値がapplication/jsonでなければならないことを示しています。

• p_source_type値は、POSTハンドラのソースがPL/SQLブロックであることを示しています。

• p_source値には、PL/SQLブロックのソースが含まれます。

  説明:

  ノート:

  :body_text暗黙的パラメータがローカル変数に割り当てられているため、複数回の間接参照が可能です。

  • POSTリクエストを発行したユーザーの身元は、:current_user暗黙的パラメータによって判別されます。

  • このPL/SQLブロックはリクエスト・ペイロードを格納するタスクをPL/SQLパッケージ・レベル・ファンクションに委任しています。PL/SQLブロックにはHTTPリクエストとPL/SQLパッケージの起動をつなぐロジックのみを含める必要があります。

    ノート:

    すべてのデータ変更操作がPL/SQL APIでラップされている場合、PL/SQLブロックは個別にテストできます。長時間および複雑なPL/SQLブロックはコードがアンチパターンであることを示しており、テストとメンテナンスが困難です。

  • PL/SQLパッケージ・レベル・ファンクションは新しく作成されたリソースのIDを返します。

  • :forward_location暗黙的パラメータには、'./' || l_idの値が割り当てられます。たとえば、l_idの値が4256の場合、:forward_locationの値は/tickets/4256になります。

    ORDSは先行するPL/SQLブロックを評価し、:forward_location暗黙的パラメータに割り当てられた値をチェックするときに、指定された場所(たとえば、/tickets/4256)に対してGETリクエストを開始し、GETリクエストから生成されたレスポンスをPOSTリクエストのレスポンスとして返します。また、ORDSは場所レスポンス・ヘッダーをレスポンスに含め、ここに:forward_location値の完全に解決されたURLを格納します。

  • :status_code暗黙的パラメータには、HTTPレスポンス・ステータス・コード値が割り当てられます。201(作成済)ステータス・コードは、新しいリソースが作成されたことを示します。この値は、GETリクエストで生成されたステータス・コードを上書きします。

3.1.9 ページ区切り暗黙的パラメータについて

次の表に、ページ区切り暗黙的パラメータを示します。

ノート:

Oracle REST Data Servicesは、問合せパラメータ、page、offsetおよびlimitの使用を予約します。前述の問合せパラメータ名のいずれかを使用して、名前付きバインド・パラメータを使用するRESTサービスを定義することはできません。かわりに、RESTサービスでは次の表に示す適切なページ区切り暗黙的パラメータを使用する必要があります。

表3-2 ページ区切り暗黙的パラメータ

名前	説明	ステータス
:page_offset	ページ区切りリクエストのゼロ基点のページ・オフセットを指定します。	非推奨
:page_size	Recovery Appliance	非推奨
:row_offset	ページ区切りリクエストで表示する最初の行の索引を指定します。	お薦めしません
:row_count	ページ区切りリクエストで表示する最後の行の索引を指定します。	お薦めしません
:fetch_offset	ページに表示する最初の行のゼロ基点の索引を指定します。	お薦めします
:fetch_size	ビューに取り込む最大行数を指定します。	お薦めします

• :page_offsetパラメータについて
  
• :page_sizeパラメータについて
  
• :row_offsetパラメータについて
  
• :row_countパラメータについて
  
• :fetch_offsetパラメータについて
  
• :fetch_sizeパラメータについて
  
• 自動ページ区切りについて
  この項では、自動ページ区切りプロセスについて説明します。
• 手動ページ区切りについて
  この項では、手動ページ区切りプロセスについて説明します。

3.1.9.1 :page_offsetパラメータについて

:page_offset暗黙的パラメータは下位互換性のために提供されるため、source_type_queryソース・タイプのリソース・ハンドラでのみ使用されます。

ノート:

• source_type_queryソース・タイプは非推奨です。かわりにsource_type_collectionフィード・パラメータを使用してください。

• :page_offset暗黙的パラメータは非推奨です。かわりに:row_offset暗黙的パラメータを使用してください。

3.1.9.2 :page_sizeパラメータについて

:page_size暗黙的パラメータは、ページに取り込む最大行数を指定するために使用されます。:page_sizeパラメータは下位互換性のために提供されます。このパラメータは非推奨です。かわりに:fetch_size暗黙的パラメータを使用してください。

3.1.9.3 :row_offsetパラメータについて

:row_offset暗黙的パラメータは、ページに表示する最初の行の数を示します。:row_offset暗黙的パラメータが使用されるのは、ラッパー・ページ区切り問合せとrow_number()(Oracle11g以前のリリースで使用される)の両方を使用している場合です。Oracle12c以降のリリースでは、:row_offsetパラメータのかわりに、:fetch_offset暗黙的パラメータと行制限句を使用することをお薦めします。

3.1.9.4 :row_countパラメータについて

:row_count暗黙的パラメータを使用して、ページに表示する行数を指定します。:row_count値は、:row_offsetとページ区切りサイズの合計の値です。:row_count暗黙的パラメータは、ラッパー・ページ区切り問合せ(Oracle Database11g以前のリリースで使用されていた)とrow_number()メソッドを使用してページ区切りを実装する場合に便利です。Oracle Databaseリリース12c以降では、かわりに:fetch_sizeパラメータと行制限句を使用することをお薦めします。

3.1.9.5 :fetch_offsetパラメータについて

:fetch_offset暗黙的パラメータは、指定されたページに表示する最初の行のゼロ基点のオフセットを示すために使用されます。:fetch_offset暗黙的パラメータは、Oracle12c以降のリリースで使用が推奨されている行制限句を使用してページ区切りを実装する場合に使用されます。

3.1.9.6 :fetch_sizeパラメータについて

:fetch_size暗黙的パラメータは、ページに取り込む最大行数を指定するために使用されます。ORDSでは:fetch_sizeの値が常にページ区切りサイズ+1に設定されます。余分な行があるかどうかに基づいて、ORDSは結果に後続のページがあるかどうかを判断します。

ノート:

問合せされた余分な行はページに表示されません。

3.1.9.7 自動ページ区切りについて

この項では、自動ページ区切りプロセスについて説明します。

ソース・タイプsource_type_collection_feedまたはsource_type_queryのGETリソース・ハンドラにゼロ以外のページ区切りサイズ(p_items_per_page)が設定されていて、さらにGETリソース・ハンドラのソースが、前の項で説明した暗黙的ページ区切りパラメータのいずれも間接参照していない場合は、ORDSは問合せをページ区切り句にラップし、リクエストされたページの値のみが含まれるよう問合せ結果を制限します。自動ページ区切りでは、リソース・ハンドラの作成者はページ区切りサイズを指定するだけでよく、リソースのページ区切りに必要な残りの作業はORDSによって自動的に処理されます。

ノート:

すべてのリソース・モジュールにはデフォルトのページ区切りサイズ(p_items_per_page) 25が設定されています。そのため、デフォルトで自動ページ区切りが有効になります。

3.1.9.8 手動ページ区切りについて

この項では、手動のページ区切りプロセスについて説明します。

シナリオによっては、ページ区切りプロセスをORDSに委任するのではなく、GETリソース・ハンドラ自身でページ区切りを実行しなければならない場合があります。このような場合、GETリソース・ハンドラのソースは、前述の項で説明した1つまたは複数の暗黙的ページ区切りパラメータを間接参照します。

ノート:

GETリソース・ハンドラ側で必要なページ区切りサイズを指定し、ORDSが暗黙的ページ区切りパラメータで必要な値を正しく計算できるようにする必要があります。

例

行制限句を使用した手動ページ区切りの例

次の例は、行制限句を使用して問合せ結果セットをページ区切りするRESTサービスを定義しています。この方法で手動のページ区切りを実装することをお薦めします。

begin
 ords.define_service(
   p_module_name => 'example.paging',
   p_base_path => '/example/',
   p_pattern => '/paged',
   p_items_per_page => 7,
   p_source => 'select * from emp e order by empno desc offset :fetch_offset rows fetch next :fetch_size rows only'
 );
 commit;
end;

row_number()メソッドを使用した手動ページ区切りの例

次の例は、ラッパー問合せおよびrow_number()メソッドを使用するRESTサービスを定義しています。このアプローチはお薦めしません。

begin
ords.define_service(
   p_module_name => 'example.paging',
   p_base_path => '/example/',
   p_pattern => '/paged',
   p_items_per_page => 7,
   p_source => 'select * from (select q_.* , row_number() over (order by 1) rn__ from (select * from emp e order by empno desc) q_ )where rn__ between :row_offset and :row_count'
 );
 commit;
end;