1. RESTのためのSODA開発者ガイド
  2. RESTのためのSODAのHTTP操作

4 RESTのためのSODAのHTTP操作

RESTのためのSODAのHTTP操作について説明しています。

  • RESTのためのSODAのHTTP操作のURI
    RESTのためのSODAのHTTP操作は、URI (Universal Resource Identifier)で指定します。
  • RESTのためのSODAのHTTP操作のレスポンス・ボディ
    RESTのためのSODAのHTTP操作で情報またはオブジェクトが返される場合は、レスポンス・ボディに返されます。
  • GET catalog
    GET catalogは、指定されたデータベース・スキーマ(ユーザー・アカウント)のすべてのコレクション名を各コレクションに関する情報とともに取得します。
  • GET user collections
    GET user collectionsは、指定されたデータベース・スキーマ(ユーザー・アカウント)のすべてのコレクション名またはそのサブセットを取得します。
  • GET JSON schema for collection
    この操作では、指定されたコレクション内のJSONドキュメントの構造およびタイプ情報を記述するJSONスキーマが取得されます。
  • GET actions
    GETアクションは、使用可能なすべてのカスタム・アクションを取得します。
  • GET collection
    GET collectionは、サブセットを指定するパラメータを使用してコレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるオブジェクトのセットをページングできます。
  • GET object
    GET objectは、指定されたコレクションから指定されたオブジェクトを取得します。
  • DELETE collection
    DELETE collectionは、コレクションを削除します。
  • DELETE object
    DELETE objectは、指定されたコレクションから指定されたオブジェクトを削除します。
  • PATCH JSON document
    PATCH JSON documentは、指定されたオブジェクトをパッチ適用(編集)されたコピーに置き換えます。
  • POST object
    POST objectは、アップロードされたオブジェクトを指定されたコレクションに挿入し、キーを割り当ててそのキーを戻します。コレクションは、サーバーによって割り当てられるキーを使用する必要があります。
  • POST query
    POST queryは、フィルタを使用してコレクションからオブジェクトのすべて、またはそのサブセットを取得します。
  • POST bulk insert
    POST bulk insertは、指定されたコレクションにオブジェクトの配列を挿入し、キーを割り当ててそのキー返します。
  • POST bulk delete
    POST bulk deleteは、サブセットを指定するフィルタを使用して指定されたコレクションからオブジェクトのすべて、またはそのサブセットを削除します。
  • POST bulk update (patch)
    POST bulk update操作は、指定されたコレクションのオブジェクトを更新(パッチ適用)します。
  • POST index
    POST indexは、指定したコレクション内のドキュメントに索引を作成します。
  • POST unindex
    POST unindexは、指定されたコレクション内のオブジェクトの索引を削除します。
  • PUT collection
    PUT collectionは、存在しない場合はコレクションを作成します。
  • PUT object
    PUT objectは、指定されたコレクション内の指定されたオブジェクトをアップロードされたオブジェクト(通常、新規バージョン)で置き換えます。コレクションがクライアントによって割り当てられたキーを持ち、アップロードしたオブジェクトがコレクションに存在しない場合は、PUTはアップロードしたオブジェクトをコレクションに挿入します。

4.1 RESTのためのSODAのHTTP操作のURI

RESTのためのSODAのHTTP操作は、Universal Resource Identifier (URI)によって指定されます。

URIには次の形式があります。

/ords/database-schema/soda/[version/[metadata-catalog/[collection]]]

/ords/database-schema/soda/[version/[custom-actions/action/[collection/[key]]]]

/ords/database-schema/soda/[version/[collection/[{key|?action=action}]]]

ここで:

  • ordsは、Oracle REST Data Services(ORDS)リスナーのディレクトリで、RESTのためのSODAはそのコンポーネントです。

  • database-schemaは、RESTのためのSODAのエンド・ポイントとして構成されているOracle Databaseスキーマ(ユーザー・アカウント)の名前です。

  • sodaは、ORDS内のテンプレートとしてマッピングしたときにOracle Database JSONサービスに付けた名前です。

  • versionは、sodaのバージョン番号です。

  • custom-actionsは、使用可能なSODAアクションのセットの名前です。

  • metadata-catalogは、SODAコレクションのカタログの名前です。

  • collectionは、database-schema内に保存されるオブジェクトのコレクション(セット)名前です。

  • keyは、collection内のオブジェクトを一意に識別(指定)する文字列です。

  • actionは、query、index、unindex、insert、update、deleteまたはtruncateのいずれかです。

注意:

SODA for REST URI構文では、バージョン・コンポーネントの後に、custom-actions、metadata-catalog、または特定のコレクション名を使用できます。custom-actionsまたはmetadata-catalogを使用する場合、URI内の次のセグメント(存在する場合)はコレクション名です。

構文の柔軟性のため、custom-actionsまたはmetadata-catalogという名前のコレクションを持つことはできません。SODA for RESTを使用して、いずれかの名前のコレクションを作成しようとすると、エラーが発生します。

SODA for REST以外のSODA実装では、custom-actionsまたはmetadata-catalogという名前のコレクションの作成および使用について何ら制約はありません。ただし、相互運用の可能性を考慮して、コレクションにこれらの名前は使用しないことをお薦めします。

次の2つの構文は同等です。

/ords/database-schema/soda/version/custom-actions/action/collection/

