プライマリ・コンテンツに移動
Oracle® REST Data Services RESTのためのSODA開発者ガイド
リリース17.2.4
E67394-05
目次へ移動
目次 		索引へ移動
索引
前
前 		次
次

5 コレクション仕様

コレクション仕様は、コレクション・オブジェクトの基礎となるOracleデータベースの表やビューについての情報を提供します。コレクションを作成するときに、表またはビューが作成されます。

注意:

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

表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は、基本となる表がHR.EMPLOYEESであるオブジェクトのコレクション仕様です。

例5-1 コレクション仕様

{
  "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
}

トピック

関連項目:

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のレスポンス・ボディで戻され、常に使用できるとはかぎりません。

前
前 		次
次
目次へ移動
目次 		索引へ移動
索引