7.5 ORDSベースのRESTfulサービス・モジュールの例の作成方法

ORDSベースのRESTfulサービス・モジュールの例の作成方法を学習します。

Oracle APEXワークスペースには、デフォルトで、RESTfulサービス・モジュールの例(oracle.example.hr)が含まれます。ORDSにスキーマを登録する際には、サンプル・サービスをインストールできます。

• RESTfulサービス・モジュールの例(oracle.example.hr)について
  ORDSベースのRESTfulサービスでは、ORDSにスキーマを登録する際にサンプル・サービスoracle.example.hrをインストールすることもできます。
• PL/SQLブロックに基づく結果セットの返却(empsecformat/:empname)
  PL/SQLブロックを使用して結果を書式設定する独自のリソース・テンプレートを追加してテストできます。
• ページ区切りセットを使用したJSON形式での結果セットの返却(employees/)
  JSON形式でデータを取得してページ区切りを実行する独自のリソース・テンプレートを追加してテストできます。
• パラメータに基づくデータの取得(employees/:id)
  パラメータに基づいて従業員データを取得する独自のリソース・テンプレートを追加してテストできます。
• CSV形式で結果セットの返却(empinfo/)
  CSV形式でデータを取得する独自のRESTfulサービス・モジュールの例を構築してテストできます。
• フィードとしての結果セットの返却(employeesfeed/)
  フィードとして返されるデータを表示する独自のリソース・テンプレートを追加してテストできます。

7.5.1 RESTfulサービス・モジュール(oracle.example.hr)例について

ORDSベースのRESTfulサービスでは、ORDSにスキーマを登録する際にサンプル・サービスoracle.example.hrをインストールすることもできます。

このモジュールは、emp表から従業員情報を取得して表示する複数の方法を実装するリソース・テンプレートおよびリソース・ハンドラの例を示します。oracle.example.hrモジュールにアクセスするには、「RESTfulサービスへのアクセス」を参照してください。

oracle.example.hrモジュールは、複数のリソース・テンプレートで構成されています。各リソース・テンプレートは、それぞれ異なった方法で、情報を取得して返される結果を書式設定します。

図oracle_ex_temp.pngの説明

次に、各GETリソース・ハンドラを起動した際に、各oracle.example.hrリソース・テンプレートで予期される結果を示します。

• empsec/:empname: 指定された従業員名(empname)に関する従業員情報がJSONで返されて表示されます。

• empsecformat/:empname: 指定された従業員名(empname)に関する従業員情報が、PL/SQLブロックの実行に基づいて返されて書式設定されます。

• employees/ - 従業員のemp表から、ページ区切りサイズが7に設定されたJSON形式で従業員情報が表示されます。最初、前および次へのリンクを使用して、結果を参照できます。

• バージョン/- RESTfulサービス・モジュールのバージョンを返します。

• employees/:id: 従業員のemp表から、指定されたidに関する従業員情報が返されます。

• empinfo/ - 従業員のemp表から、従業員情報がCSV形式で返されます。

• employeesfeed/ - 従業員のemp表から、従業員情報がJSONフィードとして返されます。

• employeesfeed/:id: 従業員のemp表から、指定されたidに関する従業員情報がJSON形式で表示されます。

次に示す結果は、PUTリソース・ハンドラが起動されたときに、employees/:idリソース・テンプレートに対して予期されるものです。

• employees/:id: 従業員のemp表で特定のidに対応する従業員情報が更新されます。

関連項目:

RESTfulサービスへのアクセス

7.5.2 PL/SQLブロックに基づく結果セットの返却(empsecformat/:empname)

PL/SQLブロックを使用して結果を書式設定するリソース・テンプレートを追加してテストできます。

oracle.example.hrモジュールには、PL/SQLブロックによって書式設定されたSQL問合せの結果を返すRESTfulサービスを示すempsecformat/:empnameリソース・テンプレートが含まれます。

PL/SQLブロックを使用して結果を書式設定するリソース・テンプレートを追加してテストするには:

1. ワークスペースのホームページで、「SQLワークショップ」をクリックして、「RESTfulサービス」をクリックします。

   「RESTfulサービス」ホームページが表示されます。

2. 「ORDSベースのRESTfulサービス」をクリックします。

   ORDS RESTfulサービス・ページが表示されます。

3. リソース・テンプレートの追加先とするRESTfulサービス・モジュールをクリックします。

   モジュール定義ページが表示されます。

4. 左のパネルのリソース・テンプレート・ブロックの下で、「テンプレートの作成」をクリックします。

   ORDSテンプレート定義ページが表示されます。

5. 「URIテンプレート」に、empsecformat/:empnameと入力します。
6. 「テンプレートの作成」をクリックします。
7. empsecformat/:empnameリソース・テンプレートの下で、「ハンドラの作成」をクリックします。

   ORDSハンドラ定義ページが表示されます。