/ords/database-schema/soda/version/collection/?action=action

アクションはPOST HTTP操作でのみ使用できます。(これはアクションを実行するための両方のURI構文に適用されます。)

一部のRESTのためのSODA操作では、URI構文のパス・コンポーネントに、疑問符(?)が前に付いたオプションの問合せコンポーネントを続けることができます。問合せコンポーネントは、アンパサンド(&)問合せデリミタで区切られた1つ以上のパラメータ/値のペアで構成されます。

たとえば、次のURIでは、問合せコンポーネント(?action=insert)は、単一のパラメータ/値のペアaction=insertで構成されています。 

/ords/myUser/soda/v1.0/MyCollection/?action=insert

次のURIでは、問合せコンポーネントは、fromID=MyCollectionとlimit=2の2つのパラメータ/値のペアで構成されています。 

/ords/myUser/soda/v1.0/metadata-catalog/?fromID=MyCollection&limit=2

親トピック: RESTのためのSODAのHTTP操作

4.2 RESTのためのSODAのHTTP操作のレスポンス・ボディ

RESTのためのSODAのHTTP操作により情報やオブジェクトが戻される場合、レスポンス・ボディでこれが行われます。

GET object操作では、レスポンス・ボディは単一のオブジェクトです。

表4-1に、レスポンス・ボディに表示されるフィールドのリストとその説明を示します。

表4-1 レスポンス・ボディに表示されるフィールド

フィールド 説明

key

コレクション内のオブジェクト(通常はJSONドキュメント)を一意に識別する文字列。

etag

HTTPエンティティ・タグ(ETag) - チェックサムまたはバージョン。

created

作成日のタイム・スタンプ。

lastModified

最終変更のタイムスタンプ。

value

オブジェクトのコンテンツ(JSONオブジェクトにのみ適用)。

mediaType

HTTPコンテンツ・タイプ(非JSONオブジェクトにのみ適用)。

bytes

HTTPコンテンツ長(非JSONオブジェクトにのみ適用)。

items

その操作により検索または作成された1つ以上のコレクションまたはオブジェクトのリスト。このフィールドには、表4-2に示すフィールドが続きます。

操作がオブジェクトを作成または戻す場合、レスポンス・ボディに表4-2に示すフィールドを追加できます。追加のフィールドはitemsフィールドの後に現れます。

表4-2 オブジェクトを戻す操作のレスポンス・ボディの追加フィールド

フィールド 説明

name

コレクションの名前。このフィールドはGET user collectionsのレスポンス・ボディにのみ表示されます。

properties

コレクションのプロパティ。このフィールドはGET user collectionsのレスポンス・ボディにのみ表示されます。

hasMore

trueは利用可能なオブジェクトが尽きる前にlimitに到達した場合で、falseはそれ以外です。このフィールドは常に存在します。

limit

サーバーで設定されたコレクション(行)の最大数の制限。

offset

戻されるオブジェクトの最初を示すオフセット(既知の場合)。

count

戻されるオブジェクトの数。これは、POST bulk deleteのレスポンス・ボディにのみ表示されるフィールドです。

totalResults

コレクション内のオブジェクトの数(要求した場合)。

links

GET collection操作の最後に存在するフィールド。詳細は、「GET collection」を参照してください。

例4-1 レスポンス本文

この例は、25個のオブジェクトを戻すレスポンス・ボディの構造を示しています。1番目のオブジェクトはJSONオブジェクトで、2番目はjpegイメージです。これらのオブジェクトを含むコレクションには、追加のオブジェクトが含まれています。 

{ "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"   : [ ... ] }

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.3 GET catalog

GET catalogは、指定されたデータベース・スキーマ(ユーザー・アカウント)のすべてのコレクション名を各コレクションに関する情報とともに取得します。

この情報には、コレクションの説明へのリンクと、コレクション内のJSONドキュメントの構造およびタイプ情報を記述するJSONスキーマへのリンクが含まれています。

注意:

JSONスキーマが存在する場合は、Oracle Databaseリリース12c (12.2.0.1)以上を必要とするデータ・ガイドがサポートされるJSON検索索引を持つコレクションが必要です。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.3.1 GET catalogのURLパターン

GET catalogのURLパターンを説明します。 

/ords/database-schema/soda/version/metadata-catalog

パラメータを指定しない場合、GET catalogはdatabase-schema内のすべてのコレクションのカタログ情報を取得します。

URLの末尾には、疑問符(?)で始まりアンパサンド(&)問合せデリミタで区切られたパラメータ/値のペアを1つ以上含めることができます。

パラメータ 説明

limit=n

リストするコレクションの数をnに制限します。

fromID=collection

取得を開始するcollection(指定したコレクションを含む)。

親トピック: GET catalog

4.3.2 GET catalogのレスポンス・コード

GET catalogのレスポンス・コードを説明します。

200

成功 - レスポンス・ボディには、データベース・スキーマ(ユーザー・アカウント)内のコレクションの名前とプロパティが名前順で含まれています。次に例を示します。

