1. RESTのためのSODA開発者ガイド
  2. RESTのためのSODAの使用

3 RESTのためのSODAの使用

実行可能な例を使用して、RESTのためのSODAの基本的な操作について段階的に説明されています。例では、コマンドライン・ツールcURLを使用してサーバーにRESTリクエストを送信します。

例は、RESTのためのSODAのインストールの説明のとおりにOracle REST Data Services (ORDS)が起動され、database-schemaでORDSが有効化されていることを前提としています。

いくつかの例では、インストール手順3でダウンロードしたzipファイルに含まれているサンプルのJSONドキュメントを使用します。それらは、ORDS_HOME/examples/soda/getting-startedディレクトリにあります。

関連項目:

3.1 RESTのためのSODAによるドキュメント・コレクションの作成

RESTのためのSODAを使用して新規ドキュメント・コレクションを作成する方法について説明します。

新しいコレクションを作成するには、このコマンドを使用します。ここでのMyCollectionは、コレクションの名前です。 

curl -i -X PUT http://localhost:8080/ords/database-schema/soda/latest/MyCollection

このコマンドは、PUTリクエストをURL http://localhost:8080/ords/database-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/database-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操作のボディとしてコレクション仕様を指定します。

すでに同じ名前のコレクションが存在する場合は、そのコレクションが開かれます。カスタム・メタデータが指定されていて、そのメタデータが既存のコレクションのメタデータと一致しない場合、コレクションは開かれずにエラーが発生します。(一致するには、すべてのメタデータ・フィールドが同じ値を保持している必要があります)。

注意:

コレクションを削除するには、RESTのためのSODAによるドキュメント・コレクションの削除の説明に従って実行します。SQLを使用して、コレクションの基礎となるデータベース表をドロップしないでください。コレクションには、コレクション表に格納されたドキュメントに加えて、永続化されたメタデータがあります。

関連項目

関連項目:

コレクション表のデフォルトのネーミング規則については、Oracle Database Simple Oracle Document Access (SODA)の概要を参照

親トピック: RESTのためのSODAの使用

3.2 RESTのためのSODAによる既存のコレクションの検出

既存のコレクションのリストについて例を示します。

database-schema内の利用可能なコレクションのリストを取得するには、次のコマンドを実行します。 

curl -X GET http://localhost:8080/ords/database-schema/soda/latest

それにより、URL http://localhost:8080/ords/database-schema/soda/latestでGETリクエストが送信され、このレスポンス・ボディが返されます。 

{ "items" :
  [ { "name":"MyCollection",
      "properties": { "schemaName":"SCHEMA",
                      "tableName":"MyCollection",
                      ... }
      "links" :
      [ { "rel"  : "canonical",
          "href" :
          "http://localhost:8080/ords/database-schema/soda/latest/MyCollection" } ] } ],
  "more" : false }

レスポンス・ボディには、database-schema内の使用可能なすべてのコレクションが含まれます。この場合は、コレクションMyCollectionのみとなります。

GET collection操作が成功すると、レスポンス・コード200が戻ります。レスポンス・ボディは、それぞれのコレクションのコレクション仕様を含む、利用可能なコレクションの配列が含まれたJSONオブジェクトです。

関連項目

親トピック: RESTのためのSODAの使用

3.3 RESTのためのSODAによるドキュメント・コレクションのドロップ

コレクションを削除する例を示します。

MyCollectionを削除するには、次のコマンドを実行します。 

curl -i -X DELETE http://localhost:8080/ords/database-schema/soda/latest/MyCollection

このコマンドは、DELETEリクエストをURL http://localhost:8080/ords/database-schema/soda/latest/MyCollectionで送信し、次のレスポンスが戻されます。 

HTTP/1.1 200 OK
Cache-Control: private,must-revalidate,max-age=0
Content-Length: 0

レスポンス・コード200は、操作が成功したことを示します。コレクションを削除するDELETE操作(DELETE collection操作)は、レスポンス・ボディを戻しません。

