| Oracle® REST Data Services RESTのためのSODA開発者ガイド リリース17.2.4 E67394-05 |
|
 前 |
 次 |
実行可能な例を使用して、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 Simple Oracle Document Access (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 }}
QBE.4.jsonファイル内の例による問合せ(QBE)では、フィールドUPCCodeの値が13023015692と等しく、フィールドItemNumberの値が3と等しいドキュメントが選択されます。キーワード$andはオプションです。
次に、QBE.4.jsonファイル内の問合せを示します。
{ "$and" : [
{ "LineItems.Part.UPCCode" : "13023015692" },
{ "LineItems.ItemNumber" : 3 }
]
}
関連項目:
Oracle Database Simple Oracle Document Access (SODA)の概要