{ "items": [
  { "name"       : "employees",
    "properties" : { .. .},
    "links"      : [
      { "rel" : "describes",
        "href" :
        "http://host:port/.../database-schema/soda/version/employees" },
      { "rel" : "canonical",
        "href" :
        "http://host:port/.../database-schema/soda/version/metadata-catalog/employees",
        "mediaType" : "application/json" },
      { "rel" : "alternate",
        "href" :
        "http:host:port/.../database-schema/soda/version/metadata-catalog/employees",
        "mediaType":"application/schema+json" } ] },
  { "name"       : "departments",
    "properties" : { ... },
    "links"      : [ ... ] }
  ...
  { "name"       : "regions",
    "properties" : { ... },
    "links"      : [ ... ] } ],
  "hasMore":false }

hasMoreがtrueの場合、コレクション名の次のセットを取得するには、fromID=last_returned_collectionと指定します。(前述の例では、last_returned_collectionは"regions"です。)

400

パラメータの値が無効です。

401

アクセスが認可されていません。

関連項目

親トピック: GET catalog

4.4 GET user collections

GET user collectionsは、指定されたデータベース・スキーマ(ユーザー・アカウント)のすべてのコレクション名またはそのサブセットを取得します。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.4.1 GET user collectionsのURLパターン

GET user collectionsのURLパターンを説明します。 

/ords/database-schema/soda/version/

パラメータを指定しない場合、GET user collectionsはdatabase-schema内のすべてのコレクション名を取得します。

URLの末尾には、疑問符(?)で始まりアンパサンド(&)問合せデリミタで区切られたパラメータ/値のペアを1つ以上含めることができます。

パラメータ 説明

limit=n

リストするコレクション名の数をnに制限します。

fromID=collection

取得を開始するcollection(指定したコレクションを含む)。

親トピック: GET user collections

4.4.2 GET user collectionsのレスポンス・コード

GET user collectionsのレスポンス・コードを説明します。

200

成功 - レスポンス・ボディには、データベース・スキーマ(ユーザー・アカウント)内のコレクションの名前とプロパティが名前順で含まれています。次に例を示します。

{ "items" : [
  { "name"       : "employees",
    "properties" : {...} },
  { "name"       : "departments",
    "properties" : {...} },
  ...
  { "name"       : "regions",
    "properties" : {...} } ],
  "hasMore" : false }

hasMoreがtrueの場合、コレクション名の次のセットを取得するには、fromID=last_returned_collectionと指定します。(前述の例では、last_returned_collectionは"regions"です。)

400

パラメータの値が無効です。

401

アクセスが認可されていません。

404

データベース・スキーマ(ユーザー)が見つかりませんでした。

親トピック: GET user collections

4.5 GET JSON schema for collection

この操作は、指定されたコレクション内のJSONドキュメントの構造およびタイプ情報を記述するJSONスキーマを取得します。

注意:

JSONスキーマが存在する場合は、Oracle Databaseリリース12c (12.2.0.1)以上を必要とするデータ・ガイドがサポートされるJSON検索索引を持つコレクションが必要です。

この操作では、コレクションのJSONスキーマの他に、コレクションのメタデータもフィールドpropertiesの値として返されます。

親トピック: RESTのためのSODAのHTTP操作

4.5.1 GET JSON schema for collectionのURLパターン

指定したコレクションのJSONスキーマを取得するためのURLパターンについて説明します。

/ords/database-schema/soda/version/metadata-catalog/collection

パラメータなし。

親トピック: GET JSON schema for collection

4.5.2 GET JSON schema for collectionのレスポンス・コード

指定したコレクションのJSONスキーマを取得するためのレスポンス・コードについて説明します。

200

成功。レスポンス・ボディには、フィールドschemaの値としてコレクションのJSONスキーマ、およびフィールドpropertiesの値としてコレクションのメタデータが含まれています。

次に例を示します。

