コレクション仕様

5 コレクション仕様

コレクション仕様は、コレクション・オブジェクトの基礎となるOracle Databaseの表またはビューに関する情報を提供するJSONオブジェクトです。コレクションを作成するときに、表またはビューが作成されます。

注意:

コレクション仕様では、厳密なJSON構文を使用する必要があります。つまり、数値以外の各値を二重引用符で囲む必要があります。

PUT collectionを使用してコレクションを作成する場合は、リクエスト・ボディとしてコレクション仕様を指定することで、そのコレクションのカスタム・メタデータを設定できます。

既存のコレクションのコレクション・メタデータは、GET catalog操作の一部として返されます。

例5-1に、デフォルトのコレクション・メタデータを指定するコレクション仕様を示します。

表5-1に、コレクション仕様のフィールドおよび使用可能な値を説明します。

注意:

オプション列(作成日のタイム・スタンプ、最終変更タイム・スタンプ、バージョンまたはメディア・タイプ)のいずれかをコレクション仕様から省略した場合、その列は作成されません。少なくとも、コレクションにはキー列とコンテンツ列があります。

表5-1 コレクション仕様のフィールド

フィールド	説明	使用可能な値
`schemaName`	コレクション・オブジェクトの基礎となる表またはビューを所有するデータベース・スキーマ(ユーザー・アカウント)のSQL名。	—
`tableName`または`viewName`	コレクション・オブジェクトの基礎となる表またはビューのSQL名。	—
`keyColumn.name`	キー列の名前。	デフォルト: `ID`
`keyColumn.sqlType`	キー列のSQLデータ型。	`VARCHAR2` (デフォルト)、`NUMBER`、`RAW`
`keyColumn.maxLength`	データ型が`NUMBER`ではない場合のキー列の最大長。	デフォルト: 255
`keyColumn.assignmentMethod`	キーの割当て方法。	`SEQUENCE`、`GUID`、`UUID` (デフォルト)または`CLIENT`
`keyColumn.sequenceName`	`keyColumn.assignmentMethod`が`SEQUENCE`の場合、このフィールドには、データベース順序の名前を指定する必要があります。	既存のデータベース順序の名前
`contentColumn.name`	コンテンツ列の名前。	デフォルト: `JSON_DOCUMENT`
`contentColumn.sqlType`	コンテンツ列のSQLデータ型。	`VARCHAR2`、`BLOB`(デフォルト)、`CLOB`
`contentColumn.maxLength`	データ型がLOBではない場合のコンテンツ列の最大長。	デフォルト長は4000バイトです。`MAX_STRING_SIZE` = `STANDARD`の場合、`maxLength`は多くても4000 (バイト)です。`MAX_STRING_SIZE` = `EXTENDED`の場合、`maxLength`は多くても32767 (バイト)です。
`contentColumn.validation`	コンテンツ列の検証レベル。SQL条件の`is` `json`に対応するもので、JSONコンテンツが準拠すべき構文を決定します。 `STANDARD`は、JSON RFC 4627標準に従って検証します。(Oracle SQL条件`is json`に定義された厳密な構文に対応します。) `STRICT`は`STANDARD`と同じですが、ドキュメントに重複したJSONフィールド名が含まれていないことも確認する点のみ異なります。(キーワード`WITH UNIQUE KEYS`も使用される場合、Oracle SQL条件`is json`に定義された厳密な構文に対応します。) `LAX`は、より緩慢に検証します。(Oracle SQL条件`is json`に定義された緩慢な構文に対応します。) `LAX`で許可される緩和の一部として、次のものがあります。 JSONフィールド名を二重引用符(`"`)で囲む必要はありません。 `true`、`false`および`null`の、大文字、小文字および混在バージョンが許可されます。数字はその他の方法で表すことができます。	`STANDARD` (デフォルト)、`STRICT`、`LAX`
`contentColumn.compress`	コンテンツ列に格納されるSecureFilesの圧縮レベル。	`NONE` (デフォルト)、`HIGH`、`MEDIUM`、`LOW`
`contentColumn.cache`	コンテンツ列に格納されるSecureFilesのキャッシング。	`TRUE`、`FALSE` (デフォルト)
`contentColumn.encrypt`	コンテンツ列に格納されるSecureFilesの暗号化アルゴリズム。^脚注 1	`NONE` (デフォルト)、`3DES168`、`AES128`、`AES192`、`AES256`
`creationTimeColumn.name`	オプションの作成日のタイム・スタンプ列の名前。この列はSQLデータ型`TIMESTAMP`で、デフォルトの値は`SYSTIMESTAMP`です。	デフォルト: `CREATED_ON`
`lastModifiedColumn.name`	オプションの最終変更タイム・スタンプ列の名前。この列はSQLデータ型`TIMESTAMP`で、デフォルトの値は`SYSTIMESTAMP`です。	デフォルト: `LAST_MODIFIED`
`lastModifiedColumn.index`	タイムスタンプ列の一意でないインデックスの名前。名前が指定されている場合、インデックスが作成されます。
`versionColumn.name`	オプションのバージョン(ETag)列の名前。この列は、そのメソッドが`SEQUENTIAL`または`TIMESTAMP`の場合はSQLデータ型`NUMBER`で、そうでない場合はSQLデータ型`VARCHAR2(255)`です。注意: メソッドが`TIMESTAMP`の場合、バージョンは、マイクロ秒の精度の日時の整数表現として格納されます。日付/時刻文字列またはSQL日付/時刻型は格納されません。	デフォルト: `VERSION`
`versionColumn.method`	バージョン管理方法。	`SEQUENTIAL`、`TIMESTAMP`、`UUID`、`SHA256` (デフォルト)、`MD5`、`NONE`
`mediaTypeColumn.name`	オプションのオブジェクトのメディア・タイプ列の名前。この列は、SQLデータ型`VARCHAR2(255)`です。
`readOnly`	読取り/書込みポリシー: `TRUE`は読取り専用を意味します。	`TRUE`、`FALSE` (デフォルト)