8. 次の選択およびエントリを行います。

   • 方法 - 「GET」を選択します。

   • ソース・タイプ - 「PL/SQL」を選択します。

   • ソース - 次を入力します。

     DECLARE
       prevdeptno     number;  
       total_rows     number;
       deptloc        varchar2(20);
       deptname       varchar2(20);
       CURSOR         getemps is select * from emp
                                  start with ename = :empname
                                 connect by prior empno = mgr
                                  order siblings by deptno, ename;
     BEGIN
       sys.htp.htmlopen;
       sys.htp.headopen;
       sys.htp.title('Hierarchical Department Report for Employee '||:empname);
       sys.htp.headclose;
       sys.htp.bodyopen;
      
       for emprecs in getemps
       loop
      
           if l_employee.deptno != prevdeptno or prevdeptno is null then
               select dname, loc
                into deptname, deptloc
                from dept
               where deptno = l_employee.deptno;
     
              if prevdeptno is not null then
                  sys.htp.print('</ul>');
              end if; 
             sys.htp.print('Department ' || apex_escape.html(deptname) || ' located in ' || apex_escape.html(deptloc) || '<p/>');
             sys.htp.print('<ul>');
           end if;
      
           sys.htp.print('<li>' || apex_escape.html(l_employee.ename) || ', '  || apex_escape.html(l_employee.empno) || ', ' ||
                             apex_escape.html(l_employee.job) || ', ' || apex_escape.html(l_employee.sal) || '</li>'); 
     
           prevdeptno := l_employee.deptno;
           total_rows := getemps%ROWCOUNT;
     
        end loop; 
        if total_rows > 0 then
            sys.htp.print('</ul>');
        end if; 
        sys.htp.bodyclose;
        sys.htp.htmlclose;
     END;
     

9. 「ハンドラの作成」をクリックします。

   GETリソース・ハンドラが左のパネルのempsecformat/:empnameリソース・テンプレートの下に表示されます。

7.5.3 ページ区切りセットを使用したJSON形式での結果セットの返却(employees/)

JSON形式でデータを取得してページ区切りを実行するリソース・テンプレートを追加してテストできます。

oracle.example.hrモジュールには、JSON形式でデータを戻すRESTfulサービスを示すemployees/リソース・テンプレートが含まれます。この例では、ページ区切りバインド変数を通じて、ページ区切りセットを使用したJSON形式で結果セットが返されます。ページ区切りバインド変数は、:row_offsetおよび:row_countです。

JSON形式で結果を返すリソース・テンプレートのその他の例は、oracle.example.hrサービス・モジュールのempsec/{empname}リソース・テンプレートを参照してください。

JSON形式でデータを取得してページ区切りを実行するリソース・テンプレートを追加してテストするには:

1. ワークスペースのホームページで、「SQLワークショップ」をクリックして、「RESTfulサービス」をクリックします。

   「RESTfulサービス」ホームページが表示されます。

2. 「ORDSベースのRESTfulサービス」をクリックします。

   ORDS RESTfulサービス・ページが表示されます。

3. リソース・テンプレートの追加先とするRESTfulサービス・モジュールをクリックします。

   モジュール定義ページが表示されます。

4. 左のパネルのリソース・テンプレート・ブロックの下で、「テンプレートの作成」をクリックします。

   ORDSテンプレート定義ページが表示されます。

5. 「URIテンプレート」に、employees/と入力します。
6. 「テンプレートの作成」をクリックします。

   employees/リソース・テンプレートが左のパネルに表示されます。

7. employees/リソース・テンプレートの下で、「ハンドラの作成」をクリックします。

   ORDSハンドラ定義ページが表示されます。

8. 次の選択およびエントリを行います。

   • 方法 - 「GET」を選択します。

   • ソース・タイプ - 「問合せ」を選択します。

   • 書式 - 「JSON」を選択します。

   • ソース - 次を入力します。

     select empno "$uri", rn, empno, ename, job, hiredate, mgr, sal, comm, deptno
       from (
            select emp.*
                 , row_number() over (order by empno) rn
              from emp
            ) tmp

9. 「ハンドラの作成」をクリックします。

   GETハンドラが左のパネルのemployees/リソース・テンプレートの下に表示されます。

7.5.4 パラメータに基づくデータの取得(employees/:id)

パラメータに基づいて従業員データを取得するリソース・テンプレートを追加してテストできます。

oracle.example.hrモジュールには、指定されたidに基づく1行分のデータをJSON形式で返すRESTfulサービスを示すemployees/:idリソース・テンプレートが含まれます。

指定されたパラメータに基づいて結果を返すリソース・テンプレートのその他の例は、oracle.example.hrサービス・モジュールのemployeesfeed/:id、empsec/:empnameおよびempsecformat/:empnameリソース・テンプレートを参照してください。

パラメータに基づいて従業員データを取得するリソース・テンプレートを追加してテストするには:

1. ワークスペースのホームページで、「SQLワークショップ」をクリックして、「RESTfulサービス」をクリックします。

   「RESTfulサービス」ホームページが表示されます。

2. 「ORDSベースのRESTfulサービス」をクリックします。

   ORDS RESTfulサービス・ページが表示されます。

3. リソース・テンプレートの追加先とするRESTfulサービス・モジュールをクリックします。

   モジュール定義ページが表示されます。