{"name"       : "employees",
 "properties" : {
   "schemaName"         : "MYUSER",
   "tableName"          : "EMPLOYEES",
   "keyColumn"          : {"name"             : "ID",
                           "sqlType"          : "VARCHAR2",
                           "maxLength"        : 24,
                           "path"             : "_id",
                           "assignmentMethod" : "MONGO"},
   "contentColumn"      : {"name"       : "DOCUMENT",
                           "sqlType"    : "VARCHAR2",
                           "maxLength"  : 4000,
                           "validation" : "STRICT"},
   "versionColumn"      : {"name"   : "CHECKSUM",
                           "type"   : "String",
                           "method" : "UUID"},
   "lastModifiedColumn" : {"name"  : "LAST_MODIFIED",
                           "index" : "PEOPLE_T1"},
   "readOnly"           : false},
 "schema"     : {
   "type"       : "object",
   "properties" : {
     "dob"      : {"type"                    : "string",
                   "o:length"                : 16,
                   "o:preferred_column_name" : "dob"},
     "name"     : {"type"                    : "string",
                   "o:length"                : 16,
                   "o:preferred_column_name" : "name"},
     "email"    : {"type"                    : "array",
                   "o:length"                : 64,
                   "o:preferred_column_name" : "email",
                   "items"                   : {
                     "type"                    : "string",
                     "o:length"                : 32,
                     "o:preferred_column_name" : "scalar_string"}},
     "empno"    : {"type"                    : "number",
                   "o:length"                : 8,
                   "o:preferred_column_name" : "empno"},
     "title"    : {"type"                    : "string",
                   "o:length"                : 16,
                   "o:preferred_column_name" : "title"},
     "salary"   : {"type"                    : "number",
                   "o:length"                : 8,
                   "o:preferred_column_name" : "salary"},
     "spouse"   : {"type"                    : "null",
                   "o:length"                : 4,
                   "o:preferred_column_name" : "spouse"},
     "address"  : {"type"                    : "object",
                   "o:length"                : 128,
                   "o:preferred_column_name" : "address",
                   "properties"              : {
                     "city"   : {"type"                    : "string",
                                 "o:length"                : 16,
                                 "o:preferred_column_name" : "city"},
                     "state"  : {"type"                    : "string",
                                 "o:length"                : 2,
                                 "o:preferred_column_name" : "state"},
                     "street" : {"type"                    : "string",
                                 "o:length"                : 32,
                                 "o:preferred_column_name" : "street"}}},
     "company"  : {"type"                    : "string",
                   "o:length"                : 16,
                   "o:preferred_column_name" : "company"},
     "location" : {"type"                    : "object",
                   "o:length"                : 64,
                   "o:preferred_column_name" : "location",
                   "properties"              : {
                     "type"        : {
                       "type"                    : "string",
                       "o:length"                : 8,
                       "o:preferred_column_name" : "type"},
                     "coordinates" : {
                       "type"                    : "array",
                       "o:length"                : 32,
                       "o:preferred_column_name" : "coordinates",
                       "items"                   : {
                         "type" : "number",
                         "o:length" : 8,
                         "o:preferred_column_name" : "scalar_number"}}}},
     "department" : {"type"                    : "string",
                     "o:length"                : 16,
                     "o:preferred_column_name" : "department"}}},
 "links" : [
   {"rel"       : "describes",
    "href"      :
    "http : //host:port/.../database-schema/soda/version/employees"},
   {"rel"       : "canonical",
    "href"      :
    "http : //host:port/.../database-schema/soda/version/metadata-catalog/employees",
    "mediaType" : "application/json"},
   {"rel"       : "alternate",
    "href"      :
    "http : //host:port/.../database-schema/soda/version/metadata-catalog/employees",
    "mediaType" : "application/schema+json"}]}

401

アクセスが認可されていません。

404

コレクションが存在しない場合。

関連項目

親トピック: GET JSON schema for collection

4.6 GET actions

GET actionsは、使用可能なすべてのカスタム・アクションを取得します。

親トピック: RESTのためのSODAのHTTP操作

4.6.1 GET actionsのURLパターン

GET actionsのURLパターンを説明します。 

/ords/database-schema/soda/version/custom-actions/

パラメータなし。

親トピック: GET actions

4.7 GET collection

GET collectionは、サブセットを指定するパラメータを使用してコレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるオブジェクトのセットをページングできます。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.7.1 GET collectionのURLパターン

GET collectionのURLパターンを説明します。 

/ords/database-schema/soda/version/collection/

注意:

コレクション内が非JSONオブジェクトの場合は、GET collectionにより、ドキュメントのコンテンツのかわりにメディア・タイプおよびバイト単位のサイズ(既知の場合)が戻されます。

URLの末尾には、疑問符(?)で始まりアンパサンド(&)問合せデリミタで区切られたパラメータ/値のペアを1つ以上含めることができます。

パラメータ 説明

limit=n

返されるオブジェクトの数を最大n個に制限します。

offset=n

返されたオブジェクトをn個(デフォルト: 0)をスキップしてから、最初のオブジェクトを取得します。

fields={id|value|all}

オブジェクトのidフィールド(キー)のみ、オブジェクトのvalueフィールド(コンテンツ)のみ、またはallフィールド(キーとコンテンツの両方)を取得します。

fieldsの値にかかわらず、GET collectionにより、そのコレクションが各ドキュメントのために保存している他のメタデータは戻されます。

totalResults=true

コレクション内のオブジェクトの数を戻します。(注意: 非効率)

fromID=key

keyの後からオブジェクトの取得を開始します(昇順)。

toID=key

keyの前でオブジェクトの取得を停止します(降順)。

after=key

keyの後からオブジェクトの取得を開始します(昇順)。

before=key

keyの前でオブジェクトの取得を停止します(降順)。

since=timestamp

timestampより後のlastModifiedタイム・スタンプを持つオブジェクトのみを取得します。

until=timestamp

timestampより前のlastModifiedタイム・スタンプを持つオブジェクトのみを取得します。

q=filter

POST queryアクションと同等です。ここで、filterはリクエストのボディで渡されるQBEです。

関連項目

親トピック: GET collection

4.7.2 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が含まれている場合)

400

パラメータの値が無効です。

401

アクセスが認可されていません。

404

コレクションが見つかりませんでした。

関連項目

親トピック: GET collection

4.7.3 GET collectionのリンク配列

GET collectionのlinks配列を説明します。

links配列の存在およびそのコンテンツは、GET collection操作のパラメータによって決定されるモードに依存します。

links配列が存在する場合は、戻される各オブジェクトの要素が格納されています。各要素には、そのオブジェクトから他のオブジェクトへのリンクが含まれています。次のリンクがあります。

  • firstは、そのオブジェクトからコレクション内の最初のオブジェクトにリンクします。

  • prevは、そのオブジェクトからコレクション内の前のオブジェクトにリンクします。

  • nextは、そのオブジェクトからコレクション内の次のオブジェクトにリンクします。

prevおよびnextリンクを使用し、戻されたオブジェクトのセットをページングできます。

表4-3に、GET collectionのパラメータによりどのようにモードが決定され、links配列の存在とそのコンテンツが決定されるのかを示します。