^脚注1

SecureFile暗号化でコレクションを作成する前に暗号化ウォレットを設定します。ALTER SYSTEM文のSET ENCRYPTION WALLET句の詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

例5-1 デフォルトのコレクション・メタデータ

{
   "schemaName" : "mySchemaName",
   "tableName" : "myTableName",
   "keyColumn" :
   {
      "name" : "ID",
      "sqlType" : "VARCHAR2",
      "maxLength" : 255,
      "assignmentMethod" : "UUID"
   },
   "contentColumn" :
   {
      "name" : "JSON_DOCUMENT",
      "sqlType" : "BLOB",
      "compress" : "NONE",
      "cache" : true,
      "encrypt" : "NONE",
      "validation" : "STANDARD"
   },
   "versionColumn" :
   {
     "name" : "VERSION",
     "method" : "SHA256"
   },
   "lastModifiedColumn" :
   {
     "name" : "LAST_MODIFIED"
   },
   "creationTimeColumn" :
   {
      "name" : "CREATED_ON"
   },
   "readOnly" : false
}

5.1 キーの割当て方法

キーの割当て方法は、コレクションに挿入されたオブジェクトにどのようにキーを割り当てるかを決定します。

表5-2 キーの割当て方法

方法	説明
`SEQUENCE`	キーはデータベース順序によって生成される整数です。`keyColumn.sequenceName`フィールドに順序の名前を指定する必要があります。
`GUID`	キーはSQL関数`SYS_GUID()`によって生成され、この関数はグローバルに一意な`RAW`値(16バイト)を戻します。必要に応じて、`RAW`値を`keyColumn.sqlType`で指定されたSQLデータ型に変換できます。
`UUID`	キーはRESTサーバーが実行中のJava仮想マシン(JVM)の組込みの`UUID`機能によって生成され、この機能はユニバーサルに一意の`RAW`値を戻します。必要に応じて、`RAW`値を`keyColumn.sqlType`で指定されたSQLデータ型に変換できます。
`CLIENT`	キーはクライアント・アプリケーションによって割り当てられます(非推奨)。

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が推奨されます。これにより、キーからデータベース・キャラクタ・セットへの変換がロスレスになります。

それ以外の場合、クライアント割当てキーにデータベース・キャラクタ・セットでサポートされない文字が含まれる場合、読取りまたは書込み操作時に、データベース・キャラクタ・セットへのキーの変換は失われます。これにより、挿入操作中に重複キー・エラーが発生することがあります。もっと一般的に言うと、予測できない結果が生じることがあります。たとえば、読取り操作で、予定したキーとは異なるキーに関連付けられている値が返されることがあります。

関連項目

親トピック: コレクション仕様

5.2 バージョン管理方法

