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

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

Oracle Application Expressワークスペースには、デフォルトで、RESTfulサービス・モジュールの例(oracle.example.hr)が含まれます。

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

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

すべてのワークスペースには、RESTful Webサービス・モジュールの例、oracle.example.hrが含まれます。

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

図GUID-4E0A9D3D-BB12-4347-A6B0-CD4AC88377CD-default.pngの説明

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

図GUID-CC0A5BEB-C69E-46E1-91DD-7FEDAAA28C1E-default.pngの説明

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

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

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

• employees/{id}: 従業員のemp表から、指定されたidに関する従業員情報が返されます。中括弧は、URIの一部として送信されるパラメータを示します。

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

• employeesfeed/{id}: 従業員のemp表から、指定されたidに関する従業員情報がJSON形式で表示されます。中括弧は、URIの一部として送信されるパラメータを示します。

• empsec/{empname}: 指定された従業員名(empname)に関する従業員情報がJSONで返されて表示されます。中括弧は、URIの一部として送信されるパラメータを示します。

• empsecformat/{empname}: 指定された従業員名(empname)に関する従業員情報が、PL/SQLブロックの実行に基づいて返されて書式設定されます。中括弧は、URIの一部として送信されるパラメータを示します。

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

• employees/{id}: 従業員のemp表で特定のidに対応する従業員情報が更新されます。中括弧は、URIの一部として送信されるパラメータを示します。リクエストが成功したかどうかの確認に使用できる、ステータス・コードが返されます。

関連項目:

• 「RESTfulサービスへのアクセス」

• その他のRESTfulサービスの例については、Oracle Learning Libraryを参照してください。移動先: http://www.oracle.com/oll/apex

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

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

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

CSV形式でデータを取得するRESTfulサービス・モジュールの例を構築してテストするには、次のステップを実行します。

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

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

2. 「作成」をクリックします。
3. 「名前」に、my.example.demoと入力します。
4. 「URI接頭辞」に、demo/と入力します。これは、このRESTfulサービスへのアクセスに使用されるUniform Resource Identifier (URI)のベースです。
5. 「リソース・テンプレートの追加」で、「URIテンプレート」にempinfo/と入力します。
6. 「リソース・ハンドラの追加」で、「方法」に「GET」を選択します。

   リソース・ハンドラの設定が表示されます。

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

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

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

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

     select * from emp
     

8. 「モジュールの作成」をクリックします

   RESTfulサービス・モジュールのページが表示されます。

9. empinfo/で、GETリソース・ハンドラをクリックします。
10. 「テスト」をクリックします。

    オープン・ダイアログが表示され、リソース・ハンドラのソースSQL問合せの実行結果を含むCSVファイルを開くか、保存することができます。

11. 「ファイルを保存」を選択して、「OK」をクリックします。
12. 保存したCSVファイルの内容は、Microsoft Excelなどのエディタで開いて表示できます。

    CSVファイルには、emp表のすべてのデータが含まれます。

    注意:

    結果が正しくない場合は、empinfo GETリソース・ハンドラとoracle.example.hr empinfo GETリソース・ハンドラを比較します。

13. 「変更の適用」をクリックします。

