1 Oracle REST Data Servicesの開始
このチュートリアルは、Oracle REST Data Servicesを使用して迅速にRESTfulサービスを開発し始められることを目的としています。
RESTfulサービスのスタート・ガイド
このチュートリアルの処理を実行する前に、次の前提条件と推奨事項を確認します。
-
Oracle REST Data Servicesがインストールされていて、Oracleデータベースに接続するように構成されていることを確認します。
-
RESTfulサービスが編集できるように、Oracle SQL Developer 4.1またはそれ以降がインストールされていることを確認します。
-
WebブラウザでJSONを表示できるようにするブラウザ拡張機能をインストールすることを強くお薦めします。お薦めする拡張機能は次のとおりです。
-
Google Chrome用: JSON Formatter (
webstore_json_formatter
) -
Mozilla Firefox用: JSON View (
addons_mozilla_org
)
-
このチュートリアルの例は、次の項目を前提としています。
-
Oracle REST Data Servicesがインストールされ、構成されていて、次のサーバー、ポートおよびコンテキスト・パスで実行されていること。
localhost:8080/ords/
-
Oracle REST Data Servicesが、
localhost:1521
のOracleデータベース・リスニングにデフォルト接続として接続するよう構成されていて、データベースはorcl
のサービス名を持つこと。
このチュートリアルでは、次の主要なトピックについて説明します。
データベース表のREST対応
RESTアクセスの表を有効にするには、次のステップを実行します。
ノート:
スキーマ・オブジェクトおよびデータベース・オブジェクトに指定した名前を使用することを含め、可能なかぎり正確にステップに従うことをお薦めします。この方法を使用してチュートリアルを正常に完了した後に、値を変更したい場合は自由に再度実行してみてください。
-
次の権限またはロールを持つユーザー
ordstest
を作成します。CREATE USER ordstest IDENTIFIED BY <password>; GRANT "CONNECT" TO ordstest; GRANT "RESOURCE" TO ordstest; GRANT UNLIMITED TABLESPACE TO ordstest
-
ordstest
スキーマに接続します。SQL Developerで、ordstest
スキーマに対する接続を作成し、接続してSQLワークシートを開きます。 -
データベース表を作成します。たとえば、EMPという名前のサンプル表を作成するには、SQLワークシートに次を入力します。
CREATE TABLE EMP ( EMPNO NUMBER(4,0), ENAME VARCHAR2(10 BYTE), JOB VARCHAR2(9 BYTE), MGR NUMBER(4,0), HIREDATE DATE, SAL NUMBER(7,2), COMM NUMBER(7,2), DEPTNO NUMBER(2,0), CONSTRAINT PK_EMP PRIMARY KEY (EMPNO) );
-
表にいくつかのサンプル・データを挿入します。次に例を示します。
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7369,'SMITH','CLERK',7902,to_date('17-DEC-80','DD-MON-RR'),800,null,20); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7499,'ALLEN','SALESMAN',7698,to_date('20-FEB-81','DD-MON-RR'),1600,300,30); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7521,'WARD','SALESMAN',7698,to_date('22-FEB-81','DD-MON-RR'),1250,500,30); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7566,'JONES','MANAGER',7839,to_date('02-APR-81','DD-MON-RR'),2975,null,20); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7654,'MARTIN','SALESMAN',7698,to_date('28-SEP-81','DD-MON-RR'),1250,1400,30); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7698,'BLAKE','MANAGER',7839,to_date('01-MAY-81','DD-MON-RR'),2850,null,30); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7782,'CLARK','MANAGER',7839,to_date('09-JUN-81','DD-MON-RR'),2450,null,10); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7788,'SCOTT','ANALYST',7566,to_date('19-APR-87','DD-MON-RR'),3000,null,20); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7839,'KING','PRESIDENT',null,to_date('17-NOV-81','DD-MON-RR'),5000,null,10); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7844,'TURNER','SALESMAN',7698,to_date('08-SEP-81','DD-MON-RR'),1500,0,30); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7876,'ADAMS','CLERK',7788,to_date('23-MAY-87','DD-MON-RR'),1100,null,20); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7900,'JAMES','CLERK',7698,to_date('03-DEC-81','DD-MON-RR'),950,null,30); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7902,'FORD','ANALYST',7566,to_date('03-DEC-81','DD-MON-RR'),3000,null,20); Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7934,'MILLER','CLERK',7782,to_date('23-JAN-82','DD-MON-RR'),1300,null,10); commit;
-
RESTでEMP表のスキーマを有効化します。SQL Developerで、
ordstest
接続を右クリックし、「RESTサービス」 > 「RESTfulサービスを有効にする」の順に選択して、次のウィザード・ページを表示します。スキーマの有効化: このオプションを有効にします。
スキーマ別名: スキーマ別名として
ordstest
を受け入れます。承認が必要: 簡素化のために、このチュートリアルでは承認を要求しないため、このオプションは無効にします。
「次」をクリックします。
-
ウィザードのRESTfulサマリー・ページで「終了」をクリックします。
-
EMP表を有効化します。SQL Developerで、「接続」ナビゲータでEMP表を右クリックし、「RESTサービス」 > 「RESTfulサービスを有効にする」の順に選択して次のウィザード・ページを表示します。
オブジェクトの有効化: このオプションを有効にします(つまり、EMP表のRESTアクセスを有効にします)。
オブジェクト別名: オブジェクト別名として
emp
を受け入れます。承認が必要: 簡素化のために、このチュートリアルでは承認を要求しないため、このオプションは無効にします。
-
ウィザードのRESTfulサマリー・ページで「終了」をクリックします。
EMP表がREST HTTPエンドポイントとして公開されます。
ノート:
DELETE、PUT、POSTおよびmetadata-catalogエンドポイントも自動生成されています。 -
RESTエンドポイントをテストします。Webブラウザで、次の図に示すように、URL
http://localhost:8080/ords/ordstest/emp/
を入力します。-
ORDSTESTスキーマが
/ordstest/
パスで公開されました。 -
EMP表が
/emp/
パスで公開されました。
-
「接続」ナビゲータを使用したRESTfulサービスの作成
この項では、接続ナビゲータの「RESTデータ・サービス」ノードを使用してRESTful Serviceを作成する方法を説明します。Oracle REST Data Servicesには、接続ナビゲータを介してRESTfulサービス定義を作成および編集できるようにするオプションが用意されています。
接続ナビゲータの「RESTデータ・サービス」ノードを使用してRESTfulサービスを作成するには、次のステップに従います。
-
ordstestスキーマで、「RESTデータ・サービス」を選択します。
次のステップでは、RESTfulサービスを作成してテストします。
-
「RESTデータ・サービス」ノードで
「モジュール」
ノードを右クリックし、「新規モジュール」をクリックして、「モジュールの指定」ページで情報を入力します。モジュール名: 接続用の任意の希望する名前。たとえば、
demo
URI接頭辞:
/demo/
公開 - このRESTfulサービスを使用可能にします: 有効化(チェック)。
ページ区切りサイズ:
25
-
「次」をクリックし、テンプレートの指定ページで情報を入力します。
URIパターン:
emp/
残りのオプションはデフォルトを受け入れます。
-
「次」をクリックして、ウィザードのRESTfulサマリー・ページに移動し、「終了」をクリックします。「モジュール」ノードを展開して、作成したリソース・モジュールを表示します。
-
モジュールDemoを展開し、
emp/
ノードを右クリックして、「追加」ハンドラを選択し、続いてGETメソッドを選択します。 -
リソース・ハンドラの作成ページに関する情報を入力します。
ソース・タイプ:
Collection Query
ページ区切りサイズ:
7
「適用」をクリックします。
次のステップは、GETリソース・ハンドラの問合せを定義することです。
-
SQLワークシートで、次の問合せを入力します。
SELECT INITCAP(ENAME) name, lower(job) job, TO_CHAR(sal,'9G999','NLS_NUMERIC_CHARACTERS=",."') salary, hiredate FROM emp
-
「RESTハンドラの保存」アイコンをクリックします。「メッセージ - ログ」ペインに、ハンドラがデータベースに保存されることを確認するメッセージが表示されます。
ノート:
「メッセージ - ログ」ペインが表示されない場合は、「ビュー」メニューに移動し、「メッセージ」を選択します。 -
RESTfulサービスをテストします。Webブラウザで、次の図に示すように、URL http://localhost:8080/ords/ordstest/demo/emp/を入力します。
-
ORDSTESTスキーマが/ordstest/パスで公開されました。
-
問合せが/demo/emp/パスで公開されました。
-
関連トピック
SQL問合せからのRESTfulサービスの作成
Oracle REST Data Servicesは、Oracle SQL DeveloperがRESTfulサービス定義を作成および編集できるようにするREST API (リソース・モジュールAPIと呼ばれる)を提供します。このオプションは、データベースへの直接アクセス権を持っていない場合に使用できます。リソース・モジュールAPIへのアクセスは保護されていて、適切なロールのユーザーがプロビジョニングされる必要があり、SQL DeveloperからAPIにアクセスするには、作成されたユーザーの資格証明を使用する必要があります。
SQL問合せからのRESTfulサービスを作成するには、次のステップを実行します。
-
Oracle REST Data Servicesがインストールされているフォルダで、コマンド・プロンプトで次のコマンドを入力します。
java -jar ords.war user test_developer "SQL Developer"
-
パスワードの入力を求めるメッセージが表示されます。
-
このコマンドは
test_developer
という名前のユーザーを作成し、ユーザーにSQL Developer
という名前のロールを付与します。SQL Developer
ロールのユーザーのみがリソース・モジュールのAPIにアクセスすることができます。 -
ユーザー詳細は、ORDS構成フォルダの
credentials
という名前のファイルに格納されます。ただし、ユーザー資格証明を本番デプロイメントの資格証明ファイルに格納することはお薦めしません。そのかわりに、ユーザーをホスト・アプリケーション・サーバーにプロビジョニングしてください。
残りのステップでは、RESTfulサービスを作成してテストします。
-
-
RESTful接続を作成します。SQL Developerで、「表示」 > 「RESTデータ・サービス」 > 「開発」の順に選択します。
-
「REST開発」ペインで、「RESTデータ・サービス」 > 「接続」の順に右クリックします。
-
「RESTfulサービス接続」ダイアログ・ボックスで、+ (プラス記号)アイコンをクリックし、選択可能なリストに接続を追加します。
-
「新規RESTfulサービス接続」ダイアログ・ボックスで、次に示す必要な情報を入力します。
接続名: 接続用の任意の希望する名前。例:
ordstest
ユーザー名:
test_developer
httpまたはhttps: このチュートリアルでは、簡素化のため、
http
を選択します。ホスト名:
localhost
ポート:
8080
サーバー・パス:
/ords
ワークスペース:
ordstest
「OK」をクリックし、プロンプトで
test_developer
ユーザーのパスワードを入力します。 -
モジュールを作成します。「REST開発」ビューで
Modules
ノードを右クリックし、「新規モジュール」をクリックして、モジュールの指定ページで情報を入力します。モジュール名: 接続用の任意の希望する名前。例:
test
URI接頭辞:
/test
公開 - このRESTfulサービスを使用可能にします: 有効化(チェック)。
ページ区切りサイズ:
7
-
「次」をクリックし、テンプレートの指定ページで情報を入力します。
URIテンプレート:
/emp/
残りのオプションはデフォルトを受け入れます。
-
「次」をクリックし、ハンドラの指定ページで情報を入力します。
メソッド:
GET
セキュア・アクセスが必要: このチュートリアルでは無効化(チェック解除)します。
ソース・タイプ:
Collection Query
ページ区切りサイズ:
7
-
「次」をクリックして、ウィザードのRESTfulサマリー・ページに移動し、「終了」をクリックします。
リソース・モジュールが作成され、次のステップではGETリソース・ハンドラの問合せを定義します。
-
GETリソース・ハンドラの問合せを定義します。
-
「REST開発」ビューで
Modules
ノードの下にあるtest
ノードを展開します。 -
/emp/
ノードを展開し、GET
ノードを右クリックして「開く」を選択します。 -
GET /emp/
用に開いたSQLワークシートで、次のSQL問合せを入力します。select * from emp
-
「REST開発」ビューの「モジュール」ノードの下のテスト・ノードで右クリックします
-
「アップロード」をクリックします。モジュールがアップロードされたことを確認する確認ダイアログが表示されます。
-
-
RESTfulサービスをテストします。Webブラウザで、次の図に示すように、URL
http://localhost:8080/ords/ordstest/test/emp/
を入力します。-
ORDSTESTスキーマが
/ordstest/
パスで公開されました。 -
問合せが
/test/emp/
パスで公開されました。
-
関連トピック
リソースの保護
ここまで、チュートリアルでは、セキュリティなしでテストをした方が簡単なため、作成したRESTfulエンドポイントで意図的にセキュリティを無効化してきました。この項では/test/emp/
サービスを保護するため、サービスにアクセスする前にユーザーは認証が必要となります。
保護されたリソースへのアクセスの制御は権限を定義することで行われます。「権限」はアクセスを、指定したロールを少なくとも1セットは持つユーザーに制限します。次に権限を1つ以上のリソース・モジュールに関連付けます。必要なロールの1つを確実に持つように、ユーザーは認証されてから権限が付与され、その後リソース・モジュールにアクセスできるようになります。
リソースを保護するには、次のステップを実行します。
OAuthクライアント・アプリケーションの登録
この項では、REST APIにアクセスするためにアプリケーション(ここでは「サード・パーティ」アプリケーションと呼ぶ)を登録する方法を説明します。
OAuth 2.0は、エンド・ユーザーのために、REST APIのサード・パーティ・アプリケーションへのアクセスを制限する手段をHTTPサーバーに提供する標準のインターネット・プロトコルです。
-
サード・パーティ・アプリケーションの作成者は、クライアント資格証明を取得するためにアプリケーションを登録する必要があります。
-
クライアント資格証明のサード・パーティ・アプリケーションを使用すると、エンド・ユーザーに対してアクセスを承認するプロンプトを表示するWebフローを起動します。
そのため、サード・パーティ・アプリケーションがREST APIにアクセスできるするには、登録して、ユーザーがアクセスを承認する必要があります。そして、アプリケーションを登録できるようにするには、ユーザー登録アプリケーションを有効にするユーザー識別子を割り当てる必要があります。SQL Developer
ロールを持つユーザー(「SQL問合せからのRESTfulサービスの作成」で作成されたtest_developer
など)には、OAuthクライアントの登録が許可されています。
ヒント:
実際のアプリケーションでは、OAuthクライアントを登録できる特定のユーザーをプロビジョニングすることもできます。これらのユーザーにはOAuth Client Developer
ロールの権限を付与してください。
この項では、これらの処理を実行する方法の概要を示します。サード・パーティ・アプリケーションをどのように作成して統合するかの全機能のデモンストレーションではありません。含まれている概念の概要を示すのみです。
-
クライアント・アプリケーションを登録します。
-
Webブラウザで次のURLを入力します。
http://localhost:8080/ords/ordstest/oauth/clients/
-
プロンプトで、リンクをクリックしてサイン・インし、
test_developer
ユーザーの資格証明を入力ます。 -
新規クライアントをクリックし、次の情報を入力します。
名前:
Test Client
説明:
An example OAuth Client
リダイレクトURI:
http://example.org/redirect
サポート電子メール:
info@example.org
サポートURI:
http://example.org/support
必要な権限:
Example Privilege
-
「作成」をクリックします。
クライアント登録が作成され、クライアントの認可URIが表示されます。暗黙の権限付与認証フロー(
https://tools.ietf.org/html/rfc6749#section-4.2
で説明)を使用するクライアントを作成しました。クライアントに割り当てられている「クライアント識別子」および認可URIの値をメモします。これらの値は認可フローの開始に使用されます(次の主要ステップ)。
-
-
クライアント・アプリケーションを承認します。
実際のサード・パーティ・クライアント・アプリケーションでは、クライアントはWebブラウザを認可URIに誘導することによって承認フローを開始します。エンド・ユーザーには、サイン・インしてクライアント・アプリケーションへのアクセスを承認するためのプロンプトが表示されます。ブラウザは、承認用に
access_token
が組み込まれたURIフラグメント付きの、クライアントの登録されたリダイレクトURIにリダイレクトされます。このプロセスをシミュレートするには:-
Webブラウザで、前述のステップで確認した認可URIを入力します。URLは次のようになります(この値の例をコピーして貼り付けないでください)。
http://localhost:8080/ords/ordstest/oauth/auth?response_type=token&client_id=5B77A34A266EFB0056BE3497ED7099.&state=d5b7944-d27d-8e2c-4d5c-fb80e1114490&_auth_=force
client_id
値は、アプリケーションに割り当てられたクライアント識別子の値である必要があります。正しいclient_id
値を使用していることを確認してください。前述の例の値は使用しないでください。アプリケーションに割り当てられているクライアント識別子に置き換えてください。state
値は、クライアントが記憶する、一意の推測できない値にしてください。後でOracle REST Data Servicesから受け取ったリダイレクトがこの認可リクエストのレスポンスに入っていることを確認するために使用できます。この値がクロス・サイト・リクエスト・フォージェリ攻撃を防ぐために使用されます。これはとても重要で、省略できません。また、攻撃者によって推測またはや検出が可能な値にはしないでください。 -
プロンプトで、リンクをクリックしてサイン・インし、
test_developer
ユーザーの資格証明を入力ます。 -
リクエストされたアクセスを確認し、「承認」をクリックします。
ブラウザは、次のようなURLにリダイレクトされます。
http://example.org/redirect#token_type=bearer&access_token=-i_Ows8j7JYu0p07jOFMEA..&expires_in=3600
OAuthクライアントを登録するときに、
http://example.org/
リダイレクトをリダイレクトURIとして指定しました。承認リクエストの完了時には、ブラウザはこの登録されたリダイレクトURIにリダイレクトされます。URIに追加された情報は、承認用に生成されたアクセス・トークンに関する情報です。実際のアプリケーションでは、サード・パーティ・アプリケーションは、アクセス・トークンをキャッシュし、別のページにリダイレクトしてREST APIにアクセスするために認可されたことをユーザーに示し、アクセス・トークンをREST APIのすべての後続のリクエストに含めることでリダイレクトURIに応答します。ただし、このチュートリアルでは、次の主要なステップで説明しているように、アクセス・トークンの値をノートにとって、そのアクセス・トークンを含むHTTPリクエストを手動で作成するのみです。
アクセス・トークンの値(前述の例では
-i_Ows8j7JYu0p07jOFMEA..
)は承認されるたびに変更されます。アクセス・トークンの有効期限が切れることに注意してください。前述の例では、3600秒後(
&expires_in=3600
)、つまり1時間後に有効期限が切れます。
-
-
許可されたリクエストを発行します。
アクセス・トークンを取得した後は、クライアント・アプリケーションはアクセス・トークンを記憶し、保護されたリソースへのすべてのリクエストに含める必要があります。次の例に示すように、アクセス・トークンはHTTP認可リクエスト・ヘッダー(
http://tools.ietf.org/html/rfc2616#section-14.8
で説明)に含める必要があります。Host: localhost:8080 GET /ords/ordstest/test/emp/ Authorization: Bearer -i_Ows8j7JYu0p07jOFMEA..
有効なHTTPリクエストの作成をエミュレートするには、cURLコマンドライン・ツールを使用します(必要に応じて、cURLをインストールします)。実際のアプリケーションでは、このリクエストは
XMLHttpRequest
などHTTPリクエストを作成するクライアントによって実行されます。次に例を示します。curl -i -H'Authorization: Bearer -i_Ows8j7JYu0p07jOFMEA..' http://localhost:8080/ords/ordstest/test/emp/
ただし、この例では、
-i_Ows8j7JYu0p07jOFMEA..
を前の手順でメモしたアクセス・トークン値で置き換えます。次のJSONドキュメントのような出力が表示されます。
HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked { "items":[ {"empno":7369,"ename":"SMITH","job":"CLERK","mgr":7902,"hiredate":"1980-12-17T00:00:00Z","sal":800,"comm":null,"deptno":20}, {"empno":7499,"ename":"ALLEN","job":"SALESMAN","mgr":7698,"hiredate":"1981-02-20T00:00:00Z","sal":1600,"comm":300,"deptno":30}, {"empno":7521,"ename":"WARD","job":"SALESMAN","mgr":7698,"hiredate":"1981-02-22T00:00:00Z","sal":1250,"comm":500,"deptno":30}, {"empno":7566,"ename":"JONES","job":"MANAGER","mgr":7839,"hiredate":"1981-04-01T23:00:00Z","sal":2975,"comm":null,"deptno":20}, {"empno":7654,"ename":"MARTIN","job":"SALESMAN","mgr":7698,"hiredate":"1981-09-27T23:00:00Z","sal":1250,"comm":1400,"deptno":30}, {"empno":7698,"ename":"BLAKE","job":"MANAGER","mgr":7839,"hiredate":"1981-04-30T23:00:00Z","sal":2850,"comm":null,"deptno":30}, {"empno":7782,"ename":"CLARK","job":"MANAGER","mgr":7839,"hiredate":"1981-06-08T23:00:00Z","sal":2450,"comm":null,"deptno":10} ], "hasMore":true, "limit":7, "offset":0, "count":7, "links":[ {"rel":"self","href":"http://localhost:8080/ords/ordstest/test/emp/"}, {"rel":"describedby","href":"http://localhost:8080/metadata-catalog/test/emp/"}, {"rel":"first","href":"http://localhost:8080/ords/ordstest/test/emp/"}, {"rel":"next","href":"http://localhost:8080/ords/ordstest/test/emp/?offset=7"} ] }
ただし、
Authorization
ヘッダーが省略された場合には、かわりにステータス401 Unauthorized
が戻されます。
関連項目:
curl_haxx