コレクションが削除されたことを確認するには、次のようにdatabase-schemaで利用可能なコレクションのリストを取得します。 

curl -X GET http://localhost:8080/ords/database-schema/soda/latest

MyCollectionが削除されていれば、このコマンドは次のレスポンスを戻します。 

{ "items" : [],
  "more"  : false }

次のステップで使用できるように、MyCollectionを再度作成します。 

curl -X PUT http://localhost:8080/ords/database-schema/soda/latest/MyCollection

関連項目

親トピック: RESTのためのSODAの使用

3.4 RESTのためのSODAによるコレクションへの単一ドキュメントの挿入

コレクションへのドキュメントの挿入について例を示します。

この例では、ダウンロードに含まれているpo.jsonファイルを使用します。ファイルには、注文書を含むJSONドキュメントが含まれています。MyCollectionにこのJSONドキュメントをロードするには、次のコマンドを実行します。 

curl -X POST --data-binary @po.json -H "Content-Type: application/json"
http://localhost:8080/ords/database-schema/soda/latest/MyCollection

このコマンドは、POSTリクエストをURL http://localhost:8080/ords/database-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の値)をコピーします。

関連項目

親トピック: RESTのためのSODAの使用

3.5 RESTのためのSODAによるコレクションへの複数ドキュメントの挿入

オブジェクトのJSON配列を使用して、一連のドキュメントをコレクションに一括挿入できます。各オブジェクトは、挿入されるいずれかのドキュメントのコンテンツに対応しています。

例3-1では、発注書オブジェクトのJSON配列を一連のドキュメントとしてコレクションに挿入しています。各オブジェクトは、1つのドキュメントのコンテンツを構成しています。例3-2は、挿入されたドキュメントをチェックしています。

POST bulk-insert操作が成功すると、レスポンス・コード200が戻されます。レスポンス・ボディは挿入した各ドキュメントの識別子、現在のETagおよび最終変更タイム・スタンプが含まれるJSONドキュメントです。

例3-1 オブジェクトのJSON配列を使用したコレクションへのドキュメントの一括挿入

この例では、ダウンロードに含まれているPOList.jsonファイルを使用します。このファイルには、発注書オブジェクトのJSON配列が含まれています。このコマンドは、発注書をドキュメントとしてコレクションMyCollectionにロードします。 

curl -X POST --data-binary @POList.json -H "Content-Type: application/json" 
http://localhost:8080/ords/database-schema/soda/latest/custom-actions/insert/MyCollection/

アクションinsertにより、配列は単一のドキュメントとしてではなくドキュメントのセットとして挿入されます。

(かわりに、同等のURL http://localhost:8080/ords/database-schema/soda/latest/MyCollection?action=insertを使用できます。)

このコマンドは、POSTリクエストをURL http://localhost:8080/ords/database-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
}

例3-2 挿入されたドキュメントの確認

挿入されたドキュメントを確認するには、(例3-1の値ではなく)実際のPOST一括挿入操作によって返されるidフィールド値をコピーして、その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構文は使用できません。

関連項目

関連項目:

コレクション表のデフォルトのネーミング規則については、Oracle Database Simple Oracle Document Access (SODA)の概要を参照

親トピック: RESTのためのSODAの使用

3.6 RESTのためのSODAによるコレクションでのドキュメントの検索

キー指定によるコレクションからのドキュメントの取得について例を示します。

RESTのためのSODAによるコレクションへの単一ドキュメントの挿入で挿入したドキュメントを取得するには、このコマンドを実行します。ここでのidは、ドキュメント挿入時にコピーしたドキュメント・キーです。 

curl -X GET http://localhost:8080/ords/database-schema/soda/latest/MyCollection/id

GET document操作が成功すると、レスポンス・コード200が戻されます。レスポンス・ボディには、取得されたドキュメントが含まれています。

idがMyCollectionに存在しない場合のレスポンス・コードは404で、idを次のような識別子に変更すれば確認できます。 