6.5.3 パラメータに基づくデータの取得(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. リソース・テンプレートの追加先とするRESTfulサービス・モジュールをクリックします。

   RESTfulサービス・モジュールのページが表示されます。

3. 左のパネル下部で、「テンプレートの作成」をクリックします。

   「リソース・テンプレート」オプションが右側に表示されます。

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

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

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

   「リソース・ハンドラ」オプションが表示されます。

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

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

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

   • セキュア・アクセスが必要 - 「いいえ」を選択します。

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

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

     select * from emp  where empno = :id
     

8. 「作成」をクリックします。

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

9. 「バインド変数の設定」をクリックします。
10. 「バインド変数値」に、7876と入力します。
11. 「テスト」をクリックします。

    従業員IDが7876である従業員レコードに関する結果を示すダイアログが表示されます。

注意:

結果が正しくない場合は、employees/{id} GETリソース・ハンドラとoracle.example.hr employees/{id} GETリソース・ハンドラを比較します。

6.5.4 ページ区切りセットを使用した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. リソース・テンプレートの追加先とするRESTfulサービス・モジュールをクリックします。

   RESTfulサービス・モジュールのページが表示されます。

3. 左のパネル下部で、「テンプレートの作成」をクリックします。

   「リソース・テンプレート」オプションが右側に表示されます。

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

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

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

   「リソース・ハンドラ」オプションが表示されます。

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

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

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

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

   • セキュア・アクセスが必要 - 「いいえ」を選択します。

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

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

     select empno "$uri", empno, ename
       from (
            select emp.*
                 , row_number() over (order by empno) rn
              from emp
            ) tmp
      where rn between :row_offset and :row_count 
     

8. 「作成」をクリックします。

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

9. 「テスト」をクリックします。

   JSONで結果が表示されます。各アイテムのuri:{$ref}によって、リンクに指定されたIDに関するemployees/{id} RESTfulサービスが起動されることに注意してください。

   注意:

   結果が正しくない場合は、employees/ GETリソース・ハンドラとoracle.example.hr employees GETリソース・ハンドラを比較します。

10. empno 7369に関するリンクで、最初のuri:{$ref}リンクをクリックします。

    7369に関する個別の従業員レコードが表示されます。

11. ブラウザで「戻る」ボタンをクリックします。

    JSONで元の結果が表示され、7人の従業員がリストされます。

12. next{$ref}リンクをクリックして、データの次のページにナビゲートします。

    次の7行が、最初、前および次のページへのリンクとともに表示されます。

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

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

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

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

フィードとして返されるデータを表示するリソース・テンプレートを追加してテストするには、次のステップを実行します。

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

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

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

   RESTfulサービス・モジュールのページが表示されます。

3. 左のパネル下部で、「テンプレートの作成」をクリックします。

   「リソース・テンプレート」オプションが右側に表示されます。

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

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

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

   「リソース・ハンドラ」オプションが表示されます。

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

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

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

   • セキュア・アクセスが必要 - 「いいえ」を選択します。

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

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

     select empno, ename from emp  order by deptno, ename

8. 「作成」をクリックします。

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

9. 「テスト」をクリックします。

   結果には、emp表の各従業員に関するフィードが表示されます。

注意:

結果が正しくない場合は、employeesfeed/ GETリソース・ハンドラとoracle.example.hr employeesfeed GETリソース・ハンドラを比較します。

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

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

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

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

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

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

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

   RESTfulサービス・モジュールのページが表示されます。

3. 左のパネル下部で、「テンプレートの作成」をクリックします。

   「リソース・テンプレート」オプションが右側に表示されます。

4. 「URIテンプレート」に、empsecformat/{empname}と入力します。
5. 「作成」をクリックします。

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

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

   「リソース・ハンドラ」オプションが表示されます。

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

   • 方法 - 「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;
     

8. 「作成」をクリックします。

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

9. 「バインド変数の設定」をクリックします。
10. empnameパラメータに、ADAMSと入力します。
11. 「テスト」をクリックします。

    Adamsに関する書式設定された結果が表示されます。

注意:

結果が正しくない場合は、empsecformat/{empname} GETリソース・ハンドラとoracle.example.hr empsecformat/{empname} GETリソース・ハンドラを比較します。

6.5.7 パラメータに基づくデータのアップロード(employees/{id})

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

oracle.example.hrモジュールには、RESTfulサービスの実例を示すためのemployees/{id}リソース・テンプレートが含まれています。このテンプレートでは、指定されたidに基づいてJSON形式のデータの行を1行更新して、HTTPステータス・コードを返します。リクエストが成功したかどうかは、このコードによって検証できます。

パラメータに基づいて従業員データを更新する独自のリソース・テンプレートを追加およびテストするには:

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

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

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

   RESTfulサービス・モジュールのページが表示されます。

3. 左のパネル下部で、「テンプレートの作成」をクリックします。

   「リソース・テンプレート」オプションが右側に表示されます。

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

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

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

   「リソース・ハンドラ」オプションが表示されます。

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

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

   • ソース・タイプ - 「PL/SQL」を選択します。匿名のPL/SQLブロックを実行し、OUTまたはIN/OUTパラメータをJSON表現に変換します。このオプションは、HTTPメソッドにDELETE、PUT、POSTのいずれかを選択した場合にのみ使用できます。

   • 使用可能なMIMEタイプ - 空白のままにします。この場合は、HTTPリクエストで使用可能なMIMEタイプのリストを設定する必要はありません。

   • セキュア・アクセスが必要 - 「いいえ」を選択します。

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

     begin
          update emp set ename = :ename,
                 job = :job,
                 hiredate = :hiredate,
                 mgr = :mgr,
                 sal = :sal,
                 comm = :comm,
                 deptno = :deptno
          where empno = :id;
          :status := 200;
          :location := :id;
      exception
          when others then
              :status := 400;
      end;

8. 「作成」をクリックします。

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

9. 「パラメータの作成」をクリックします。
10. 次の選択およびエントリを行います。

    • 名前 - 「ID」と入力します。

    • バインド変数名 - 「ID」と入力します

    • アクセス方法 - 「IN」を選択します

    • ソース・タイプ - 「HTTPヘッダー」を選択します

    • パラメータ・タイプ - 「String」を選択します

11. 「作成」をクリックします。
12. 「パラメータの作成」をクリックします。
13. 次の選択およびエントリを行います。

    • 名前 - 「X-APEX-FORWARD」と入力します

    • バインド変数名 - 「Location」と入力します

    • アクセス方法 - 「OUT」を選択します

    • ソース・タイプ - 「HTTPヘッダー」を選択します

    • パラメータ・タイプ - 「String」を選択します

14. 「作成」をクリックします。
15. 「パラメータの作成」をクリックします。
16. 次の選択およびエントリを行います。

    • 名前 - 「X-APEX-STATUS-CODE」と入力します

    • バインド変数名 - 「Status」と入力します

    • アクセス方法 - 「OUT」を選択します

    • ソース・タイプ - 「HTTPヘッダー」を選択します

    • パラメータ・タイプ - 「Integer」を選択します

17. 「作成」をクリックします。

    注意:

    「テスト」ボタンと「バインド変数の設定」ボタンは、GETリソース・ハンドラのテストにのみ使用できます。Sample REST Servicesアプリケーションをインストールして、PUTリソース・ハンドラの動作をテストしてください。

18. 「パッケージ・アプリケーション」をクリックします。
19. 「Sample REST Services」サンプル・アプリケーションをクリックします。
20. 「パッケージ・アプリケーションのインストール」をクリックし、インストール・ウィザードを最後まで実行して、サンプル・アプリケーションをワークスペースにインストールします。
21. Sample REST Servicesアプリケーションを実行し、APEX認証のログイン資格証明を使用してログインします。
22. 左側のナビゲーション・メニューから、「Simple Report」メニュー項目をクリックします。
23. 従業員のBLAKEに関する情報を編集します(その従業員の編集鉛筆アイコンをクリックします)。

    ダイアログに、従業員のBLAKEに関する従業員レコードが表示されます。このダイアログを使用すると、データを編集して、元のRESTサービスに保存できます(PUTリクエストを使用)。API apex_web_service.make_rest_requestは、PUTリクエストをコールするために使用します。

24. このダイアログ・ボックスで、次に示すようにデータを更新します。

    • 給与: 3000

25. 「変更の適用」をクリックします。

    ダイアログが閉じられ、Simple Reportでは従業員のBLAKEに関するデータの行が更新され(給与が3000に設定され)、ページの上部に"REST PUT request sent - changes applied."という成功メッセージが表示されます。

注意:

結果が正しくない場合は、employees/{id} PUTリソース・ハンドラとoracle.example.hr employees/{id} PUTリソース・ハンドラを比較します。