4. 左のパネルのリソース・テンプレート・ブロックの下で、「テンプレートの作成」をクリックします。

   ORDSテンプレート定義ページが表示されます。

5. 「URIテンプレート」に、employees/:idと入力します。
6. 「テンプレートの作成」をクリックします。

   employees/:idリソース・テンプレートが左のパネルに表示されます。

7. employees/:idリソース・テンプレートの下で、「ハンドラの作成」をクリックします。

   ORDSハンドラ定義ページが表示されます。

8. 次の選択およびエントリを行います。

   • 方法 - 「GET」を選択します。

   • ソース・タイプ - 「1行問い合せる」を選択します。1行分のデータをJSON形式で返すSQL問合せを1回実行します。このオプションは、HTTPメソッドのGETを選択した場合にのみ使用できます。

   • ページ区切りサイズ - 空白のままにします。ここでは、1つのレコードのみが取得されるため、ページ区切りを設定する必要はありません。

   • ソース - 次を入力します。

     select * from emp  where empno = :id
     

9. 「ハンドラの作成」をクリックします。

7.5.5 CSV形式での結果セットの返却(empinfo/)

CSV形式でデータを取得するRESTfulサービス・モジュールの例を構築してテストできます。

oracle.example.hrモジュールには、CSV形式でデータを返すRESTfulサービスを示すempinfo/リソース・テンプレートが含まれます。この例では、emp表の従業員データはすべて、SQL問合せを使用して返されます。

CSV形式でデータを取得するRESTfulサービス・モジュールの例を構築してテストするには:

1. ワークスペースのホームページで、「SQLワークショップ」をクリックして、「RESTfulサービス」をクリックします。

   「RESTfulサービス」ホームページが表示されます。

2. 「ORDSベースのRESTfulサービス」をクリックします。

   ORDS RESTfulサービス・ページが表示されます。

3. リソース・テンプレートの追加先とするRESTfulサービス・モジュールをクリックします。

   モジュール定義ページが表示されます。

4. 左のパネルのリソース・テンプレート・ブロックの下で、「テンプレートの作成」をクリックします。

   ORDSテンプレート定義ページが表示されます。

5. 「URIテンプレート」に、empinfo/と入力します。
6. 「テンプレートの作成」をクリックします。

   empinfo/リソース・テンプレートが左のパネルに表示されます。

7. empinfo/リソース・テンプレートの下で、「ハンドラの作成」をクリックします。

8. 次の選択およびエントリを行います。

   • 方法 - 「GET」を選択します。

   • ソース・タイプ - 「問合せ」を選択します。SQL問合せを実行し、選択したフォーマットに応じて、JavaScript Object Notation (JSON)形式またはCSV形式に結果セットを変換します。このオプションは、HTTPメソッドのGETを選択した場合にのみ使用できます。

   • 書式 - 「CSV」を選択します。

   • ソース - 次を入力します。

     select * from emp
     

9. 「ハンドラの作成」をクリックします。

7.5.6 フィードとしての結果セットの返却(employeesfeed/)

フィードとして返されるデータを表示するリソース・テンプレートを追加してテストできます。

oracle.example.hrモジュールには、emp表からempnoおよびenameの値を返し、それらの値をフィードとして表示するRESTfulサービスを示すemployeesfeed/リソース・テンプレートが含まれます。

フィード・リソース・ハンドラは、SQL問合せを実行し、結果をJSON Feed形式に変換します。フィードの各アイテムには、リソースのサマリーと、リソースの完全形式へのハイパーリンクが含まれます。結果セットの各行の最初の列は、その行の一意の識別子である必要があり、path/to/feed/{id}という形式のハイパーリンクを生成するために使用されます(最初の列の値が{id}の値として使用されます)。その行の他の列は、リソースを要約するとみなされ、フィードに含まれます。リソースの完全形式のリソース・テンプレートも、別途定義する必要があります。

フィードとして返されるデータを表示するリソース・テンプレートを追加してテストするには:

1. ワークスペースのホームページで、「SQLワークショップ」をクリックして、「RESTfulサービス」をクリックします。

   「RESTfulサービス」ホームページが表示されます。

2. 「ORDSベースのRESTfulサービス」をクリックします。

   ORDS RESTfulサービス・ページが表示されます。

3. リソース・テンプレートの追加先とするRESTfulサービス・モジュールをクリックします。

   モジュール定義ページが表示されます。

4. 左のパネルのリソース・テンプレート・ブロックの下で、「テンプレートの作成」をクリックします。

   ORDSテンプレート定義ページが表示されます。

5. 「URIテンプレート」に、employeesfeed/と入力します。
6. 「テンプレートの作成」をクリックします。
7. employeesfeed/リソース・テンプレートの下で、「ハンドラの作成」をクリックします。

   ORDSハンドラ定義ページが表示されます。

8. 次の選択およびエントリを行います。

   • 方法 - 「GET」を選択します。

   • ソース・タイプ - 「フィード」を選択します。

   • ページ区切りサイズ - 「25」と入力します。

   • ソース - 次を入力します。

     select empno, ename from emp  order by deptno, ename

9. 「ハンドラの作成」をクリックします。