表4-3 GET collectionのパラメータとモードおよびリンク配列の関係

パラメータ モード リンク配列

fields=id

キーのみ

存在しません(他のパラメータに関係なく)。

offset=n

オフセット

戻される各オブジェクトの要素が格納されます。各要素には、注意書きのある場合を除き、次のリンクが含まれます。

  • first(最初のオブジェクトの場合を除く)

  • prev(最初のオブジェクトの場合を除く)

  • next(最後のオブジェクトの場合を除く)

fromID=key

toID=key

after=key

before=key

キー

戻される各オブジェクトの要素が格納されます。各要素には、注意書きのある場合を除き、次のリンクが含まれます。

  • prev(最初のオブジェクトの場合を除く)

  • next(最後のオブジェクトの場合を除く)

since=timestamp

until=timestamp

lastModifiedタイムスタンプ

存在しません。

q=QBE

 問合せ

存在しません。

関連項目

親トピック: GET collection

4.8 GET object

GET objectは、指定されたコレクションから指定されたオブジェクトを取得します。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.8.1 GET objectのURLパターン

GET objectのURLパターンを説明します。 

/ords/database-schema/soda/version/collection/key

親トピック: GET object

4.8.2 GET objectのリクエスト・ヘッダー

GET objectのリクエスト・ヘッダーを説明します。

操作GET objectは、次のオプションのリクエスト・ヘッダーを受け入れます。

ヘッダー 説明

If-Modified-Since=timestamp

timestampからオブジェクトが変更されていない場合、レスポンス・コード304が戻されます。

If-None-Match=etag

ヘッダーに設定したetag (オブジェクト・バージョン)値がドキュメントのetag値と一致する場合は、レスポンス・コード304が返されます。

親トピック: GET object

4.8.3 GET objectのレスポンス・コード

GET objectのレスポンス・コードを説明します。

200

成功 - レスポンス・ボディにはURLパターンで識別されたオブジェクトが含まれます。

204

オブジェクトのコンテンツはnullです。

304

オブジェクトは変更されていません。

401

アクセスが認可されていません。

404

コレクションまたはオブジェクトが見つかりませんでした。

関連項目

親トピック: GET object

4.9 DELETE collection

DELETE collectionは、コレクションを削除します。

コレクションからすべてのオブジェクトを削除し、コレクション自体は削除しない場合は、POST bulk deleteを使用します。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.9.1 DELETE collectionのURLパターン

DELETE collectionのURLパターンを説明します。 

/ords/database-schema/soda/version/collection/

パラメータなし。

親トピック: DELETE collection

4.9.2 DELETE collectionのレスポンス・コード

DELETE collectionのレスポンス・コードを説明します。

200

成功 - コレクションが削除されました。

401

アクセスが認可されていません。

404

コレクションが見つかりませんでした。

関連項目

親トピック: DELETE collection

4.10 DELETE object

DELETE objectは、指定されたコレクションから指定されたオブジェクトを削除します。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.10.1 DELETE objectのURLパターン

DELETE objectのURLパターンを説明します。 

/ords/database-schema/soda/version/collection/key

パラメータなし。

親トピック: DELETE object

4.10.2 DELETE objectのレスポンス・コード

DELETE objectのレスポンス・コードを説明します。

200

成功 - オブジェクトが削除されました。

401

アクセスが認可されていません。

404

コレクションまたはオブジェクトが見つかりませんでした。

405

コレクションは読取り専用です。

関連項目

親トピック: DELETE object

4.11 PATCH JSON document

PATCH JSON documentは、指定されたオブジェクトをパッチ適用(編集)されたコピーに置き換えます。

注意:

PATCH JSON document操作を使用するには、Oracle Databaseリリース18c以上が必要です。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.11.1 PATCH JSON documentのURLパターン

PATCH JSON documentのURLパターンについて説明します。 

/ords/database-schema/soda/version/collection/key

パラメータなし。

親トピック: PATCH JSON document

4.11.2 PATCH JSON documentのリクエスト・ヘッダー

PATCH JSON document操作には、ヘッダーContent-Type=application/json-patch+jsonを使用します。

親トピック: PATCH JSON document

4.11.3 PATCH JSON documentのリクエスト・ボディ

PATCH JSON documentのリクエスト・ボディには、JSON Patch仕様、つまり、JSON Patch手順(操作)をそれぞれ指定するオブジェクトの配列が含まれています。操作は配列順に連続して実行されます。

JSONドキュメントに対する変更を記述するJSON Patch仕様の構文および意味は、JSON Patch標準RFC 6902に指定されています。JSON Patch仕様で参照されるJSONドキュメントの一部へのパスは、JSON Pointer標準RFC 6901を使用して指定します。

関連項目:

親トピック: PATCH JSON document

4.11.4 PATCH JSON Documentのレスポンス・コード

PATCH JSON documentのレスポンス・コードについて説明します。

200

成功 - ドキュメントがパッチ適用(更新)されました。

401

アクセスが認可されていません。

404

ドキュメントまたはコレクションが見つかりません。

405

コレクションは読取り専用です。

関連項目

親トピック: PATCH JSON document

4.12 POST object

POST objectは、アップロードされたオブジェクトを指定されたコレクションに挿入し、キーを割り当ててそのキーを戻します。コレクションは、サーバーによって割り当てられるキーを使用する必要があります。

