概要
AutoRESTはOracle Database Cloudの秘められた機能で、対象のスキーマとテーブルに対して有効化することにより、何もしなくてもREST APIで対象テーブルにアクセスすることができるようになります。
利用できるAPI
一般的なCRUD操作（レコードの作成、読み込み、更新、削除）に加えて複数レコードのローディングやフィルターを使った検索なども可能になっています。
完全なAPIの一覧とそれぞれの利用例については末尾にも掲載している公式ドキュメントを参照ください。
- テーブルのメタデータ取得
- GET http://<HOST>:<PORT>/apex[/PDB]/<SchemaAlias>/metadata-catalog/<ObjectAlias>
- レコード一覧取得
- GET http://<HOST>:<PORT>/apex[/PDB]/<SchemaAlias>/<ObjectAlias>/
- レコード一覧取得（ページング）
- GET http://<HOST>:<PORT>/apex[/PDB]/<SchemaAlias>/<ObjectAlias>/?offset=<Offset>&limit=<Limit>
-
レコード検索
- GET http://<HOST>:<PORT>/apex[/PDB]/<SchemaAlias>/<ObjectAlias>/?q=<FilterClause>
-
1レコード取得
- GET http://<HOST>:<PORT>/apex[/PDB]/<SchemaAlias>/<ObjectAlias>/<KeyValues>
-
1レコード追加
- POST http://<HOST>:<PORT>/apex[/PDB]/<SchemaAlias>/<ObjectAlias>/
-
1レコードを更新または追加
- PUT http://<HOST>:<PORT>/apex[/PDB]/<SchemaAlias>/<ObjectAlias>/<KeyValues>
-
1レコード削除
- DELETE http://<HOST>:<PORT>/apex[/PDB]/<SchemaAlias>/<ObjectAlias>/?q=<FilterClause>
-
複数レコードを追加
- POST http://<HOST>:<PORT>/apex[/PDB]/<SchemaAlias>/<ObjectAlias>/batchload?<Parameters>
上記URIのapexの部分はOracle REST Data Servicesのデフォルト仕様ではordsとなっています。
設定手順
- まずSQL Developerで対象のデータベースに接続します。このとき、AutoRESTを有効化したいユーザー（スキーマ）で接続してください。
- スキーマ単位でAutoRESTを有効化します。
AutoRESTを有効化したい接続を右クリックして、RESTサービス > RESTサービスの有効化を選択します。
スキーマの有効化にチェック。話をシンプルにするため、「承認が必要」はチェックを外します。
今後本番利用の際、認証を行うにはチェックを入れます。
設定を確認して終了ボタンをクリック。
- テーブル単位でAutoRESTを有効化します。
AutoRESTを有効化したいテーブルを右クリックし、RESTサービスの有効化を選択します。
オブジェクトの有効化にチェック。ここでも話をシンプルにするために、「承認が必要」はチェックを外します。
設定を確認して終了ボタンをクリック。
これでsugoanスキーマのsurveyテーブルはREST APIでアクセスできるようになりました。
APIアクセス
curlコマンドを使っていくつかAPIコールを試してみます。
1レコード追加
curl -i -X POST -H "Content-Type: application/json" --insecure https://lab/apex/nkjm/sugoan/survey/ --data '{"id":"ID_OF_THIS_RECORD","name":"NAME_OF_THIS_RECORD"}'
//以下はレスポンス
HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: https://lab/apex/nkjm/sugoan/survey/ID_OF_THIS_RECORD
ETag: "6CXmBFGQcBPmkE3H8xIZDgK3olFajUFtGUgHnVm9XM8iqZR0orD0YLGGWbtZ/i/guIIHIfqjoXId6i4rb7EN7Q=="
Transfer-Encoding: chunked
Server: Jetty(9.2.z-SNAPSHOT)
{"id":"ID_OF_THIS_RECORD","name":"NAME_OF_THIS_RECORD","links":[{"rel":"self","href":"https://lab/apex/nkjm/sugoan/survey/ID_OF_THIS_RECORD"},{"rel":"edit","href":"https://lab/apex/nkjm/sugoan/survey/ID_OF_THIS_RECORD"},{"rel":"describedby","href":"https://lab/apex/nkjm/sugoan/metadata-catalog/survey/item"},{"rel":"collection","href":"https://lab/apex/nkjm/sugoan/survey/"}]}
curlコマンドのオプションは下記の通りです。
- -i : レスポンスヘッダーを表示させる
- -X POST : POSTメソッドを利用
- -H : ヘッダーを指定
- --insecure : SSL証明書の確認をおこなわない
- --data : JSON形式にて追加するレコードを入力
URIの構成は下記の通りです。
- lab : ホスト名
- /apex : URIプリフィックス
- /nkjm : PDB名 ＊多くのDatabase Cloud環境はPDB（プラガブルデータベース）を利用することになると思いますが、その際にはPDB名をこのように付加する必要があります。
- /sugoan : スキーマ
- /survey : テーブル
URI末尾の/は必ず必要です。
レコード一覧取得
curl -i -X GET --insecure https://lab/apex/nkjm/sugoan/survey/
// 以下はレスポンス
HTTP/1.1 200 OK
Date: Mon, 06 Jun 2016 01:43:55 GMT
Content-Type: application/json
ETag: "3PmCftlP4JuNerrNgWr/asHJm5m6VPxZ8+Z+q5uHk60bEGMK3MFwdLKqwYoTBN0cG9KbpaVrDMTIdDSlft5fYg=="
Transfer-Encoding: chunked
Server: Jetty(9.2.z-SNAPSHOT)
{"items":[{"id":"ID_OF_THIS_RECORD","name":"NAME_OF_THIS_RECORD","links":[{"rel":"self","href":"https://lab/apex/nkjm/sugoan/survey/ID_OF_THIS_RECORD"}]}],"hasMore":false,"limit":25,"offset":0,"count":1,"links":[{"rel":"self","href":"https://lab/apex/nkjm/sugoan/survey/"},{"rel":"edit","href":"https://lab/apex/nkjm/sugoan/survey/"},{"rel":"describedby","href":"https://lab/apex/nkjm/sugoan/metadata-catalog/survey/"},{"rel":"first","href":"https://lab/apex/nkjm/sugoan/survey/"}]}
curlコマンドのオプションはほとんど先ほどと同じですが、-X GETでGETメソッドを指定している部分がことなります。また、今回は--dataオプションを使ったデータの送信はありません。
URLの構成は先ほどと同様です。
複数レコードの追加
curl -i -X POST -H "Content-Type: text/csv" --insecure https://lab/apex/nkjm/sugoan/survey/batchload --data "id,name
FIRST_ID,FIRST_NAME
SECOND_ID,SECOND_NAME
"
// 以下はレスポンス
HTTP/1.1 200 OK
Date: Mon, 06 Jun 2016 03:16:08 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Server: Jetty(9.2.z-SNAPSHOT)
#INFO Number of rows processed: 2
#INFO Number of rows in error: 0
#INFO Elapsed time: 00:05:10.127 - (310,127 ms)
0 - SUCCESS: Load processed without errors
-H "Content-Type: text/csv"で送信するデータがCSV形式であることを指定し、--dataオプションにてCSV形式のデータを入力しています。
ちなみにCSVファイルをcurlに直接読み込ませる場合は、下記のように--data-binaryオプションに@に続けてCSVファイルへのパスを指定します。
curl -i -X POST -H "Content-Type: text/csv" --insecure https://lab/apex/nkjm/sugoan/survey/batchload --data-binary @/Users/nkjm/Desktop/survey.csv
下記の公式ドキュメントにはすべてのAPI一覧と、その利用例が掲載されていますので網羅的な情報はそちらを参照ください。
Enjoy.