| Oracle® REST Data Services RESTのためのSODA開発者ガイド リリース17.2.4 E67394-05 |
|
 前 |
 次 |
RESTのためのSODAのHTTP操作について説明しています。
表4-1に、RESTのためのSODAによって提供されるHTTP操作をまとめます。操作の完全な説明を参照するには、左の列のリンクをクリックします。
表4-1 RESTのためのSODAのHTTP操作
| 操作 | 説明 |
|---|---|
スキーマ内のコレクション名の一部またはすべてを取得します。 |
|
サブセットを指定するパラメータを使用して、コレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるセットをページングできます。 |
|
指定したオブジェクトをコレクションから取得します。 |
|
存在しない場合は、コレクションを作成します。 |
|
アップロードしたオブジェクト(通常は新規バージョン)で指定したオブジェクトを置き換えます。 コレクションがクライアントによって割り当てられたキーを持ち、アップロードしたオブジェクトがコレクションに存在しない場合は、 |
|
コレクションを削除します。 |
|
指定したオブジェクトをコレクションから削除します。 |
|
アップロードしたオブジェクトを指定したコレクションにPUTし、キーを割り当ててそのキーを戻します。コレクションは、サーバーが割り当てるキーを使用する必要があります。 |
|
サブセットを指定するフィルタを使用して、コレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるセットはページングできません。 |
|
指定されたコレクションにオブジェクトの配列を挿入し、キーを割り当ててそのキーを戻します。 |
|
コレクションからオブジェクトのすべて、またはそのサブセットを削除します。 |
RESTのためのSODAのHTTP操作は、Universal Resource Identifier (URI)によって指定されます。
URIの形式は、次のとおりです。
/ords/schema/soda/[version/[collection/[{key/|?action=action}]]]
ここで、
ordsは、Oracle REST Data Services(ORDS)リスナーのディレクトリで、RESTのためのSODAはそのコンポーネントです。
schemaは、RESTのためのSODAのエンド・ポイントとして構成されたOracle Databaseスキーマの名前です。
sodaは、ORDS内のテンプレートとしてマッピングしたときにOracle Database JSONサービスに付けた名前です。
versionは、sodaのバージョン番号です。
collectionは、schema内に保存されるオブジェクトのセットの名前です。
通常、オブジェクトはJSONドキュメントですが、Multipurpose Internet Mail Extensions(MIME)タイプ(イメージ、オーディオ、ビデオなど)も可能です。
JSONドキュメントは、テキストJSONとして表現されます。
通常、アプリケーションは、コレクションを使用して特定のタイプのオブジェクトのすべてのインスタンスを保持します。このように、コレクションはリレーショナル・データベースの表に類似しています。1つの列にキーを格納し、別の列にコンテンツを格納します。
keyは、collection内のオブジェクトを一意に識別する文字列です。
指定されたオブジェクトは、そのキーによって指定されています。
actionは、query、index、unindex、insert、updateまたはdeleteのいずれかです。
RESTのためのSODAのHTTP操作により情報やオブジェクトが戻される場合、レスポンス・ボディでこれが行われます。
GET object操作では、レスポンス・ボディは単一のオブジェクトです。
表4-2に、レスポンス・ボディに表示されるフィールドのリストとその説明を示します。
表4-2 レスポンス・ボディに表示されるフィールド
| フィールド | 説明 |
|---|---|
|
コレクション内のオブジェクト(通常はJSONドキュメント)を一意に識別する文字列。 |
|
HTTPエンティティ・タグ(ETag) - チェックサムまたはバージョン。 |
|
作成日のタイム・スタンプ。 |
|
最終変更のタイムスタンプ。 |
|
オブジェクトのコンテンツ(JSONオブジェクトにのみ適用)。 |
|
HTTPコンテンツ・タイプ(非JSONオブジェクトにのみ適用)。 |
|
HTTPコンテンツ長(非JSONオブジェクトにのみ適用)。 |
|
その操作により検索または作成された1つ以上のコレクションまたはオブジェクトのリスト。このフィールドには、表4-3に示すフィールドが続きます。 |
操作がオブジェクトを作成または戻す場合、レスポンス・ボディに表4-3に示すフィールドを追加できます。追加のフィールドはitemsフィールドの後に現れます。
表4-3 オブジェクトを戻す操作のレスポンス・ボディの追加フィールド
| フィールド | 説明 |
|---|---|
|
コレクションの名前。このフィールドはGET schemaのレスポンス・ボディにのみ表示されます。 |
|
コレクションのプロパティ。このフィールドはGET schemaのレスポンス・ボディにのみ表示されます。 |
|
|
|
サーバーで設定されたコレクション(行)の最大数の制限。 |
|
戻されるオブジェクトの最初を示すオフセット(既知の場合)。 |
|
戻されるオブジェクトの数。これは、POST bulk deleteのレスポンス・ボディにのみ表示されるフィールドです。 |
|
コレクション内のオブジェクトの数(要求した場合)。 |
|
|
例4-1は、25個のオブジェクトを戻すレスポンス・ボディの構造を示しています。1番目のオブジェクトはJSONオブジェクトで、2番目はjpegイメージです。これらのオブジェクトを含むコレクションには、追加のオブジェクトが含まれています。
例4-1 レスポンス本文
{
"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" : [ ... ]
}
GET schemaは、スキーマ内のコレクション名のすべて、またはそのサブセットを取得します。
関連項目:
GET schemaのURLパターンを説明します。
/ords/schema/soda/version/
パラメータを指定しなければ、GET schemaによりschema内のすべてのコレクション名が取得されます。
| パラメータ | 説明 |
|---|---|
|
リストするコレクション名の数を |
|
取得を開始する |
GET schemaのレスポンス・コードを説明します。
200
成功 - レスポンス・ボディには、スキーマ内のコレクションの名前とプロパティが名前の順序で含まれています。次に例を示します。
{
"items" : [
{"name" : "employees",
"properties" : {...} },
{"name" : "departments",
"properties" : {...} },
...
],
"hasMore" : false
}
hasMoreがtrueの場合、コレクション名の次のセットを取得するには、fromID=last_returned_collectionと指定します。(前述の例では、last_returned_collectionは"regions"です。)
404
スキーマが見つからないか、アクセスが許可されていないかのいずれかです。
GET collectionは、サブセットを指定するパラメータを使用してコレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるオブジェクトのセットをページングできます。
関連項目:
POST queryは、パラメータのかわりにフィルタを使用してコレクションからオブジェクトのすべてまたはサブセットを取得します。戻されるオブジェクトのセットはページングできません。
GET collectionのURLパターンを説明します。
/ords/schema/soda/version/collection/
パラメータを指定しなければ、GET collectionにより、collectionからすべてのオブジェクト(キーとコンテンツの両方)が取得され、collection内のオブジェクトの数は戻されません。
注意:
コレクション内が非JSONオブジェクトの場合は、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が含まれている場合)
linksの詳細は、「GET collectionのリンク配列」を参照してください
401
コレクションの読取りアクセスが許可されていません。
404
コレクションが見つかりませんでした。
GET collectionのlinks配列を説明します。
links配列の存在およびそのコンテンツは、GET collection操作のパラメータによって決定されるモードに依存します。
links配列が存在する場合は、戻される各オブジェクトの要素が格納されています。各要素には、そのオブジェクトから他のオブジェクトへのリンクが含まれています。次のリンクがあります。
firstは、そのオブジェクトからコレクション内の最初のオブジェクトにリンクします。
prevは、そのオブジェクトからコレクション内の前のオブジェクトにリンクします。
nextは、そのオブジェクトからコレクション内の次のオブジェクトにリンクします。
prevおよびnextリンクを使用し、戻されたオブジェクトのセットをページングできます。
表4-4に、GET collectionのパラメータによりどのようにモードが決定され、links配列の存在とそのコンテンツが決定されるのかを示します。
表4-4 GET collectionのパラメータとモードおよびリンク配列の関係
| パラメータ | モード | リンク配列 |
|---|---|---|
|
キーのみ |
存在しません(他のパラメータに関係なく)。 |
|
オフセット |
戻される各オブジェクトの要素が格納されます。各要素には、注意書きのある場合を除き、次のリンクが含まれます。
|
|
キー |
戻される各オブジェクトの要素が格納されます。各要素には、注意書きのある場合を除き、次のリンクが含まれます。
|
|
タイムスタンプ |
存在しません。 |
GET objectは、指定されたコレクションから指定されたオブジェクトを取得します。
関連項目:
GET objectのURLパターンを説明します。
/ords/schema/soda/version/collection/key/
パラメータなし。
GET objectのリクエスト・ヘッダーを説明します。
操作GET objectは、次のオプションのリクエスト・ヘッダーを受け入れます。
| ヘッダー | 説明 |
|---|---|
|
|
|
オブジェクトの |
GET objectのレスポンス・コードを説明します。
200
成功 - レスポンス・ボディにはURLパターンで識別されたオブジェクトが含まれます。
204
オブジェクトのコンテンツはnullです。
304
etagオブジェクトと一致する変更日またはチェックサムから、どのオブジェクトも変更されていません(「GET objectのリクエスト・ヘッダー」を参照)。
401
コレクションまたはオブジェクトの読取りアクセスが許可されていません。
404
コレクションまたはオブジェクトが見つかりませんでした。
PUT collectionは、存在しない場合はコレクションを作成します。
関連項目:
PUT collectionのURLパターンを説明します。
/ords/schema/soda/version/collection/
パラメータなし。
PUT objectは、指定されたコレクション内の指定されたオブジェクトをアップロードされたオブジェクト(通常、新規バージョン)で置き換えます。コレクションがクライアントによって割り当てられたキーを持ち、アップロードしたオブジェクトがコレクションに存在しない場合は、PUTはアップロードしたオブジェクトをコレクションに挿入します。
関連項目:
PUT objectのURLパターンを説明します。
/ords/schema/soda/version/collection/key/
パラメータなし。
DELETE collectionは、コレクションを削除します。
コレクションからすべてのオブジェクトを削除し、コレクション自体は削除しない場合は、POST bulk deleteを使用します。
関連項目:
DELETE collectionのURLパターンを説明します。
/ords/schema/soda/version/collection/
パラメータなし。
DELETE objectは、指定されたコレクションから指定されたオブジェクトを削除します。
関連項目:
DELETE objectのURLパターンを説明します。
/ords/schema/soda/version/collection/key/
パラメータなし。
POST objectは、アップロードされたオブジェクトを指定されたコレクションに挿入し、キーを割り当ててそのキーを戻します。コレクションは、サーバーによって割り当てられるキーを使用する必要があります。
コレクションが、クライアントによって割り当てられるキーを使用する場合は、PUT objectを使用します。キーの割当て方法の詳細は、「キーの割当て方法」を参照してください。
関連項目:
POST objectのURLパターンを説明します。
/ords/schema/soda/version/collection/
パラメータなし。
POST objectのレスポンス・コードを説明します。
201
成功 - オブジェクトはコレクション内にあり、レスポンス・ボディにはサーバーによって割当てられたキーが含まれ、その他の情報が含まれている可能性もあります。次に例を示します。
{
"items" : [
{
"id" : "key",
"etag" : "etag",
"lastModified" : "timestamp"
"created" : "timestamp"
}
],
"hasMore" : false
}
202
オブジェクトは受入れられて非同期挿入のキューに入れられ、レスポンス・ボディにはサーバーによって割当てられたキーが含まれています。
401
コレクションへの挿入が許可されていません。
405
コレクションは読取り専用です。
501
サポートされていない操作です(たとえば、サーバーによるキー割当てではない)。
POST queryは、サブセットを指定するフィルタを使用してコレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるオブジェクトのセットはページングできません。
関連項目:
GET collectionは、フィルタのかわりにパラメータを使用してコレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるオブジェクトのセットをページングできます。
POST queryのURLパターンを説明します。
/ords/schema/soda/version/collection?action=query
パラメータは、注意書きのある場合を除きオプションです。
| パラメータ | 説明 |
|---|---|
|
必須。アクションの種類を指定します。 |
|
戻されるオブジェクトの数を |
|
オブジェクトを戻す前に、 |
|
オブジェクトの |
POST queryのリクエスト・ボディからフィルタ仕様オブジェクトを省略した場合、操作ではコレクション内のすべてのオブジェクトが取得されます。
関連項目:
SODAフィルタ使用に関する情報は、『Oracle Database Simple Oracle Document Access (SODA)の概要』を参照
POST array insertは、オブジェクトの配列を指定されたコレクションに挿入し、キーを割り当ててそのキーを戻します。
関連項目:
POST array insertのURLパターンを説明します。
/ords/schema/soda/version/collection?action=insert
| パラメータ | 説明 |
|---|---|
|
必須。アクションの種類を指定します。 |
POST array insertのレスポンス・コードを説明します。
200
成功 - レスポンス・ボディには、挿入されたオブジェクトの配列が割当てられたキーとともに含まれます。次に例を示します。
{
"items" : [
{
"id" : "12345678",
"etag" : "...",
"lastModified" : "..."
"created" : "..."
},
{
"id" : "23456789",
"etag" : "...",
"lastModified" : "..."
"created" : "..."
}
],
"hasMore" : false
}
401
コレクションへの挿入が許可されていません。
404
コレクションが見つかりませんでした。
405
コレクションは読取り専用です。
POST bulk deleteは、サブセットを指定するフィルタを使用して指定されたコレクションからオブジェクトのすべて、またはそのサブセットを削除します。
注意:
コレクションからすべてのオブジェクトを削除しても、空のコレクションは存在しています。コレクション自体を削除するには、DELETE collectionを使用します。
POST bulk deleteのURLパターンを説明します。
次のいずれかです。
/ords/schema/soda/version/collection?action=delete /ords/schema/soda/version/collection?action=truncate
| パラメータ | 説明 |
|---|---|
|
必須。サブセットを指定するオプションのフィルタを使用して |
|
必須。 |
警告:
action=deleteを指定し、フィルタ仕様を省略するか、またはフィルタ仕様が空の場合、その操作によりコレクションのすべてのオブジェクトが削除されます。
SODAフィルタ仕様の詳細は、Oracle Database JavaのためのSODA開発者ガイドを参照してください。