コレクションが、クライアントによって割り当てられるキーを使用する場合は、PUT objectを使用します。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.12.1 POST objectのURLパターン

POST objectのURLパターンを説明します。 

/ords/database-schema/soda/version/collection/

パラメータなし。

親トピック: POST object

4.12.2 POST objectのリクエスト・ボディ

POST objectのリクエスト・ボディは、コレクションに挿入されるよう、アップロードされたオブジェクトです。

親トピック: POST object

4.12.3 POST objectのレスポンス・コード

POST objectのレスポンス・コードを説明します。

201

成功 - オブジェクトはコレクション内にあり、レスポンス・ボディにはサーバーによって割り当てられたキーが含まれ、その他の情報が含まれている可能性もあります。次に例を示します。

{ "items" : [ { "id"           : "key",
                "etag"         : "etag",
                "lastModified" : "last_modified_timestamp"
                "created"      : "created_timestamp" } ],
  "hasMore" : false }

202

オブジェクトは受入れられて非同期挿入のキューに入れられ、レスポンス・ボディにはサーバーによって割当てられたキーが含まれています。

401

アクセスが認可されていません。

405

コレクションは読取り専用です。

501

サポートされていない操作です(たとえば、サーバーによるキー割当てではない)。

関連項目

親トピック: POST object

4.13 POST query

POST queryは、フィルタを使用してコレクションからオブジェクトのすべて、またはそのサブセットを取得します。

POST query操作ではlinksセクションが返されないため、次および前へのページングは直接実行できません。

注意:

リクエスト・ボディにフィルタを指定したPOST queryを使用するかわりに、GET collectionを使用して、同じフィルタをURLパラメータqの値として渡すことができます。たとえば、次の2つのコマンドは同等です。ここで、QBE.1.jsonファイルの内容は{ "User" : "TGATES" }です。 

curl -X POST --data-binary @QBE.1.json -H "Content-Type: application/json" http://localhost:8080/ords/database-schema/soda/latest/custom-actions/query/MyCollection/
curl -X GET  -H "Content-Type: application/json" http://localhost:8080/ords/database-schema/soda/latest/MyCollection/?q={%20%22User%22%20:%20%22TGATES%22%20}

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.13.1 POST queryのURLパターン

POST queryのURLパターンを説明します。

次のいずれかのURIパターンを使用して、フィルタを使用してコレクションを問い合せます。

/ords/database-schema/soda/version/custom-actions/query/collection
/ords/database-schema/soda/version/collection?action=query

URLの末尾には、疑問符(?)で始まりアンパサンド(&)問合せデリミタで区切られたパラメータ/値のペアを1つ以上含めることができます。パラメータは、注意書きのある場合を除きオプションです。

パラメータ 説明

action=query

2番目の構文形式を使用する場合は必須です。アクションの種類が問合せであることを指定します。

limit=n

戻されるオブジェクトの数をnに制限します。

offset=n

オブジェクトを戻す前に、n個のオブジェクトをスキップします。

fields={id|value|all}

オブジェクトのid(キー)のみ、オブジェクトのvalue(コンテンツ)のみ、またはall(オブジェクトのキーとコンテンツ)を戻します。デフォルト: all

親トピック: POST query

4.13.2 POST queryのリクエスト・ボディ

POST queryアクションのリクエスト・ボディはQBE (フィルタ仕様)です。

リクエスト・ボディは空にできませんが、空のオブジェクト{}にできます。{}の場合は、コレクション内のすべてのオブジェクトが返されます。

関連項目:

SODAフィルタ使用に関する情報は、『Oracle Database Simple Oracle Document Access (SODA)の概要』を参照

親トピック: POST query

4.13.3 POST queryのレスポンス・コード

POST queryのレスポンス・コードを説明します。

200

成功 - オブジェクトはコレクション内にあり、レスポンス・ボディには、フィルタに一致するコレクション内のすべてのオブジェクトが含まれます。

401

アクセスが認可されていません。

404

コレクションが見つかりませんでした。

関連項目

親トピック: POST query

4.14 POST bulk insert

POST bulk insertは、オブジェクトの配列を指定されたコレクションに挿入し、キーを割り当ててそのキーを戻します。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.14.1 POST bulk insertのURLパターン

POST bulk insertのURLパターンを説明します。

次のいずれかのURIパターンを使用して、1つ以上のオブジェクトをコレクションに挿入します。

/ords/database-schema/soda/version/custom-actions/insert/collection
/ords/database-schema/soda/version/collection?action=insert

URLの末尾には、疑問符(?)で始まりアンパサンド(&)問合せデリミタで区切られたパラメータ/値のペアを1つ以上含めることができます。

パラメータ 説明

action=insert

2番目の構文形式を使用する場合は必須です。アクションの種類が一括挿入であることを指定します。

親トピック: POST bulk insert

4.14.2 POST bulk insertのリクエスト・ボディ

POST bulk insertのリクエスト・ボディは、オブジェクトの配列です。

親トピック: POST bulk insert

4.14.3 POST bulk insertのレスポンス・コード

POST bulk insertのレスポンス・コードを説明します。

200

成功 - レスポンス・ボディには、挿入されたオブジェクトに割り当てられたキーを持つ配列が含まれています。次に例を示します。

