インストール方法や使用方法など、REST APIのためのOracle SODAについて説明します。
次の内容を理解しておくと、ここで示す情報を最大限に活用できます。
Oracleリレーショナル・データベース管理システム(RDBMS)
JavaScript Object Notation(JSON)
Hypertext Transfer Protocol(HTTP)
関連項目:
Oracle Database JavaのためのSODA開発者ガイド。RESTのためのSODAが構築されるJavaクライアントAPIの使用方法について説明しています。
Oracle DatabaseでのJSONの情報については、Oracle Database JSON開発者ガイド
Simple Oracle Document Access (略してSODA)を使用すると、Oracle Databaseのドキュメントのコレクションを作成および格納することができ、Structured Query Language (SQL)や、ドキュメントのデータがどのようにデータベースに格納されているかを理解していなくても、そのコレクションの取得や問合せを行うことができます。
RESTのためのSODAは、Representational State Transfer (REST)アーキテクチャ・スタイルを使用してSODAを提供するREST API です。これを使用して、あらゆる種類のドキュメントについて作成、読取り、更新および削除(CRUD)操作を実行することや、JSONドキュメントを問い合せることができます。
注意:
RESTのためのSODAで使用されるドキュメントは、約2 GBに制限されています。
注意:
データベース文字セットにはAL32UTF8 (Unicode)を使用することをお薦めします。そうでない場合は、次のようになります。
データベース文字セットへの変換で情報が失われるため、データは、入力中に変更される可能性があります。
例による問合せ(QBE)で、予測不能な結果が返される可能性があります。
RESTアーキテクチャ・スタイルは、HTTP 1.1およびUniform Resource Identifier(URI)を定義するために使用されました。RESTベースのAPIはHTTPサーバーの提供する基本機能に非常によく似ており、ほとんどのRESTベースのシステムはHTTPクライアントとHTTPサーバーを使用して実装されています。
標準的なRESTの実装では、作成、読取り、更新、削除(CRUD)の操作が、HTTPの動詞であるPOST
、GET
、PUT
、DELETE
のそれぞれにマッピングされています。
RESTベース・システムの重要な特性は、ステートレスであるということです。サーバーは、クライアント・オブジェクトの状態の追跡や管理を行いません。RESTベースのサーバーに対して実行される各操作はアトミックです。それ自体が1つのトランザクションと考えられます。標準的なRESTベースのシステムでは、ロックや同時実行制御といったRDBMS環境で当然とされる多くの機能は、アプリケーションに管理が任されています。
RESTベースのシステムの主な利点は、そのサービスが、従来のプログラミング言語(C、C#、C++、JAVA、PL/SQLなど)および最新のスクリプティング言語(JavaScript、Perl、Python、Rubyなど)など、現代のプログラミング・プラットフォームのほとんどすべてから使用できることです。
関連項目:
『Principled Design of the Modern Web Architecture(最新Webアーキテクチャの原則に基づいた設計)』Roy T.Fielding and Richard N.Taylor
RESTベースのアプリケーションでは、通常は、ドキュメント・コレクションを使用して状態が維持されます。
ドキュメント・コレクションでは、各ドキュメントは一意の識別子を持ちます。通常、識別子はドキュメントの作成時にサーバーによって割り当てられますが、クライアント割当ての識別子も使用できます。ドキュメント識別子はメタデータ(個々のドキュメントについてのデータ)です。ドキュメント・コレクションでドキュメントごとに追跡できるその他のメタデータとして、それが作成された日付と時間および最後に変更された日付と時間があります。
RESTのためのSODAでは、RESTアーキテクチャ・スタイルを実装し、Oracle Databaseが管理するドキュメント・コレクションに対してドキュメントの格納や取得を行うことができるHTTPベースのサービスが提供されます。
APIには、実行できる次のようなシンプルな操作のセットが定義されています。
利用可能なコレクションのセットのリスト
コレクションの作成
コレクションのドロップ
コレクションへのドキュメントの挿入
コレクションからのドキュメントの取得
コレクション内のドキュメントの更新
コレクションからのドキュメントの削除
コレクションのコンテンツのリスト
コレクションの検索
アプリケーションでは、このAPI操作を使用し、アプリケーションのオブジェクトや状態の永続化に使用するJSONオブジェクトを作成および操作できます。JSONドキュメントを生成するため、アプリケーションでJSONのシリアライズ技術を使用できます。アプリケーションでドキュメント・オブジェクトを取得すると、JSONパーサーにより、それがアプリケーション・オブジェクトに変換されます。
関連項目:
RESTのためのSODAで定義された操作の詳細は、RESTのためのSODAのHTTP操作を参照
RESTのためのSODAのインストールについて、すべての手順を説明します。
RESTのためのSODAをインストールするには、次の手順を実行します。
Oracle Database 12c リリース1 (12.1.0.2)、およびMerge Label Request(MLR)バンドル・パッチ20885778がインストールされていることを確認します。(パッチ20885778によりパッチ20080249は廃止されました。)
パッチは、My Oracle Support(https://support.oracle.com
)から入手してください。「パッチと更新版」タブを選択します。パッチ番号20885778を検索するか、または次のURL: https://support.oracle.com/rs?type=patch&id=20885778
に直接アクセスします。
データベースを起動します。
Oracle REST Data Services(ORDS)をダウンロードし、zipファイルを解凍します。
手順の詳細は、『Oracle REST Data Servicesインストレーション、構成および開発ガイド』を参照してください。
ORDSを構成します。
データベースが標準ポート1521を使用している場合:
java -jar ords.war install
データベースが非標準ポート(1521を除くすべてのポート)を使用している場合:
java -jar ords.war install advanced
注意:
入力を求められたら、次のように指定します。
Oracle REST Data Servicesスキーマの検証/インストールの手順をスキップしないでください。
PL/SQLゲートウェイを構成する手順をスキップします。
Application ExpressのRESTfulサービスのデータベース・ユーザーを構成するステップをスキップします。
スタンドアロン・サーバーの起動を拒否します。
詳細は、『Oracle REST Data Servicesインストレーション、構成および開発ガイド』を参照してください。
ORDSからアクセスするスキーマに接続します。
次のSQLコマンドを実行して、スキーマ内でORDSを有効にします。
EXEC ords.enable_schema; COMMIT;
ロールSODA_APP
を、手順6で有効にしたデータベース・スキーマ(ユーザー・アカウント) schema
に付与します。
GRANT SODA_APP TO schema;
開発環境の場合のみ、次の手順を実行します。
デフォルトのセキュリティ制約を削除します。
BEGIN ords.delete_privilege_mapping( 'oracle.soda.privilege.developer', '/soda/*'); COMMIT; END;
これにより、サービスへの匿名アクセスが有効になるため、本番システムではお薦めしません。セキュリティの詳細は、「セキュリティ」を参照してください。
スタンドアロン・モードでORDSを起動します。
java -jar ords.war standalone
詳細は、『Oracle REST Data Servicesインストレーション、構成および開発ガイド』を参照してください。
注意:
セキュリティを無効にしてスタンドアロン・モードでORDSを実行するのは、本番環境ではお薦めしません。
Webブラウザで、次のページを開きます。
http://localhost:8080/ords/schema/soda/latest/
ここで、schema
は、手順 6でORDSを有効にしたスキーマの小文字の名前です。インストールが成功した場合は、次のように表示されます。
{"items":[],"more":false}
関連項目:
『Oracle REST Data Servicesインストレーション、構成および開発ガイド』
実行可能な例を使用して、RESTのためのSODAの基本的な操作について段階的に説明されています。例では、コマンドライン・ツールcURLを使用してサーバーにRESTリクエストを送信します。
例は、RESTのためのSODAのインストールの説明のとおりにORDSが起動され、schema
でORDSが有効化されていることを前提としています。
いくつかの例では、インストール手順3でダウンロードしたzipファイルに含まれているサンプルのJSONドキュメントを使用します。それらはORDS_HOME/examples/soda/getting-started
ディレクトリにあります。
関連項目:
コマンドライン・ツールcURLの詳細は、http://curl.haxx.se/
を参照
『Oracle REST Data Servicesインストレーション、構成および開発ガイド』
手順
新規コレクションの作成について例を示します。
新しいコレクションを作成するには、このコマンドを使用します。ここでのMyCollection
は、コレクションの名前です。
curl -i -X PUT http://localhost:8080/ords/schema/soda/latest/MyCollection
このコマンドは、PUT
リクエストをURL http://localhost:8080/ords/
schema
/soda/latest/MyCollection
で送信し、MyCollection
という名前のコレクションを作成します。-i
コマンドライン・オプションにより、cURLで出力にHTTPレスポンス・ヘッダーが含まれるようになります。操作が成功した場合、出力は次のようになります。
HTTP/1.1 201 Created Cache-Control: private,must-revalidate,max-age=0 Location: http://localhost:8080/ords/schema/soda/latest/MyCollection/ Content-Length: 0
レスポンス・コード201は、操作が成功したことを示します。新規コレクションを生成するPUT
操作(PUT collection
操作)は、レスポンス・ボディを戻しません。
PUT collection
操作が成功すると、新規コレクションを保存するデータベース表が作成されます。この表の詳細を確認する1つの方法としては、次のようにSQL*Plusのコマンドdescribe
を使用します。
SQL> describe "MyCollection"
Name Null? Type
----------------------------------------- -------- ----------------------------
ID NOT NULL VARCHAR2(255)
CREATED_ON NOT NULL TIMESTAMP(6)
LAST_MODIFIED NOT NULL TIMESTAMP(6)
VERSION NOT NULL VARCHAR2(255)
JSON_DOCUMENT BLOB
この表は、デフォルトのコレクションの構成を反映しています。カスタムのコレクション構成を作成するには、PUT
操作のボディとしてコレクション仕様を指定します。コレクション仕様の詳細は、「コレクション仕様」を参照してください。
注意:
コレクションをドロップするには、「コレクションの削除」の説明に従って続行します。SQLを使用して、コレクションの基礎となるデータベース表をドロップしないでください。コレクションには、コレクション表に格納されたドキュメントに加えて、永続化されたメタデータがあります。
関連項目:
この操作の詳細は、「PUT collection」を参照
利用可能なコレクションのリストについて例を示します。
schema
内の利用可能なコレクションのリストを取得するには、次のコマンドを実行します。
curl -X GET http://localhost:8080/ords/schema/soda/latest
それにより、URL http://localhost:8080/ords/
schema
/soda/latest
でGET
リクエストが送信され、このレスポンス・ボディが返されます。
{ "items" : [ { "name":"MyCollection", "properties": { "schemaName":"SCHEMA", "tableName":"MyCollection", ... } "links" : [ { "rel" : "canonical", "href" :"http://localhost:8080/ords/schema/soda/latest/MyCollection" } ] } ], "more" : false }
レスポンス・ボディには、schema
内の使用可能なすべてのコレクションが含まれます。この場合は、コレクションMyCollection
のみとなります。
GET collection
操作が成功すると、レスポンス・コード200が戻ります。レスポンス・ボディは、それぞれのコレクションのコレクション仕様を含む、利用可能なコレクションの配列が含まれたJSONオブジェクトです。
関連項目:
コレクションの削除について例を示します。
MyCollection
を削除するには、次のコマンドを実行します。
curl -i -X DELETE http://localhost:8080/ords/schema/soda/latest/MyCollection
このコマンドは、DELETE
リクエストをURL http://localhost:8080/ords/
schema
/soda/latest/MyCollection
で送信し、次のレスポンスが戻されます。
HTTP/1.1 200 OK Cache-Control: private,must-revalidate,max-age=0 Content-Length: 0
レスポンス・コード200は、操作が成功したことを示します。コレクションを削除するDELETE
操作(DELETE collection
操作)は、レスポンス・ボディを戻しません。
コレクションが削除されたことを確認するには、次のようにschema
で利用可能なコレクションのリストを取得します。
curl -X GET http://localhost:8080/ords/schema/soda/latest
MyCollection
が削除されていれば、このコマンドは次のレスポンスを戻します。
{ "items" : [], "more" : false }
次のステップで使用できるように、MyCollection
を再度作成します。
curl -X PUT http://localhost:8080/ords/schema/soda/latest/MyCollection
コレクションへのドキュメントの挿入について例を示します。
この例では、ダウンロードに含まれているpo.json
ファイルを使用します。ファイルには、注文書を含むJSONドキュメントが含まれています。MyCollection
にこのJSONドキュメントをロードするには、次のコマンドを実行します。
curl -X POST --data-binary @po.json -H "Content-Type: application/json"
http://localhost:8080/ords/schema/soda/latest/MyCollection
このコマンドは、POST
リクエストをURL http://localhost:8080/ords/
schema
/soda/latest/MyCollection
で送信します。出力は、次のようになります。
{ "items" : [ { "id" : "2FFD968C531C49B9A7EAC4398DFC02EE", "etag" : "C1354F27A5180FF7B828F01CBBC84022DCF5F7209DBF0E6DFFCC626E3B0400C3", "lastModified":"2014-09-22T21:25:19.564394Z", "created":"2014-09-22T21:25:19.564394Z" } ], "hasMore" : false, "count" : 1 }
POST object
操作が成功すると、レスポンス・コード200が戻されます。レスポンス・ボディは、挿入したドキュメントについての、コレクションに挿入したときにサーバーによってドキュメントに割り当てられた識別子、現在のETagおよび最終変更タイム・スタンプが含まれるJSONドキュメントです。
注意:
ドキュメントを取得する場合、取得に使用するドキュメント識別子(フィールドid
の値)をコピーします。
関連項目:
この操作の詳細は、「POST object」を参照
コレクションからのドキュメントの取得について例を示します。
コレクションへのドキュメントの挿入で挿入したドキュメントを取得するには、このコマンドを実行します。ここでのid
は、ドキュメント挿入時にコピーしたドキュメント識別子です。
curl -X GET http://localhost:8080/ords/schema/soda/latest/MyCollection/id
GET document
操作が成功すると、レスポンス・コード200が戻されます。レスポンス・ボディには、取得されたドキュメントが含まれています。
id
がMyCollection
に存在しない場合のレスポンス・コードは404で、id
を次のような識別子に変更すれば確認できます。
curl -X GET http://localhost:8080/ords/schema/soda/latest/MyCollection/2FFD968C531C49B9A7EAC4398DFC02EF
{
"type" : "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
"status" : 404,
"title" : "Key 2FFD968C531C49B9A7EAC4398DFC02EF not found in collection MyCollection.",
"o:errorCode" : "REST-02001"
}
コレクションからのドキュメントの削除について例を示します。
コレクションからのドキュメントの取得で取得したドキュメントをMyCollection
から削除するには、次のコマンドを実行します(ここでのid
は、ドキュメント識別子です)。
curl -i -X DELETE http://localhost:8080/ords/schema/soda/latest/MyCollection/id
このコマンドは、DELETE
リクエストをURL http://localhost:8080/ords/
schema
/soda/latest/MyCollection/
id
で送信し、次のレスポンスが戻されます。
HTTP/1.1 200 OK Cache-Control: private,must-revalidate,max-age=0 Content-Length: 0
レスポンス・コード200は、操作が成功したことを示します。コレクションからオブジェクトを削除するDELETE
操作(DELETE object
操作)は、レスポンス・ボディを戻しません。
ドキュメントのJSON配列からコレクションへの一連のドキュメントの一括挿入について例を示します。この一括挿入操作はPOST
array insertとも呼ばれます。
この例では、ダウンロードに含まれているPOList.json
ファイルを使用します。ファイルには、70個の注文書のJSON配列が含まれています。コレクションMyCollection
にそれらの注文書をロードするには、次のコマンドを実行します。
curl -X POST --data-binary @POList.json -H "Content-Type: application/json" http://localhost:8080/ords/schema/soda/latest/MyCollection?action=insert
パラメータ値action=insert
により、配列は単一のドキュメントとしてではなくドキュメントのセットとして挿入されます。
このコマンドは、POST
リクエストをURL http://localhost:8080/ords/
schema
/soda/latest/MyCollection
で送信し、出力は次のようになります。
{ "items" : [ { "id" : "6DEAF8F011FD43249E5F60A93B850AB9", "etag" : "49205D7E916EAED914465FCFF029B2795885A1914966E0AE82D4CCDBBE2EAF8E", "lastModified" : "2014-09-22T22:39:15.546435Z", "created" : "2014-09-22T22:39:15.546435Z" }, { "id" : "C9FF7685D48E4E4B8641D8401ED0FB68", "etag" : "F3EB514BEDE6A6CC337ADA0F5BE6DEFC5D451E68CE645729224BB6707FBE1F4F", "lastModified" : "2014-09-22T22:39:15.546435Z", "created":"2014-09-22T22:39:15.546435Z" }, ... ], "hasMore":false, "count":70 }
POST
array insert操作が成功すると、レスポンス・コード200が戻されます。レスポンス・ボディは挿入した各ドキュメントの識別子、現在のETagおよび最終変更タイム・スタンプが含まれるJSONドキュメントです。
自分のPOST
array insert操作から戻されたid
フィールド値をコピーします(前述の例の値ではありません)。SQL*PlusまたはSQL Developerを使用してコレクションを問合せ、コピーした値をidentifier
のかわりに使用します。
SELECT json_value(json_document FORMAT JSON, '$.Reference')
FROM "MyCollection" WHERE id = 'identifier';
JSON_VALUE(JSON_DOCUMENTFORMATJSON,'$.REFERENCE')
--------------------------------------------------------------------------------
MSULLIVA-20141102
注意:
MyCollection
という表名は大文字と小文字が混在するため、SQLのSELECT
文では引用符で囲まれた識別子として指定する必要があります(表名はコレクション名と同じ)。
MyCollection
には、JSONドキュメントをBLOB
列に保存するというデフォルトの構成があるため、SQL/JSON関数json_value
を使用する場合は、FORMAT JSON
を含める必要があります。単純化されたJSON構文は使用できません。
GET
操作の使用によるコレクション内のドキュメントのリストについて例を示します。
結果を制御するパラメータを使用できます。たとえば、次の操作が可能です。
戻されるドキュメントの数を制限する
ドキュメントの識別子(キー)のみ、ドキュメントのコンテンツのみ、またはキーとコンテンツの両方を戻す
キーまたは最終変更タイム・スタンプに基づいて、ドキュメントの範囲を戻す
戻されるドキュメントのリストの順序を指定する
MyCollection
のドキュメントをリストするには、そのコンテンツではなく、キーやその他のメタデータを戻すように、次のコマンドを実行します。
curl -X GET http://localhost:8080/ords/schema/soda/latest/MyCollection?fields=id
このコマンドの出力は次のようなものになります。
{ "items" : [ { "id" : "023C4A6581D84B71A5C0D5D364CE8484", "etag":"3484DFB604DDA3FBC0C681C37972E7DD8C5F4457ACE32BD16960D4388C5A7C0E", "lastModified" : "2014-09-22T22:39:15.546435Z", "created":"2014-09-22T22:39:15.546435Z" }, { "id" : "06DD0319148E40A7B8AA48E39E739184", "etag" : "A19A1E9A3A38B1BAE3EE52B93350FBD76309CBFC4072A2BECD95BCA44D4849DD", "lastModified" : "2014-09-22T22:39:15.546435Z", "created" : "2014-09-22T22:39:15.546435Z" }, ... ], "hasMore" : false, "count" : 70, "offset":0, "limit":100, "totalResults":70 }
GET collection
操作が成功すると、レスポンス・コード200が戻り、レスポンス・ボディはコレクション内のドキュメントをリストするJSONドキュメントです。コレクションが空の場合は、レスポンス・ボディは空のitems
配列です。
MyCollection
のドキュメントを最大10個までリストし、キー、コンテンツ、およびその他のメタデータを戻すには、次のコマンドを実行します。
curl -X GET "http://localhost:8080/ords/schema/soda/latest/MyCollection?fields=all&limit=10"
このコマンドの出力は次のようなものになります。
{
"items": [ ... ],
"hasMore" : true,
"count" : 10,
"offset" : 0,
"limit" : 10,
"links" : [{
"rel" : "next",
"href" :
"http://localhost:8080/ords/schema/soda/latest/MyCollection?offset=10&limit=10"
}]
}
注意:
ドキュメントのコンテンツを含めると、レスポンス・ボディはかなり大きくなります。後でコンテンツが必要になる場合にのみ、レスポンス・ボディにコンテンツを含めることをお薦めします。レスポンス・ボディからコンテンツを取得すると、サーバーから取得するより効率的です。
レスポンス・ボディ内のメタデータは、10個のドキュメントがリクエストされたこと("limit" : 10
)、10個のドキュメントが戻されたこと("count" : 10
)、さらに多くのドキュメントが利用可能であること("hasMore" : true
)を示しています。"links"."href"
フィールドのURLは、ドキュメントの次のセットを取得するために使用できます。
サーバーによってコレクションから戻されるドキュメントの最大数は、次によって制御されます。
URLパラメータlimit
構成パラメータsoda.maxLimit
およびsoda.defaultLimit
注意:
ドキュメントを更新する場合、更新に使用するドキュメント識別子(フィールドid
の値)をコピーします。
関連項目:
コンテンツに基づいてドキュメントをリストする方法は、「フィルタ仕様を使用したコレクションからのドキュメントの選択」を参照
構成パラメータsoda.maxLimit
およびsoda.defaultLimit
の詳細は、『Oracle REST Data Servicesインストレーション、構成および開発ガイド』を参照
コレクション内のドキュメントの更新、つまり、新しいバージョンとの置換について例を示します。この場合は、PUT
操作を使用します。
存在しないドキュメントに対するPUT
操作の動作は、コレクションに使用されるキー割当て方法によって異なります。
コレクションがサーバーによって割り当てられたキーを使用している場合(コレクションMyCollection
と同様)、存在しないドキュメントを更新しようとすると(つまり、コレクション内のドキュメントのものではないキーを指定すると)エラーが発生します。
コレクションがクライアントによって割り当てられたキーを使用する場合は、存在しないドキュメントを更新しようとすると、指定されたキーを持つ新規ドキュメントがコレクションに挿入されます。
MyCollection
からドキュメントを取得するには、次のコマンドを実行します(ここでのid
は、コレクション内のドキュメントのリストでコピーしたドキュメント識別子です)。
curl -X GET http://localhost:8080/ords/schema/soda/latest/MyCollection/id
このコマンドは、取得したドキュメントを出力します。
ダウンロードに含まれるpoUpdated.json
ファイルのコンテンツでこのドキュメントを更新するには、次のコマンドを実行します。
curl -i -X PUT --data-binary @poUpdated.json -H "Content-Type: application/json" http://localhost:8080/ords/schema/soda/latest/MyCollection/id
このコマンドの出力は次のようなものになります。
HTTP/1.1 200 OK
Cache-Control: no-cache,must-revalidate,no-store,max-age=0
ETag: A0B07E0A6D000358C546DC5D8D5059D9CB548A1A5F6F2CAD66E2180B579CCB6D
Last-Modified: Mon, 22 Sep 2014 16:42:35 PDT
Location: http://localhost:8080/ords/schema/soda/latest/MyCollection/023C4A6581D84B71A5C0D5D364CE8484/
Content-Length: 0
レスポンス・コード200は、操作が成功したことを示しています。コレクション内のドキュメントを更新するPUT
操作(PUT object
操作)の成功は、レスポンス・ボディを戻しません。
更新されたドキュメントを確認するには、次のコマンドを再実行します。
curl -X GET http://localhost:8080/ords/schema/soda/latest/MyCollection/id
このコマンドは、次の出力を戻します。
{ "PONumber": 1, "Content" : "This document has been updated...." }
フィルタ仕様、つまり例による問合せ(QBE)を使用した、コレクションからドキュメントを選択するための問合せ条件の定義について例を示します。
例では、インストール手順3でダウンロードしたzipファイルに含まれているQBE.*.json
ファイルを使用します。それらは、ORDS_HOME/examples/soda/getting-started
ディレクトリにあります。
関連項目:
フィルタ仕様およびQBEの詳細は、Oracle Database JavaのためのSODA開発者ガイドを参照してください
QBE.1.json
ファイル内の例による問合せ(QBE)では、フィールドUser
の値がTGATES
である9個のドキュメントのリストが返されます。
次に、QBE.1.json
ファイル内の問合せを示します。
{ "User" : "TGATES" }
問合せを実行するには、次のコマンドを実行します。
curl -X POST --data-binary @QBE.1.json -H "Content-Type: application/json" http://localhost:8080/ords/schema/soda/latest/MyCollection?action=query
POST query
操作が成功すると、レスポンス・コード200および問合せ基準を満たすドキュメントのリストが戻されます。
コマンドにはfields
パラメータがないので、デフォルト値fields=all
が適用され、レスポンス・ボディには各ドキュメントのメタデータとコンテンツの両方が含まれています。
注意:
ドキュメントのコンテンツを含めると、レスポンス・ボディはかなり大きくなります。後の操作でコンテンツが必要になる場合にのみ、レスポンス・ボディにコンテンツを含めることをお薦めします。レスポンス・ボディからコンテンツを取得すると、サーバーから取得するより効率的です。
他のQBE.*.json
ファイル内の問合せを実行するには、前述のものと同様のコマンドを実行します。
QBE.2.json
ファイル内の例による問合せ(QBE)では、フィールドUPCCode
の値が13023015692
と等しいドキュメントが選択されます。UPCCode
はPart
オブジェクトのフィールドで、PartオブジェクトはLineItems
配列のフィールドです。LineItems
に配列のオフセットが指定されていないので、問合せは配列のすべての要素を検索します。
次に、QBE.2.json
ファイル内の問合せを示します。
{ "LineItems.Part.UPCCode" : "13023015692" }
注意:
問合せ内のキーワード"$eq"
は、暗黙の指定です。詳細は、Oracle Database JavaのためのSODA開発者ガイドを参照してください。
QBE.3.json
ファイル内の例による問合せ(QBE)では、オブジェクトLineItems
内のフィールドItemNumber
の値が4より大きいドキュメントが選択されます。キーワード"$gt"
は必要です。
次に、QBE.3.json
ファイル内の問合せを示します。
{ "LineItems.ItemNumber" : { "$gt" : 4 }}
RESTのためのSODAのHTTP操作について説明しています。
表1-1に、RESTのためのSODAによって提供されるHTTP操作をまとめます。操作の完全な説明を参照するには、左の列のリンクをクリックします。
表1-1 RESTのためのSODAのHTTP操作
操作 | 説明 |
---|---|
スキーマ内のコレクション名の一部またはすべてを取得します。 |
|
サブセットを指定するパラメータを使用して、コレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるセットをページングできます。 |
|
指定したオブジェクトをコレクションから取得します。 |
|
存在しない場合は、コレクションを作成します。 |
|
アップロードしたオブジェクト(通常は新規バージョン)で指定したオブジェクトを置き換えます。 コレクションがクライアントによって割り当てられたキーを持ち、アップロードしたオブジェクトがコレクションに存在しない場合は、 |
|
コレクションを削除します。 |
|
指定したオブジェクトをコレクションから削除します。 |
|
アップロードしたオブジェクトを指定したコレクションにPUTし、キーを割り当ててそのキーを戻します。コレクションは、サーバーが割り当てるキーを使用する必要があります。 |
|
サブセットを指定するフィルタを使用して、コレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるセットはページングできません。 |
|
指定されたコレクションにオブジェクトの配列を挿入し、キーを割り当ててそのキーを戻します。 |
|
コレクションからオブジェクトのすべて、またはそのサブセットを削除します。 |
RESTのためのSODAのHTTP操作は、Universal Resource Identifier (URI)によって指定されます。
URIの形式は、次のとおりです。
/ords/schema/soda/[version/[collection/[{key/|?action=action}]]]
説明:
ords
は、Oracle REST Data Services(ORDS)リスナーのディレクトリで、RESTのためのSODAはそのコンポーネントです。
schema
は、RESTのためのSODAのエンド・ポイントとして構成されたOracle Databaseスキーマの名前です。
soda
は、ORDS内のテンプレートとしてマッピングしたときにOracle Database JSONサービスに付けた名前です。
version
は、soda
のバージョン番号です。
collection
は、schema
内に保存されるオブジェクトのセットの名前です。
通常、オブジェクトはJSONドキュメントですが、Multipurpose Internet Mail Extensions(MIME)タイプ(イメージ、オーディオ、ビデオなど)も可能です。
JSONドキュメントは、テキストJSONとして表現されます。
通常、アプリケーションは、コレクションを使用して特定のタイプのオブジェクトのすべてのインスタンスを保持します。このように、コレクションはリレーショナル・データベースの表に類似しています。1つの列にキーを格納し、別の列にコンテンツを格納します。
key
は、collection
内のオブジェクトを一意に識別する文字列です。
指定されたオブジェクトは、そのキーによって指定されています。
action
は、query
、index
、unindex
、insert
、update
またはdelete
のいずれかです。
RESTのためのSODAのHTTP操作により情報やオブジェクトが戻される場合、レスポンス・ボディでこれが行われます。
GET object操作では、レスポンス・ボディは単一のオブジェクトです。
表1-2に、レスポンス・ボディに表示されるフィールドのリストとその説明を示します。
表1-2 レスポンス・ボディに表示されるフィールド
フィールド | 説明 |
---|---|
|
コレクション内のオブジェクト(通常はJSONドキュメント)を一意に識別する文字列。 |
|
HTTPエンティティ・タグ(ETag) - チェックサムまたはバージョン。 |
|
作成日のタイム・スタンプ。 |
|
最終変更のタイム・スタンプ |
|
オブジェクトのコンテンツ(JSONオブジェクトにのみ適用)。 |
|
HTTPコンテンツ・タイプ(非JSONオブジェクトにのみ適用)。 |
|
HTTPコンテンツ長(非JSONオブジェクトにのみ適用)。 |
|
その操作により検索または作成された1つ以上のコレクションまたはオブジェクトのリスト。このフィールドには、表1-3に示すフィールドが続きます。 |
操作がオブジェクトを作成または戻す場合、レスポンス・ボディに表1-3に示すフィールドを追加できます。追加のフィールドはitems
フィールドの後に現れます。
表1-3 オブジェクトを戻す操作のレスポンス・ボディの追加フィールド
フィールド | 説明 |
---|---|
|
コレクションの名前。このフィールドはGET schemaのレスポンス・ボディにのみ表示されます。 |
|
コレクションのプロパティ。このフィールドはGET schemaのレスポンス・ボディにのみ表示されます。 |
|
|
|
サーバーで設定されたコレクション(行)の最大数の制限。 |
|
戻されるオブジェクトの最初を示すオフセット(既知の場合)。 |
|
戻されるオブジェクトの数。これは、POST bulk deleteのレスポンス・ボディにのみ表示されるフィールドです。 |
|
コレクション内のオブジェクトの数(要求した場合)。 |
|
|
例1-1は、25個のオブジェクトを戻すレスポンス・ボディの構造を示しています。1番目のオブジェクトはJSONオブジェクトで、2番目はjpeg
イメージです。これらのオブジェクトを含むコレクションには、追加のオブジェクトが含まれています。
例1-1 レスポンス・ボディ
{ "items" : [ { "id" : "key_of_object_1
", "etag" : "etag_of_object_1
", "lastModified" : "lastmodified_timestamp_of_object_1
", "value" : {object_1
} }, { "id" : "key_of_object_2
", "etag" : "etag_of_object_2
", "lastModified" : "lastmodified_timestamp_of_object_2
", "mediaType" : "image/jpeg", "bytes" : 1234 }, ... ], "hasMore" : true, "limit" : 100, "offset" : 50, "count" : 25 "links" : [ ... ] }
GET
schemaは、スキーマ内のコレクション名のすべて、またはそのサブセットを取得します。
関連項目:
GET
schemaのURLパターンを説明します。
/ords/schema/soda/version/
パラメータを指定しなければ、GET schema
によりschema
内のすべてのコレクション名が取得されます。
パラメータ | 説明 |
---|---|
|
リストするコレクション名の数を |
|
取得を開始する |
GET
schemaのレスポンス・コードを説明します。
200
成功 - レスポンス・ボディには、スキーマ内のコレクションの名前とプロパティが名前の順序で含まれています。次に例を示します。
{ "items" : [ {"name" : "employees", "properties" : {...} }, {"name" : "departments", "properties" : {...} }, ... ], "hasMore" : false }
hasMore
がtrue
の場合、コレクション名の次のセットを取得するには、fromID=
last_returned_collection
と指定します。(前述の例では、last_returned_collection
は"regions"
です。)
404
スキーマが見つからないか、アクセスが許可されていないかのいずれかです。
GET
collectionは、サブセットを指定するパラメータを使用してコレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるオブジェクトのセットをページングできます。
関連項目:
POST queryは、パラメータのかわりにフィルタを使用してコレクションからオブジェクトのすべてまたはサブセットを取得します。戻されるオブジェクトのセットはページングできません。
GET
collectionのURLパターンを説明します。
/ords/schema/soda/version/collection/
パラメータを指定しなければ、GET collection
により、collection
からすべてのオブジェクト(キーとコンテンツの両方)が取得され、collection
内のオブジェクトの数は戻されません。
注意:
コレクション内が非JSONオブジェクトの場合は、GET collection
により、コンテンツのかわりにメディア・タイプおよびバイト単位のサイズ(既知の場合)が戻されます。
パラメータ | 説明 |
---|---|
|
リストするオブジェクトの数を |
|
最初のオブジェクトを取得する前に |
|
オブジェクトの
|
|
コレクション内のオブジェクトの数を戻します。(注意: 非効率) |
|
|
|
|
|
|
|
|
|
|
|
|
GET
collectionのレスポンス・コードを説明します。
200
成功 - レスポンス・ボディには、collection
の指定したオブジェクトが含まれています(fields=id
を指定した場合はキーのみ)。次に例を示します。
{ "items" : [ { "id" : "key_of_object_1
", "etag" : "etag_of_object_1
", "lastModified" : "lastmodified_timestamp_of_object_1
", "value" : {object_1
} }, { "id" : "key_of_object_2
", "etag" : "etag_of_object_2
", "lastModified" : "lastmodified_timestamp_of_object_2
", "value" : {object_2
} }, { "id" : "key_of_object_3
", "etag" : "etag_of_object_3
", "lastModified" : "lastmodified_timestamp_of_object_3
", "mediaType" : "image/jpeg", "bytes" : 1234 }, ... ], "hasMore" : true, "limit" : 100, "offset" : 50, "count" : 25 "links" : [ ... ] }
hasMore
がtrue
の場合、次のオブジェクトのセットを取得するには、適切なパラメータを使用して操作を繰り返します。次に例を示します。
offset=
n
(レスポンス・ボディにオフセットが含まれている場合)
toID=
last_returned_key
またはbefore=
last_returned_key
(レスポンス・ボディにdescending=true
が含まれている場合)
fromID=
last_returned_key
またはafter=
last_returned_key
(レスポンス・ボディにdescending=true
が含まれている場合)
links
の詳細は、「GET collectionのリンク配列」を参照してください
401
コレクションの読取りアクセスが許可されていません。
404
コレクションが見つかりませんでした。
GET
collectionのlinks
配列を説明します。
links
配列の存在およびそのコンテンツは、GET collection
操作のパラメータによって決定されるモードに依存します。
links
配列が存在する場合は、戻される各オブジェクトの要素が格納されています。各要素には、そのオブジェクトから他のオブジェクトへのリンクが含まれています。次のリンクがあります。
first
は、そのオブジェクトからコレクション内の最初のオブジェクトにリンクします。
prev
は、そのオブジェクトからコレクション内の前のオブジェクトにリンクします。
next
は、そのオブジェクトからコレクション内の次のオブジェクトにリンクします。
prev
およびnext
リンクを使用し、戻されたオブジェクトのセットをページングできます。
表1-4に、GET collection
のパラメータによりどのようにモードが決定され、links
配列の存在とそのコンテンツが決定されるのかを示します。
表1-4 GET collectionのパラメータとモードおよびリンク配列の関係
パラメータ | モード | リンク配列 |
---|---|---|
|
キーのみ |
存在しません(他のパラメータに関係なく)。 |
|
オフセット |
戻される各オブジェクトの要素が格納されます。各要素には、注意書きのある場合を除き、次のリンクが含まれます。
|
|
キー |
戻される各オブジェクトの要素が格納されます。各要素には、注意書きのある場合を除き、次のリンクが含まれます。
|
|
タイムスタンプ |
存在しません。 |
GET
objectは、指定されたコレクションから指定されたオブジェクトを取得します。
関連項目:
GET
objectのリクエスト・ヘッダーを説明します。
操作GET object
は、次のオプションのリクエスト・ヘッダーを受け入れます。
ヘッダー | 説明 |
---|---|
|
|
|
オブジェクトの |
GET
objectのレスポンス・コードを説明します。
200
成功 - レスポンス・ボディにはURLパターンで識別されたオブジェクトが含まれます。
204
オブジェクトのコンテンツはnullです。
304
etag
オブジェクトと一致する変更日またはチェックサムから、どのオブジェクトも変更されていません(「GET objectのリクエスト・ヘッダー」を参照)。
401
コレクションまたはオブジェクトの読取りアクセスが許可されていません。
404
コレクションまたはオブジェクトが見つかりませんでした。
PUT
collectionは、存在しない場合はコレクションを作成します。
関連項目:
PUT
collectionのURLパターンを説明します。
/ords/schema/soda/version/collection/
パラメータはありません。
PUT
objectは、指定されたコレクション内の指定されたオブジェクトをアップロードされたオブジェクト(通常、新規バージョン)で置き換えます。コレクションがクライアントによって割り当てられたキーを持ち、アップロードしたオブジェクトがコレクションに存在しない場合は、PUT
はアップロードしたオブジェクトをコレクションに挿入します。
関連項目:
DELETE
collectionは、コレクションを削除します。
コレクションからすべてのオブジェクトを削除し、コレクション自体は削除しない場合は、POST bulk deleteを使用します。
関連項目:
DELETE
collectionのURLパターンを説明します。
/ords/schema/soda/version/collection/
パラメータはありません。
DELETE
objectは、指定されたコレクションから指定されたオブジェクトを削除します。
関連項目:
DELETE
objectのURLパターンを説明します。
/ords/schema/soda/version/collection/key/
パラメータはありません。
POST
objectは、アップロードされたオブジェクトを指定されたコレクションに挿入し、キーを割り当ててそのキーを戻します。コレクションは、サーバーによって割り当てられるキーを使用する必要があります。
コレクションが、クライアントによって割り当てられるキーを使用する場合は、PUT objectを使用します。キーの割当て方法の詳細は、「キーの割当て方法」を参照してください。
関連項目:
POST
objectのレスポンス・コードを説明します。
201
成功 - オブジェクトはコレクション内にあり、レスポンス・ボディにはサーバーによって割当てられたキーが含まれ、その他の情報が含まれている可能性もあります。次に例を示します。
{ "items" : [ { "id" : "key", "etag" : "etag", "lastModified" : "timestamp" "created" : "timestamp" } ], "hasMore" : false }
202
オブジェクトは受入れられて非同期挿入のキューに入れられ、レスポンス・ボディにはサーバーによって割当てられたキーが含まれています。
401
コレクションへの挿入が許可されていません。
405
コレクションは読取り専用です。
501
サポートされていない操作です(たとえば、サーバーによるキー割当てではない)。
POST
queryは、サブセットを指定するフィルタを使用してコレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるオブジェクトのセットはページングできません。
関連項目:
GET collectionは、フィルタのかわりにパラメータを使用してコレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるオブジェクトのセットをページングできます。
POST
queryのURLパターンを説明します。
/ords/schema/soda/version/collection?action=query
パラメータは、注意書きのある場合を除きオプションです。
パラメータ | 説明 |
---|---|
|
必須。アクションの種類を指定します。 |
|
戻されるオブジェクトの数を |
|
オブジェクトを戻す前に、 |
|
オブジェクトの |
POST
queryのリクエスト・ボディからフィルタ仕様オブジェクトを省略した場合、操作ではコレクション内のすべてのオブジェクトが取得されます。
関連項目:
SODAフィルタ仕様の詳細は、Oracle Database JavaのためのSODA開発者ガイドを参照してください。
POST
array insertは、オブジェクトの配列を指定されたコレクションに挿入し、キーを割り当ててそのキーを戻します。
関連項目:
POST
array insertのURLパターンを説明します。
/ords/schema/soda/version/collection?action=insert
パラメータ | 説明 |
---|---|
|
必須。アクションの種類を指定します。 |
POST
array insertのレスポンス・コードを説明します。
200
成功 - レスポンス・ボディには、挿入されたオブジェクトの配列が割当てられたキーとともに含まれます。次に例を示します。
{ "items" : [ { "id" : "12345678", "etag" : "...", "lastModified" : "..." "created" : "..." }, { "id" : "23456789", "etag" : "...", "lastModified" : "..." "created" : "..." } ], "hasMore" : false }
401
コレクションへの挿入が許可されていません。
404
コレクションが見つかりませんでした。
405
コレクションは読取り専用です。
POST
bulk deleteは、サブセットを指定するフィルタを使用して指定されたコレクションからオブジェクトのすべて、またはそのサブセットを削除します。
注意:
コレクションからすべてのオブジェクトを削除しても、空のコレクションは存在しています。コレクション自体を削除するには、DELETE collectionを使用します。
POST
bulk deleteのURLパターンを説明します。
次のいずれかです。
/ords/schema/soda/version/collection?action=delete /ords/schema/soda/version/collection?action=truncate
パラメータ | 説明 |
---|---|
|
必須。サブセットを指定するオプションのフィルタを使用して |
|
必須。 |
警告:
action=delete
を指定し、フィルタ仕様を省略するか、またはフィルタ仕様が空の場合、その操作によりコレクションのすべてのオブジェクトが削除されます。
コレクション仕様は、コレクション・オブジェクトの基礎となるOracleデータベースの表やビューについての情報を提供します。コレクションを作成するときに、表またはビューが作成されます。
注意:
コレクション仕様では、厳密なJSON構文を使用する必要があります。つまり、数値以外の各値を二重引用符で囲む必要があります。
表1-5に、コレクション仕様のフィールドおよび使用可能な値を説明します。
注意:
オプション列(作成日のタイム・スタンプ、最終変更タイム・スタンプ、バージョンまたはメディア・タイプ)のいずれかをコレクション仕様から省略した場合、その列は作成されません。少なくとも、コレクションにはキー列とコンテンツ列があります。
表1-5 コレクション仕様のフィールド
フィールド | 説明 | 使用可能な値 |
---|---|---|
|
コレクション・オブジェクトの基礎となる表またはビューを所有するスキーマのSQL名。 |
— |
|
コレクション・オブジェクトの基礎となる表またはビューのSQL名。 |
— |
|
キー列の名前。 |
デフォルト: |
|
キー列のSQLデータ型。 |
|
|
データ型が |
デフォルト:255 |
|
キーの割当て方法。 |
|
|
|
既存のデータベース順序の名前 |
|
コンテンツ列の名前。 |
デフォルト: |
|
コンテンツ列のSQLデータ型。 |
|
|
データ型がLOBではない場合のコンテンツ列の最大長。 |
デフォルト長は4000バイトです。 |
|
コンテンツ列の検証レベル。SQL条件の
|
|
|
コンテンツ列に格納されるSecureFilesの圧縮レベル。 |
|
|
コンテンツ列に格納されるSecureFilesのキャッシング。 |
|
|
コンテンツ列に格納されるSecureFilesの暗号化アルゴリズム。脚注 1 |
|
|
オプションの作成日のタイム・スタンプ列の名前。 この列はSQLデータ型 |
デフォルト: |
|
オプションの最終変更タイム・スタンプ列の名前。 この列はSQLデータ型 |
デフォルト: |
|
タイムスタンプ列の一意でないインデックスの名前。名前が指定されている場合、インデックスが作成されます。 |
|
|
オプションのバージョン(ETag)列の名前。 この列は、そのメソッドが 注意: メソッドが |
デフォルト: |
|
バージョン管理方法。 |
|
|
オプションのオブジェクトのメディア・タイプ列の名前。 この列は、SQLデータ型 |
|
|
読取り/書込みポリシー: |
|
脚注1
SecureFile暗号化でコレクションを作成する前に暗号化ウォレットを設定します。ALTER
SYSTEM
文のSET
ENCRYPTION
WALLET
句の詳細は、『Oracle Database SQL言語リファレンス』を参照してください。
例1-2は、基本となる表がHR.EMPLOYEES
であるオブジェクトのコレクション仕様です。
例1-2 コレクション仕様
{ "schemaName" : "HR", "tableName" : "EMPLOYEES", "contentColumn" : { "name" : "EMP_DOC", "sqlType" : "VARCHAR2", "maxLength" : 4000, "validation" : "STRICT", "compress" : "HIGH", "cache" : true, "encrypt" : "AES128", }, "keyColumn" : { "name" : "EMP_ID", "sqlType" : "NUMBER", "assignmentMethod" : "SEQUENCE", "sequenceName" : "EMPLOYEE_ID_SEQ" }, "creationTimeColumn" : { "name" : "CREATED_ON" }, "lastModifiedColumn" : { "name" : "LAST_UPDATED", "index" : "empLastModIndexName" }, "versionColumn" : { "name" : "VERSION_NUM", "method" : "SEQUENTIAL" }, "mediaTypeColumn" : { "name" : "CONTENT_TYPE" }, "readOnly" : true }
関連項目:
SQL条件is json
によって使用される構文の可能性の詳細は、『Oracle Database JSON開発者ガイド』を参照
JSON RFC 4627標準については、http://tools.ietf.org/html/rfc4627
を参照
SecureFiles LOB記憶域の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照
キーの割当て方法は、コレクションに挿入されたオブジェクトにどのようにキーを割り当てるかを決定します。
表1-6 キーの割当て方法
方法 | 説明 |
---|---|
|
キーはデータベース順序によって生成される整数です。 |
|
キーはSQL関数 |
|
キーはRESTサーバーが実行中のJava仮想マシン(JVM)の組込みの |
|
キーはクライアント・アプリケーションによって割り当てられます(非推奨)。 |
Oracle RESTの標準として、サーバーによって割り当てられるキーを使用すること、つまり、CLIENT
によるキーの割当て方法を避けることを強くお薦めします。簡易な数値のキーが必要な場合は、SEQUENCE
をお薦めします。一意の識別子なら何でもよい場合は、UUID
をお薦めします。
キー割当て方法がSEQUENCE
、GUID
またはUUID
の場合は、操作POST objectを使用してコレクションにオブジェクトを挿入します。RESTサーバーでは、必ずPOST
が挿入操作として解釈され、キーが割り当てられ、レスポンス・ボディでそのキーが返されます。
キーの割当て方法がCLIENT
の場合、URLパスに必要なキーが含まれていないため、POST
をコレクションへのオブジェクトの挿入に使用できません。かわりに、PUT objectを使用してコレクションにオブジェクトを挿入する必要があります。オブジェクトがコレクションにまだ存在しない場合、RESTサーバーでは、PUT
は挿入操作と解釈されます。オブジェクトがコレクションにすでに存在する場合は、RESTサーバーによりPUT
は置換操作と解釈されます。PUT
は、事実上、SQL文のMERGE
と等価です。
注意:
クライアント割当てキーが使用され、キー列タイプがVARCHAR2
の場合、データベース・キャラクタ・セットにはAL32UTF8が推奨されます。これにより、キーからデータベース・キャラクタ・セットへの変換がロスレスになります。
それ以外の場合、クライアント割当てキーにデータベース・キャラクタ・セットでサポートされない文字が含まれる場合、読取りまたは書込み操作時に、データベース・キャラクタ・セットへのキーの変換は失われます。これにより、挿入操作中に重複キー・エラーが発生することがあります。もっと一般的に言うと、予測できない結果が生じることがあります。たとえば、読取り操作で、予定したキーとは異なるキーに関連付けられている値が返されることがあります。
バージョン管理方法は、オブジェクトがコレクションに挿入またはコレクション内のオブジェクトが置換されたとき、RESTサーバーがオブジェクトのバージョン値を計算する方法を決定します。
表1-7 バージョン管理方法
方法 | 説明 |
---|---|
|
RESTサーバーにより、オブジェクトのコンテンツの各バイトのMD5チェックサムが計算されます。文字データ型( 一括挿入の場合、リクエスト・ボディはオブジェクトの配列として解析され、個別のオブジェクトのバイトは、記憶域用に選択されたエンコーディングにかかわらず、UTF-8エンコーディングで再シリアライズされます。 すべての場合において、各バイトのチェックサムが計算され、オブジェクトの |
|
RESTサーバーにより、オブジェクトのコンテンツの各バイトのSHA256チェックサムが計算されます。文字データ型( 一括挿入の場合、リクエスト・ボディはオブジェクトの配列として解析され、個別のオブジェクトのバイトは、記憶域用に選択されたエンコーディングにかかわらず、UTF-8エンコーディングで再シリアライズされます。 すべての場合において、各バイトのチェックサムが計算され、特定のオブジェクトの |
|
オブジェクトのコンテンツは無視して、オブジェクトの挿入、およびすべての置換操作において(置換操作がオブジェクトのコンテンツを変更しない場合でも)、RESTサーバーにより32文字の16進値である汎用一意識別子(UUID)が生成されます。 |
|
オブジェクトのコンテンツは無視して、RESTサーバーにより、SQLの |
|
オブジェクトのコンテンツは無視して、RESTサーバーにより、オブジェクトが挿入されたときにバージョン1が割り当てられ、オブジェクトが置換されるたびにバージョン値がインクリメントされます。 |
|
RESTサーバーでは、挿入または置換操作の間にバージョン値が割り当てられません。GET操作では、バージョン列に格納されている任意の非nullの値がETagとして使用されます。アプリケーションは、バージョン列に値を入れる責任があります(たとえば、PL/SQLトリガーまたは非同期プログラムを使用して)。 |
コンテンツ自体が変更したときに変更されるMD5
やSHA256
のチェックサム計算値により、クライアントのキャッシュを無効にするための非常に正確な方法が提供されます。しかし、RESTサーバーでは、挿入または置換されたオブジェクトに対してバイト単位で計算を実行しなければならず、コストが高くなります。
UUID
は、RESTサーバーで入力のすべてのバイトを調べたり、SQLが関数の値を戻すのを待つ必要がないため、入力操作として最も効率的です。しかし、オブジェクトのコンテンツを変更しない場合でも、置換操作によりキャッシュされたコピーが無効になります。
TIMESTAMP
は、整数値を必要とするか、または最新のものを決定するために2つのバージョンを比較しなければならない場合に便利です。UUID
と同様、オブジェクトのコンテンツを変更しなくても、置換操作によりキャッシュされたコピーが無効になります。システム・クロックの精度に制限があることから、オブジェクトが非常に高い頻度(ミリ秒ごとに何度も)で変更される可能性がある場合は、TIMESTAMP
はお薦めしません。
SEQUENTIAL
もまた、整数値を必要とするか、または最新のものを決定するために2つのバージョンを比較しなければならない場合に便利です。バージョン値は人が見てわかりやすく、システム・クロックの制限があってもバージョンが増加します。しかし、インクリメント操作がSQL内で発生するため、新規のバージョン値がRESTのレスポンス・ボディで戻され、常に使用できるとはかぎりません。
RESTのためのSODAなどのORDSでは、サービスを保護するためにロールベースのアクセス制御が使用されます。ここでは、RESTのためのSODAに必要なロールおよび権限について説明しています。
この項を読む前に、ORDSのセキュリティ機能に精通している必要があります。関連する情報は、『Oracle REST Data Servicesインストレーション、構成および開発ガイド』を参照してください。
REST SODAを使用する前に、データベース・ロールSODA_APP
をデータベース・ユーザーに付与する必要があります。さらに、ords.enable_schema
を使用してORDSでスキーマを有効にする際に、アプリケーション・サーバー・ロールSODA Developer
を持つユーザーのみがサービスにアクセスできるように、権限が作成されます。具体的には、ords.enable_schema
は次の権限マッピングを作成します。
exec ords.create_role('SODA Developer'); exec ords.create_privilege(p_name => 'oracle.soda.privilege.developer', p_role_name => 'SODA Developer'); exec ords.create_privilege_mapping('oracle.soda.privilege.developer', '/soda/*');
このことは、デフォルトで、JSONドキュメント・ストアにアクセスするにはユーザーはアプリケーション・サーバー・ロールSODA Developer
を持っている必要があることに影響します。
カスタムの権限マッピングを追加することもできます。次に例を示します。
declare l_patterns owa.vc_arr; begin l_patterns(1) := '/soda/latest/employee'; l_patterns(2) := '/soda/latest/employee/*'; ords.create_role('EmployeeRole'); ords.create_privilege(p_name => 'EmployeePrivilege', p_role_name => 'EmployeeRole'); ords.create_privilege_mapping(p_privilege_name => 'EmployeePrivilege', p_patterns => l_patterns); commit; end;
この例では、EmployeeRole
ロールを持つユーザーのみがemployee
コレクションにアクセスできるように指定する権限マッピングを作成します。
複数の権限パターンが同じリソースに適用された場合、最も具体的なパターンを持つ権限が他の権限よりも優先されます。たとえば、パターン/soda/latest/employees/*
および/soda/*
は、どちらもリクエストURL http://example.org/ords/quine/soda/latest/employee/id1
と一致します。
'/soda/latest/employees/*'
は'/soda/*'
よりも具体的であるため、EmployeePrivilege
権限のみがこのリクエストに適用されます。
注意:
SODA_APP
はOracle Databaseロールです。SODA Developer
はアプリケーション・サーバー・ロールです。
ORDSは、様々な認証メカニズムをサポートしています。JSONドキュメント・ストアRESTサービスは、サーバー間の相互作用に使用されることを意図しています。このため、JSONドキュメント・ストアRESTサービスで使用する認証メカニズムとしては、Two-Legged OAuth(クライアント資格証明フロー)をお薦めします。しかし、HTTP Basic認証など、その他のメカニズムもサポートされています。
関連項目:
『Oracle REST Data Servicesインストレーション、構成および開発ガイド』
開発およびテストのセキュリティ上の考慮事項を示します。
次のように、デフォルトの権限マッピングを削除することで、セキュリティを無効にし、匿名アクセスを許可できます。
exec ords.delete_privilege_mapping('oracle.soda.privilege.developer', '/soda/*')
しかし、本番システムで匿名アクセスを許可することはお薦めしません。匿名アクセスの許可は、認証されていないユーザーに任意のコレクションの読取り、更新、またはドロップを許可することになります。
また、ords.war user
コマンド使用して特定のロールを持つテスト・ユーザーを作成できます。次に例を示します(new_passwordは、ユーザーbob
のパスワードのプレースホルダです)。
# Create user bob with role SODA Developer
java -jar ords.war user bob "SODA Developer"
# Access the JSON document store as user bob using basic authentication
curl -u bob:new_password https://example.com/ords/scott/soda/latest/