curl -X GET http://localhost:8080/ords/database-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"
}

関連項目

親トピック: RESTのためのSODAの使用

3.7 RESTのためのSODAによるコレクション内のドキュメントの置換

コレクション内のドキュメントを新しいバージョンに置き換える例を示します。このために、HTTP操作PUTを使用します。

存在しないドキュメントに対するPUT操作の動作は、コレクションに使用されるキー割当て方法によって異なります。

  • コレクションがサーバーによって割り当てられたキーを使用している場合(コレクションMyCollectionと同様)、存在しないドキュメントを更新しようとすると(つまり、コレクション内のドキュメントのものではないキーを指定すると)エラーが発生します。

  • コレクションがクライアントによって割り当てられたキーを使用する場合は、存在しないドキュメントを更新しようとすると、指定されたキーを持つ新規ドキュメントがコレクションに挿入されます。

MyCollectionからドキュメントを取得するには、次のコマンドを実行します(ここでのidは、RESTのためのSODAによるコレクション内のドキュメントのリストでコピーしたドキュメント識別子です)。 

curl -X GET http://localhost:8080/ords/database-schema/soda/latest/MyCollection/id

このコマンドは、取得したドキュメントを出力します。

ダウンロードに含まれるpoUpdated.jsonファイルのコンテンツでこのドキュメントを置き換えるには、次のコマンドを実行します。 

curl -i -X PUT --data-binary @poUpdated.json -H "Content-Type: application/json"
http://localhost:8080/ords/database-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/database-schema/soda/latest/MyCollection/023C4A6581D84B71A5C0D5D364CE8484/
Content-Length: 0

レスポンス・コード200は、操作が成功したことを示しています。コレクション内のドキュメントを更新するPUT操作(PUT object操作)の成功は、レスポンス・ボディを戻しません。

更新されたドキュメントを確認するには、次のコマンドを再実行します。

curl -X GET http://localhost:8080/ords/database-schema/soda/latest/MyCollection/id

このコマンドは、次の出力を戻します。

{
  "PONumber": 1,
  "Content" : "This document has been updated...."
}

関連項目

親トピック: RESTのためのSODAの使用

3.8 RESTのためのSODAによるコレクションからの単一ドキュメントの削除

HTTP操作DELETEを使用すると、コレクションから単一のドキュメントを削除できます。

RESTのためのSODAによるコレクション内のドキュメントの検索で取得したドキュメントをMyCollectionから削除するには、次のコマンドを実行します(ここで、idはドキュメント識別子です)。 

curl -i -X DELETE http://localhost:8080/ords/database-schema/soda/latest/MyCollection/id

このコマンドは、DELETEリクエストをURL http://localhost:8080/ords/database-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操作)は、レスポンス・ボディを戻しません。

関連項目

親トピック: RESTのためのSODAの使用

3.9 RESTのためのSODAによるコレクションからの複数ドキュメントの削除

HTTP操作POSTを使用してコレクションから複数のJSONドキュメントを削除するには、リクエストURLでカスタム・アクションdeleteまたはtruncateを使用します。コレクションからすべてのJSONドキュメントを削除するには、truncateを使用します。そのフィルタに一致するドキュメントのみを削除するには、QBEとともにdeleteを使用します。

例3-3では、コレクションMyCollectionからUserフィールドの値がTGATESであるドキュメントを削除します。例3-4では、コレクションMyCollectionからすべてのドキュメントを削除します。

例3-3 コレクションからの一致するドキュメントの一括削除

この例では、QBE.1.jsonファイル内のQBEを使用し、フィールドUserの値として"TGATES"を持つ9個のドキュメントと一致します。コレクションMyCollectionからそれらのドキュメント(のみ)を削除します。 

curl -X POST --data-binary @QBE.1.json -H "Content-Type: application/json" 
http://localhost:8080/ords/database-schema/soda/latest/custom-actions/delete/MyCollection/