{ "items" : [ { "id"           : "12345678",
                "etag"         : "...",
                "lastModified" : "..."
                "created"      : "..." },
              { "id"           : "23456789",
                "etag"         : "...",
                "lastModified" : "..."
                "created"      : "..." } ],
  "hasMore" : false }

401

アクセスが認可されていません。

404

コレクションが見つかりませんでした。

405

コレクションは読取り専用です。

関連項目

親トピック: POST bulk insert

4.15 POST bulk delete

POST bulk deleteは、サブセットを指定するフィルタを使用して指定されたコレクションからオブジェクトのすべて、またはそのサブセットを削除します。

注意:

コレクションからすべてのオブジェクトを削除しても、空のコレクションは存在しています。コレクション自体を削除するには、DELETE collectionを使用します。

HTTP POSTアクションのdeleteとtruncateをそれぞれ使用する2つの一括削除操作があります。deleteアクションはより一般的であり、コレクション内の一部またはすべてのオブジェクトを削除するために使用できます。truncateアクションでは、常にコレクションからすべてのオブジェクトが削除されます。deleteアクションは、削除するオブジェクトを選択するフィルタによって制御されます。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.15.1 POST bulk deleteのURLパターン

POST bulk deleteのURLパターンを説明します。

次のURIパターンのいずれかを使用したフィルタによって判別されたとおりに、コレクションから一部またはすべてのオブジェクトを削除します。

/ords/database-schema/soda/version/custom-actions/delete/collection

/ords/database-schema/soda/version/collection?action=delete

次のURIパターンのいずれかを使用して、コレクションからすべてのオブジェクトを削除します(コレクションの切捨て)。 

/ords/database-schema/soda/version/custom-actions/truncate/collection

/ords/database-schema/soda/version/collection?action=truncate

URLの末尾には、疑問符(?)で始まりアンパサンド(&)問合せデリミタで区切られたパラメータ/値のペアを1つ以上含めることができます。

アクション 説明

delete

必須。サブセットを指定するフィルタを使用してcollectionからオブジェクトのすべて、またはそのサブセットを削除することを指定します。(フィルタが存在する必要がありますが、空のオブジェクト{}にできます。)

truncate

必須。collectionからすべてのオブジェクトの削除することを指定します。フィルタは使用しません。

警告:

アクションとしてdeleteを指定し、空のオブジェクト{}をフィルタ仕様として使用すると、コレクションからすべてのオブジェクトが削除されます。

親トピック: POST bulk delete

4.15.2 POST bulk deleteのリクエスト・ボディ(オプション)

アクションがdelete (truncateではなく)の場合、リクエスト・ボディにはコレクションから削除するドキュメントを指定するフィルタ(QBE)が含まれています。

関連項目:

SODAフィルタ仕様の詳細は、Oracle Database JavaのためのSODA開発者ガイドを参照してください

親トピック: POST bulk delete

4.15.3 POST bulk deleteのレスポンス・コード

POST bulk deleteのレスポンス・コードを説明します。

200

成功 - レスポンス・ボディには、削除されたオブジェクトの数がcountおよびitemsDeletedフィールドの値として含まれています。次に例を示します。 

