| Oracle® REST Data Services RESTのためのSODA開発者ガイド リリース3.0 E67394-04 |
|
 前 |
 次 |
インストール方法や使用方法など、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/