(かわりに、同等のURL http://localhost:8080/ords/database-schema/soda/latest/MyCollection?action=deleteを使用できます。)

警告:

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

例3-4 コレクションからのすべてのドキュメントの一括削除

この例では、コレクションMyCollectionからすべてのドキュメントを削除します。 

curl -X POST -H "Content-Type: application/json" 
http://localhost:8080/ords/database-schema/soda/latest/custom-actions/truncate/MyCollection/

(かわりに、同等のURL http://localhost:8080/ords/database-schema/soda/latest/MyCollection?action=truncateを使用できます。)

親トピック: RESTのためのSODAの使用

3.10 RESTのためのSODAによるコレクション内のドキュメントのリスト

GET操作の使用によるコレクション内のドキュメントのリストについて例を示します。

結果を制御するパラメータを使用できます。たとえば、次の操作が可能です。

  • 戻されるドキュメントの数を制限する

  • ドキュメントの識別子(キー)のみ、ドキュメントのコンテンツのみ、またはキーとコンテンツの両方を戻す

  • キーまたは最終変更タイム・スタンプに基づいて、ドキュメントの範囲を戻す

  • 戻されるドキュメントのリストの順序を指定する

MyCollectionのドキュメントをリストするには、そのコンテンツではなく、キーやその他のメタデータを戻すように、次のコマンドを実行します。 

curl -X GET http://localhost:8080/ords/database-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/database-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/database-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インストレーション、構成および開発ガイド』を参照

親トピック: RESTのためのSODAの使用

3.11 RESTのためのSODAによるコレクション内のドキュメントの索引付け

リクエストURLでカスタム・アクションindexを使用し、HTTP操作POSTによってコレクション内のドキュメントを索引付けできます。リクエスト・ボディには索引仕様が含まれています。Bツリー、空間、フルテキストまたはデータ・ガイドの索引付けを指定できます。

注意:

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

JSON検索索引は、全文検索および非定型構造問合せに使用され、永続的な記録およびJSONデータ・ガイド情報の自動更新に使用されます。Oracle Spatial and Graph索引はGeoJSON (空間)データに使用されます。

関連項目:

例3-5 RESTのためのSODAによるJSONフィールドの索引付け

この例では、ファイルindexSpec1.json (例3-6を参照)の索引仕様に従って、コレクションMyCollection内のドキュメントを索引付けます。 

curl -i -X POST --data-binary @indexSpec1.json -H "Content-Type: application/json" http://localhost:8080/ords/database-schema/soda/latest/custom-actions/index/MyCollection/

代替のURI構文を使用している次のリクエストは同等です。

curl -i -X POST --data-binary @indexSpec1.json -H "Content-Type: application/json" http://localhost:8080/ords/database-schema/soda/latest/MyCollection?action=index

例3-6 RequestorフィールドのBツリー索引仕様(ファイルindexSpec1.json)

次の例は、ファイルindexSpec1.jsonのBツリー索引仕様を示しています。

索引の名前はREQUESTOR_IDXであり、Requestorフィールドに索引付けします。データ型が指定されていないため、デフォルトでVARCHAR2となります。scalarRequiredフィールドにtrueが指定されているため、コレクションに索引付きフィールドがないドキュメントが含まれている場合、索引作成が試行されたときにエラーが発生します。 

{ "name"           : "REQUESTOR_IDX",
  "scalarRequired" : true, 
  "fields"         : [{"path" : "Requestor", "order" : "asc"}] }

親トピック: RESTのためのSODAの使用

3.12 RESTのためのSODAによるフィルタ仕様を使用した問合せ

フィルタ仕様、つまり例による問合せ(QBE)を使用した、コレクションからドキュメントを選択するための問合せ条件の定義について例を示します。

例では、インストール手順3でダウンロードしたzipファイルに含まれているQBE.*.jsonファイルを使用します。それらは、ORDS_HOME/examples/soda/getting-startedディレクトリにあります。

  • QBE.1.json
    QBE.1.jsonファイル内の例による問合せ(QBE)では、フィールドUserの値がTGATESである9個のドキュメントのリストが返されます。
  • QBE.2.json
    QBE.2.jsonファイル内の例による問合せ(QBE)では、フィールドUPCCodeの値が13023015692と等しいドキュメントが選択されます。UPCCodeはPartオブジェクトのフィールドで、PartオブジェクトはLineItems配列のフィールドです。LineItemsに配列のオフセットが指定されていないので、問合せは配列のすべての要素を検索します。
  • QBE.3.json
    QBE.3.jsonファイル内の例による問合せ(QBE)では、配列LineItemsの要素内のフィールドItemNumberの値が4より大きいドキュメントが選択されます。QBE演算子フィールド"$gt"は必須です。
  • QBE.4.json
    QBE.4.jsonファイル内の例による問合せ(QBE)では、フィールドUPCCodeの値が13023015692と等しく、フィールドItemNumberの値が3と等しいドキュメントが選択されます。QBE演算子フィールド$andはオプションです。

関連項目

関連項目:

親トピック: RESTのためのSODAの使用

3.12.1 QBE.1.json

QBE.1.jsonファイル内の例による問合せ(QBE)では、フィールドUserの値がTGATESである9個のドキュメントのリストが返されます。

次に、QBE.1.jsonファイル内の問合せを示します。脚注1

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

(かわりに、同等のURL http://localhost:8080/ords/database-schema/soda/latest/MyCollection?action=queryを使用できます。)

POST query操作が成功すると、レスポンス・コード200および問合せ基準を満たすドキュメントのリストが戻されます。

コマンドにはfieldsパラメータがないので、デフォルト値fields=allが適用され、レスポンス・ボディには各ドキュメントのメタデータとコンテンツの両方が含まれています。

注意:

ドキュメントのコンテンツを含めると、レスポンス・ボディはかなり大きくなります。後の操作でコンテンツが必要になる場合にのみ、レスポンス・ボディにコンテンツを含めることをお薦めします。レスポンス・ボディからコンテンツを取得すると、サーバーから取得するより効率的です。

他のQBE.*.jsonファイル内の問合せを実行するには、前述のものと同様のコマンドを実行します。

親トピック: RESTのためのSODAによるフィルタ仕様を使用した問合せ

3.12.2 QBE.2.json

QBE.2.jsonファイル内の例による問合せ(QBE)では、フィールドUPCCodeの値が13023015692と等しいドキュメントが選択されます。UPCCodeはPartオブジェクトのフィールドで、PartオブジェクトはLineItems配列のフィールドです。LineItemsに配列のオフセットが指定されていないので、問合せは配列のすべての要素を検索します。

次に、QBE.2.jsonファイル内の問合せを示します。演算子フィールド"$eq"が暗黙的に使用されています。 

{ "LineItems.Part.UPCCode" : "13023015692" }

関連項目:

詳細は、『Oracle Database Simple Oracle Document Access (SODA)の概要』を参照してください

親トピック: RESTのためのSODAによるフィルタ仕様を使用した問合せ

3.12.3 QBE.3.json

QBE.3.jsonファイル内の例による問合せ(QBE)では、配列LineItemsの要素内のフィールドItemNumberの値が4より大きいドキュメントが選択されます。QBE演算子フィールド"$gt"は必須です。

次に、QBE.3.jsonファイル内の問合せを示します。 

{ "LineItems.ItemNumber" : { "$gt" : 4 } }

親トピック: RESTのためのSODAによるフィルタ仕様を使用した問合せ

3.12.4 QBE.4.json

QBE.4.jsonファイル内の例による問合せ(QBE)では、フィールドUPCCodeの値が13023015692と等しく、フィールドItemNumberの値が3と等しいドキュメントが選択されます。QBE演算子フィールド$andはオプションです。

次に、QBE.4.jsonファイル内の問合せを示します。 

{ "$and" : [
  { "LineItems.Part.UPCCode" : "13023015692" },
  { "LineItems.ItemNumber"   : 3 } ] }

関連項目:

Oracle Database Simple Oracle Document Access (SODA)の概要

親トピック: RESTのためのSODAによるフィルタ仕様を使用した問合せ

3.13 RESTのためのSODAによる単一JSONドキュメントへのパッチ適用

HTTP操作PATCHを使用して、単一のJSONドキュメントの一部を選択的に更新(パッチ適用)できます。JSON Patch仕様を使用して更新を指定します。

注意:

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

JSON Patchは、JSONドキュメントに適用する一連の操作を指定するための形式です。これはメディア・タイプapplication/json-patch+jsonによって識別され、HTTP操作PATCHでの使用に適しています。

QBE.5.jsonファイル内のQBEを使用して、PONumberフィールドが値1である単一のドキュメントをMyCollectionから取得します。 

curl -X POST --data-binary @QBE.5.json -H "Content-Type: application/json" http://localhost:8080/ords/database-schema/soda/latest/custom-actions/query/MyCollection/

QBE.5.jsonファイルの内容は{ "PONumber" : 1 }です。

このコマンドは、取得したドキュメントを出力します。

poPatchSpec.json (例3-7を参照)ファイルのJSON Patch仕様に従ってそのドキュメントを更新するには、次のコマンドを実行します。ここで、keyは、前述のコマンド(QBE.5.jsonファイル内のQBEのPOST操作)によって返されるドキュメントのキーです。 

curl -i -X PATCH --data-binary @poPatchSpec.json -H "Content-Type: application/json-patch+json"
http://localhost:8080/ords/database-schema/soda/latest/MyCollection/key

正常終了の場合、前述のコマンドはHTTPステータス・コード200を返します。

失敗した場合、パッチ適用は実行されません。特に、いずれかの手順(操作)が失敗すると、そのドキュメントへのパッチ適用は失敗します。ドキュメントは、PATCH HTTP操作を試行する前の状態から変更されません。

例3-8は例3-7を使用したパッチ適用が成功する前のドキュメントの例を示し、例3-9はパッチ適用後の同じドキュメントを示しています(変更部分は太字で示されます)。

関連項目:

JSONドキュメントの変更を記述するJSON Patch形式の詳細は、JSON Patch (RFC 6902)を参照してください

例3-7 JSON Patch仕様(ファイルpoPatchSpec.json)

[ { "op"    : "test",
    "path"  : "/ShippingInstructions/Address/street",
    "value" : "200 Sporting Green" },
  { "op"    : "replace",
    "path"  : "/ShippingInstructions/Address/street",
    "value" : "Winchester House, Heatley Rd" },
  { "op"    : "copy",
    "from"  : "/ShippingInstructions/Phone/0",
    "path"  : "/ShippingInstructions/Phone/1" },
  { "op"    : "replace",
    "path"  : "/ShippingInstructions/Phone/1/number",
    "value" : "861-555-8765" } ]

例3-8 パッチ適用前のJSONドキュメント

{ "PONumber"             : 1,
  "Reference"            : "MSULLIVA-20141102",
  "Requestor"            : "Martha Sullivan",
  "User"                 : "MSULLIVA",
  "CostCenter"           : "A50",
  "ShippingInstructions" : {
    "name"    : "Martha Sullivan",
    "Address" : { "street"  : "200 Sporting Green",
                  "city"    : "South San Francisco",
                  "state"   : "CA",
                  "zipCode" : 99236,
                  "country" : "United States of America" },
    "Phone"   : [ { "type"   : "Office",
                    "number" : "979-555-6598" } ] }
  ... }

例3-9 パッチ適用後のJSONドキュメント

{ "PONumber"             : 1,
  "Reference"            : "MSULLIVA-20141102",
  "Requestor"            : "Martha Sullivan",
  "User"                 : "MSULLIVA",
  "CostCenter"           : "A50",
  "ShippingInstructions" : {
    "name"    : "Martha Sullivan",
    "Address" : { "city": "South San Francisco",
                  "state": "CA",
                  "zipCode": 99236,
                  "country": "United States of America",
                  "street": "Winchester House, Heatley Rd" },
    "Phone"   : [ { "type"   : "Office",
                    "number" : "979-555-6598" },
                  { "type": "Office",
                    "number": "861-555-8765" } ] }
  ... }

関連項目

親トピック: RESTのためのSODAの使用

3.14 RESTのためのSODAによるコレクション内の複数JSONドキュメントへのパッチ適用

対象のドキュメントに一致するようにコレクションを問い合せ、変更内容を指定することで、コレクション内の複数のJSONドキュメントを更新(パッチ適用)できます。QBE演算子$patchを使用して、JSON Patch仕様で更新を指定します。リクエストURLでカスタム・アクションupdateを使用して、HTTP操作POSTを使用します。

注意:

QBE演算子$patchを使用するには、Oracle Databaseリリース18c以上が必要です。

演算子$patchはRESTのためのSODAに固有です。他のSODA実装では使用されません。$queryおよび$orderbyと同じレベルでコンポジット・フィルタで使用されます。(演算子$patchおよび$orderbyの両方がコンポジット・フィルタに存在する場合、$orderbyは無視されます)。

演算子$patchのオペランドはJSON Patch仕様であり、問合せのターゲットとなる各ドキュメントに適用するパッチ操作をリストするオブジェクト要素を含むJSON配列です。

JSON Patchは、JSONドキュメントに適用する一連の操作を指定するための形式です。これはメディア・タイプapplication/json-patch+jsonによって識別され、HTTP操作PATCHでの使用に適しています。

特定のドキュメントのパッチ適用に対して指定された更新手順(操作)が正常に終了しなかった場合、そのドキュメントに対するパッチ適用は実行されません。ただし、他のターゲット・ドキュメントではパッチ適用が続行されます。

例3-10は、Userフィールドの値がTGATESであるドキュメントにパッチ適用するためのQBEを示しています。例3-11は、そのQBEを使用して更新操作を実行するコマンドを示しています。

関連項目:

例3-10 QBE演算子$patchを使用して複数JSONドキュメントにパッチ適用するためのQBE

この例は、ダウンロード内のqbePatch.jsonファイルの内容であるQBEを示しています。このQBEは、QBE.1.jsonと同じドキュメントと一致します。各ドキュメントで同じ新しい値を使用し、各ドキュメントの番地と最初の電話番号が更新されます。

演算子$patchが使用されるため、QBEの問合せ部分は演算子$queryを使用して指定する必要があります。演算子$patchの値はJSON Patch仕様です。これは、番地"200 Sporting Green"を"176 Gateway Blvd"に置き換え、配列Phoneの最初の番号を999-999-9999に置き換えます。 

{ "$query" : {"User" : "TGATES" },
  "$patch" : [ { "op"    : "test",
                 "path"  : "/ShippingInstructions/Address/street",
                 "value" : "200 Sporting Green" },
               { "op"    : "replace",
                 "path"  : "/ShippingInstructions/Address/street",
                 "value" : "176 Gateway Blvd" },
               { "op"    : "replace",
                 "path"  : "/ShippingInstructions/Phone/0/number",
                 "value" : "999-999-9999" } ] }

例3-11 パッチ・アクションを含むHTTP POSTを使用した複数JSONドキュメントへのパッチ適用

このコマンドは、例3-10のQBEに従ってドキュメントを更新します。$query値に一致する各ドキュメントが更新されます。 

curl -X POST --data-binary @qbePatch.json -H "Content-Type: application/json"
http://localhost:8080/ords/database-schema/soda/latest/custom-actions/update/MyCollection

関連項目

親トピック: RESTのためのSODAの使用


脚注の凡例

脚注1: 同等のコンポジット・フィルタQBEでは、QBE演算子$query: { $query : { "User" : "TGATES" } }を明示的に使用します。