{ "count"       : 42,
  "itemsDeleted : 42 }

401

アクセスが認可されていません。

404

コレクションが見つかりませんでした。

405

コレクションは読取り専用です。

関連項目

親トピック: POST bulk delete

4.16 POST bulk update (patch)

POST bulk update操作は、指定されたコレクションのオブジェクトを更新(パッチ適用)します。

QBEに一致するオブジェクトには、JSON Patch仕様に従ってパッチが適用されます。

注意:

POST bulk update操作を使用するには、Oracle Databaseリリース18c以上が必要です。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.16.1 POST bulk update (patch)のURLパターン

POST bulk updateのURLパターンを説明します。

次のいずれかのURIパターンを使用して、コレクションの1つ以上のオブジェクトを更新します。

/ords/database-schema/soda/version/custom-actions/update/collection
/ords/database-schema/soda/version/collection?action=update

URLの末尾には、疑問符(?)で始まりアンパサンド(&)問合せデリミタで区切られたパラメータ/値のペアを1つ以上含めることができます。

パラメータ 説明

action=update

2番目の構文形式を使用する場合は必須です。アクションの種類が一括更新であることを指定します。

親トピック: POST bulk update (patch)

4.16.2 POST bulk update (patch)のリクエスト・ボディ

POST bulk updateのリクエスト・ボディは、オブジェクトの配列です。

リクエスト・ボディは、例3-10のように、値がJSON Patch仕様である$patchフィールドを持つQBEです。

親トピック: POST bulk update (patch)

4.16.3 POST bulk update (patch)のレスポンス・コード

POST bulk updateのレスポンス・コードを説明します。

200

成功 - レスポンス・ボディには、更新されたオブジェクトの数がcountおよびitemsUpdatedフィールドの値として含まれています。次に例を示します。 

{ "count"       : 42,
  "itemsUpdated : 42

401

アクセスが認可されていません。

405

許可されません。コレクションは読取り専用です。

関連項目

親トピック: POST bulk update (patch)

4.17 POST index

POST indexは、指定されたコレクション内のドキュメントに索引を作成します。

注意:

SODAに索引を作成するには、Oracle Databaseリリース12c (12.2.0.1)以上が必要です。ただし、DATEまたはTIMESTAMP値にBツリー索引を作成するには、Oracle Databaseリリース18c (18.1)以上が必要です。

親トピック: RESTのためのSODAのHTTP操作

4.17.1 POST indexのURLパターン

POST indexのURLパターンを説明します。

次のいずれかのURIパターンを使用して、コレクションの1つ以上のオブジェクトに索引付けします。

/ords/database-schema/soda/version/custom-actions/index/collection
/ords/database-schema/soda/version/collection?action=index

URLの末尾には、疑問符(?)で始まりアンパサンド(&)問合せデリミタで区切られたパラメータ/値のペアを1つ以上含めることができます。

パラメータ 説明

action=index

2番目の構文形式を使用する場合は必須です。アクションが索引付けアクションであることを指定します。

親トピック: POST index

4.17.2 POST indexのリクエスト・ボディ

POST indexのリクエスト・ボディはSODA索引仕様です。

SODA索引仕様は、JSONドキュメントに対する操作に使用される特定の種類のOracle Database索引を指定するJSONオブジェクトです。次の種類の索引を指定できます。

  • Bツリー: スカラーJSON値の索引付けに使用されます。

  • 空間: GeoJSON地理データを索引付けするために使用されます。

  • 検索: 次のいずれか、または両方に使用されます。

    • 非定型の構造的問合せまたは全文検索

    • JSONデータ・ガイド

注意:

データ・ガイド対応JSON検索索引を作成する、または既存のJSON検索索引をデータ・ガイド対応にするには、データベース権限CTXAPPおよびOracle Databaseリリース12c (12.2.0.1)以降が必要です。

関連項目:

親トピック: POST index

4.17.3 POST indexのレスポンス・コード

POST indexのレスポンス・コードを説明します。

200

成功。

401

アクセスが認可されていません。

404

コレクションが見つかりませんでした。

関連項目

親トピック: POST index

4.18 POST unindex

POST unindexは、指定されたコレクション内のオブジェクトの索引を削除します。

親トピック: RESTのためのSODAのHTTP操作

4.18.1 POST unindexのURLパターン

POST unindexのURLパターンを説明します。

次のいずれかのURIパターンを使用して、コレクションの1つ以上のオブジェクトの索引を削除します。

/ords/database-schema/soda/version/custom-actions/unindex/collection
/ords/database-schema/soda/version/collection?action=unindex

URLの末尾には、疑問符(?)で始まりアンパサンド(&)問合せデリミタで区切られたパラメータ/値のペアを1つ以上含めることができます。

パラメータ 説明

action=unindex

2番目の構文形式を使用する場合は必須です。アクションが索引削除アクションであることを指定します。

親トピック: POST unindex

4.18.2 POST unindexのリクエスト・ボディ

POST unindexのリクエスト・ボディはSODA索引仕様です。ただし、指定する必要があるのは索引の名前のみで、残りの索引仕様は無視されます。

関連項目:

SODA索引の仕様に関する情報は、『Oracle Database Simple Oracle Document Access (SODA)の概要』を参照

親トピック: POST unindex

4.18.3 POST unindexのレスポンス・コード

POST unindexのレスポンス・コードを説明します。

200

成功。

401

アクセスが認可されていません。

404

コレクションが見つかりませんでした。

関連項目

親トピック: POST unindex

4.19 PUT collection

PUT collectionは、存在しない場合はコレクションを作成します。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.19.1 PUT collectionのURLパターン

PUT collectionのURLパターンを説明します。 

/ords/database-schema/soda/version/collection

パラメータなし。

親トピック: PUT collection

4.19.2 PUT collectionのリクエスト・ボディ(オプション)

PUT collectionのリクエスト・ボディには、作成されるコレクションのメタデータを定義するコレクション仕様がオプションで含まれます。(仕様が存在しない場合は、デフォルトのメタデータが使用されます。)

関連項目

親トピック: PUT collection

4.19.3 PUT collectionのレスポンス・コード

PUT collectionのレスポンス・コードを説明します。

200

同じ名前のコレクションおよびプロパティがすでに存在しています。

201

成功 - コレクションが作成されました。

401

アクセスが認可されていません。

関連項目

親トピック: PUT collection

4.20 PUT object

PUT objectは、指定されたコレクション内の指定されたオブジェクトをアップロードされたオブジェクト(通常、新規バージョン)で置き換えます。コレクションがクライアントによって割り当てられたキーを持ち、アップロードしたオブジェクトがコレクションに存在しない場合は、PUTはアップロードしたオブジェクトをコレクションに挿入します。

関連項目

親トピック: RESTのためのSODAのHTTP操作

4.20.1 PUT objectのURLパターン

PUT objectのURLパターンを説明します。

URLパターンには次の2つの形式があります。

  • クライアント割当てキーを持つコレクション用のパターン

    /ords/database-schema/soda/version/collection/key

  • システム割当てキーを持つコレクション用のパターン

    /ords/database-schema/soda/version/collection/

パラメータなし。

親トピック: PUT object

4.20.2 PUT objectのリクエスト・ボディ

PUT objectのリクエスト・ボディは、アップロードされたオブジェクトです。

親トピック: PUT object

4.20.3 PUT objectのレスポンス・コード

PUT objectのレスポンス・コードを説明します。

200

成功 - オブジェクトは置換されました。

401

アクセスが認可されていません。

405

コレクションは読取り専用です。

関連項目

親トピック: PUT object