バージョン管理方法は、オブジェクトがコレクションに挿入またはコレクション内のオブジェクトが置換されたとき、RESTサーバーがオブジェクトのバージョン値を計算する方法を決定します。

表5-3 バージョン管理方法

方法	説明
`MD5`	RESTサーバーにより、オブジェクトのコンテンツの各バイトのMD5チェックサムが計算されます。文字データ型(`VARCHAR2`や`CLOB`など)のバイトの場合、計算にはUTF-8エンコーディングが使用されます。データ型`BLOB`のバイトの場合、計算にはPOST本文の転送に使用されるエンコーディング(UTF-8またはUTF-16)が使用されます。一括挿入の場合、リクエスト・ボディはオブジェクトの配列として解析され、個別のオブジェクトのバイトは、記憶域用に選択されたエンコーディングにかかわらず、UTF-8エンコーディングで再シリアライズされます。すべての場合において、各バイトのチェックサムが計算され、オブジェクトの`GET`操作で戻されます。
`SHA256` (デフォルト)	RESTサーバーにより、オブジェクトのコンテンツの各バイトのSHA256チェックサムが計算されます。文字データ型(`VARCHAR2`や`CLOB`など)のバイトの場合、計算にはUTF-8エンコーディングが使用されます。データ型`BLOB`のバイトの場合、計算にはPOST本文の転送に使用されるエンコーディング(UTF-8またはUTF-16)が使用されます。一括挿入の場合、リクエスト・ボディはオブジェクトの配列として解析され、個別のオブジェクトのバイトは、記憶域用に選択されたエンコーディングにかかわらず、UTF-8エンコーディングで再シリアライズされます。すべての場合において、各バイトのチェックサムが計算され、特定のオブジェクトの`GET`操作で戻されます。
`UUID`	オブジェクトのコンテンツは無視して、オブジェクトの挿入、およびすべての置換操作において(置換操作がオブジェクトのコンテンツを変更しない場合でも)、RESTサーバーにより32文字の16進値である汎用一意識別子(UUID)が生成されます。
`TIMESTAMP`	オブジェクトのコンテンツは無視して、RESTサーバーにより、SQLの`SYSTIMESTAMP`機能によって戻された値から導出される整数値が生成されます。この整数値は、システム・クロック(通常、マイクロ秒またはミリ秒)の精度で変化します。
`SEQUENTIAL`	オブジェクトのコンテンツは無視して、RESTサーバーにより、オブジェクトが挿入されたときにバージョン1が割り当てられ、オブジェクトが置換されるたびにバージョン値がインクリメントされます。
`NONE`	RESTサーバーでは、挿入または置換操作の間にバージョン値が割り当てられません。GET操作では、バージョン列に格納されている任意の非nullの値がETagとして使用されます。アプリケーションは、バージョン列に値を入れる責任があります(たとえば、PL/SQLトリガーまたは非同期プログラムを使用して)。

コンテンツ自体が変更したときに変更されるMD5やSHA256のチェックサム計算値により、クライアントのキャッシュを無効にするための非常に正確な方法が提供されます。しかし、RESTサーバーでは、挿入または置換されたオブジェクトに対してバイト単位で計算を実行しなければならず、コストが高くなります。

UUIDは、RESTサーバーで入力のすべてのバイトを調べたり、SQLが関数の値を戻すのを待つ必要がないため、入力操作として最も効率的です。しかし、オブジェクトのコンテンツを変更しない場合でも、置換操作によりキャッシュされたコピーが無効になります。

TIMESTAMPは、整数値を必要とするか、または最新のものを決定するために2つのバージョンを比較しなければならない場合に便利です。UUIDと同様、オブジェクトのコンテンツを変更しなくても、置換操作によりキャッシュされたコピーが無効になります。システム・クロックの精度に制限があることから、オブジェクトが非常に高い頻度(ミリ秒ごとに何度も)で変更される可能性がある場合は、TIMESTAMPはお薦めしません。

SEQUENTIALもまた、整数値を必要とするか、または最新のものを決定するために2つのバージョンを比較しなければならない場合に便利です。バージョン値は人が見てわかりやすく、システム・クロックの制限があってもバージョンが増加します。しかし、インクリメント操作がSQL内で発生するため、新規のバージョン値がRESTのレスポンス・ボディで戻され、常に使用できるとはかぎりません。

親トピック: コレクション仕様