Oracle® REST Data Services

RESTのためのSODA開発者ガイド

リリース3.0

E67394-04(原本部品番号:E58123-13)

2016年11月

Oracle REST Data Services RESTのためのSODA開発者ガイド, リリース3.0

E67394-04

Copyright © 2014, 2016, Oracle and/or its affiliates.  All rights reserved.

原本著者: Drew Adams

原本協力著者: Douglas McMahon、Sheila Moore、Maxim Orgiyan、Josh Spiegel

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations.As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。適用されるお客様とOracle Corporationとの間の契約に別段の定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。適用されるお客様とOracle Corporationとの間の契約に定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

目次

例一覧

図一覧

表一覧

タイトルおよび著作権情報

はじめに

- 対象読者

- ドキュメントのアクセシビリティについて

- 関連ドキュメント

- 表記規則

1 RESTのためのSODA

- RESTのためのSODAの概要

- REST

- ドキュメント・コレクションおよびドキュメント中心のAPI

- RESTのためのSODAの操作

- RESTのためのSODAのインストール

- RESTのためのSODAのスタート・ガイド

- 新規コレクションの作成

- 利用可能なコレクションのリストの取得

- コレクションの削除

- コレクションへのドキュメントの挿入

- コレクションからのドキュメントの取得

- コレクションからのドキュメントの削除

- JSON配列からのドキュメントの一括挿入

- コレクション内のドキュメントのリスト

- コレクション内のドキュメントの更新

- フィルタ仕様を使用したコレクションからのドキュメントの選択

- QBE.1.json

- QBE.2.json

- QBE.3.json

- QBE.4.json

- RESTのためのSODAのHTTP操作

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

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

- GET schema

- GET schemaのURLパターン

- GET schemaのレスポンス・コード

- GET collection

- GET collectionのURLパターン

- GET collectionのレスポンス・コード

- GET collectionのリンク配列

- GET object

- GET objectのURLパターン

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

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

- PUT collection

- PUT collectionのURLパターン

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

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

- PUT object

- PUT objectのURLパターン

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

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

- DELETE collection

- DELETE collectionのURLパターン

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

- DELETE object

- DELETE objectのURLパターン

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

- POST object

- POST objectのURLパターン

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

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

- POST query

- POST queryのURLパターン

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

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

- POST array insert

- POST array insertのURLパターン

- POST array insertのリクエスト・ボディ

- POST array insertのレスポンス・コード

- POST bulk delete

- POST bulk deleteのURLパターン

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

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

- コレクション仕様

- キーの割当て方法

- バージョン管理方法

- セキュリティ

- 認証メカニズム

- 開発およびテストのセキュリティ上の考慮事項

索引

例の一覧

- 1-1 レスポンス・ボディ

- 1-2 コレクション仕様

図一覧

表一覧

- 1-1 RESTのためのSODAのHTTP操作

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

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

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

- 1-5 コレクション仕様のフィールド

- 1-6 キーの割当て方法

- 1-7 バージョン管理方法

はじめに

このドキュメントでは、REST APIのためのOracle SODAの使用方法について説明します。

対象読者

このドキュメントは、RESTのためのSODAユーザーを対象としています。

ドキュメントのアクセシビリティについて

Oracleのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWeb サイト(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc)を参照してください。

Oracle Supportへのアクセス

サポートをご購入のOracleのお客様は、My Oracle Supportにアクセスして電子サポートを受けることができます。詳細情報は(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info) か、聴覚に障害のあるお客様は (http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs)を参照してください。

関連ドキュメント

なし

表記規則

このマニュアルでは次の表記規則を使用します。

規則

意味

太字

太字は、操作に関連するGraphical User Interface要素、または本文中で定義されている用語および用語集に記載されている用語を示します。

イタリック体

イタリックは、ユーザーが特定の値を指定するプレースホルダ変数を示します。

固定幅フォント

固定幅フォントは、段落内のコマンド、URL、サンプル内のコード、画面に表示されるテキスト、または入力するテキストを示します。

window.name='rest' function footdisplay(footnum,footnote) { var msg = window.open('', 'NewWindow' + footnum, 'directories=no,height=120,location=no,menubar=no,resizable=yes,' + 'scrollbars=yes,status=no,toolbar=no,width=598'); msg.document.open('text/html'); }
1 RESTのためのSODA

インストール方法や使用方法など、REST APIのためのOracle SODAについて説明します。

次の内容を理解しておくと、ここで示す情報を最大限に活用できます。

- Oracleリレーショナル・データベース管理システム(RDBMS)

- JavaScript Object Notation(JSON)

- Hypertext Transfer Protocol(HTTP)

関連項目:

- Oracle Database JavaのためのSODA開発者ガイド。RESTのためのSODAが構築されるJavaクライアントAPIの使用方法について説明しています。

- Oracle DatabaseでのJSONの情報については、Oracle Database JSON開発者ガイド

トピック

- RESTのためのSODAの概要

- RESTのためのSODAのインストール

- RESTのためのSODAのスタート・ガイド

- RESTのためのSODAのHTTP操作

- コレクション仕様

- セキュリティ

RESTのためのSODAの概要

Simple Oracle Document Access (略してSODA)を使用すると、Oracle Databaseのドキュメントのコレクションを作成および格納することができ、Structured Query Language (SQL)や、ドキュメントのデータがどのようにデータベースに格納されているかを理解していなくても、そのコレクションの取得や問合せを行うことができます。

RESTのためのSODAは、Representational State Transfer (REST)アーキテクチャ・スタイルを使用してSODAを提供するREST API です。これを使用して、あらゆる種類のドキュメントについて作成、読取り、更新および削除(CRUD)操作を実行することや、JSONドキュメントを問い合せることができます。

注意:

RESTのためのSODAで使用されるドキュメントは、約2 GBに制限されています。

注意:

データベース文字セットにはAL32UTF8 (Unicode)を使用することをお薦めします。そうでない場合は、次のようになります。

- データベース文字セットへの変換で情報が失われるため、データは、入力中に変更される可能性があります。

- 例による問合せ(QBE)で、予測不能な結果が返される可能性があります。

REST

RESTアーキテクチャ・スタイルは、HTTP 1.1およびUniform Resource Identifier(URI)を定義するために使用されました。RESTベースのAPIはHTTPサーバーの提供する基本機能に非常によく似ており、ほとんどのRESTベースのシステムはHTTPクライアントとHTTPサーバーを使用して実装されています。

標準的なRESTの実装では、作成、読取り、更新、削除(CRUD)の操作が、HTTPの動詞であるPOST、GET、PUT、DELETEのそれぞれにマッピングされています。

RESTベース・システムの重要な特性は、ステートレスであるということです。サーバーは、クライアント・オブジェクトの状態の追跡や管理を行いません。RESTベースのサーバーに対して実行される各操作はアトミックです。それ自体が1つのトランザクションと考えられます。標準的なRESTベースのシステムでは、ロックや同時実行制御といったRDBMS環境で当然とされる多くの機能は、アプリケーションに管理が任されています。

RESTベースのシステムの主な利点は、そのサービスが、従来のプログラミング言語(C、C#、C++、JAVA、PL/SQLなど)および最新のスクリプティング言語(JavaScript、Perl、Python、Rubyなど)など、現代のプログラミング・プラットフォームのほとんどすべてから使用できることです。

関連項目:

『Principled Design of the Modern Web Architecture(最新Webアーキテクチャの原則に基づいた設計)』Roy T.Fielding and Richard N.Taylor

http://www.ics.uci.edu/~taylor/documents/2002-REST-TOIT.pdf

ドキュメント・コレクションおよびドキュメント中心のAPI

RESTベースのアプリケーションでは、通常は、ドキュメント・コレクションを使用して状態が維持されます。

ドキュメント・コレクションでは、各ドキュメントは一意の識別子を持ちます。通常、識別子はドキュメントの作成時にサーバーによって割り当てられますが、クライアント割当ての識別子も使用できます。ドキュメント識別子はメタデータ(個々のドキュメントについてのデータ)です。ドキュメント・コレクションでドキュメントごとに追跡できるその他のメタデータとして、それが作成された日付と時間および最後に変更された日付と時間があります。

RESTのためのSODAの操作

RESTのためのSODAでは、RESTアーキテクチャ・スタイルを実装し、Oracle Databaseが管理するドキュメント・コレクションに対してドキュメントの格納や取得を行うことができるHTTPベースのサービスが提供されます。

APIには、実行できる次のようなシンプルな操作のセットが定義されています。

- 利用可能なコレクションのセットのリスト

- コレクションの作成

- コレクションのドロップ

- コレクションへのドキュメントの挿入

- コレクションからのドキュメントの取得

- コレクション内のドキュメントの更新

- コレクションからのドキュメントの削除

- コレクションのコンテンツのリスト

- コレクションの検索

アプリケーションでは、このAPI操作を使用し、アプリケーションのオブジェクトや状態の永続化に使用するJSONオブジェクトを作成および操作できます。JSONドキュメントを生成するため、アプリケーションでJSONのシリアライズ技術を使用できます。アプリケーションでドキュメント・オブジェクトを取得すると、JSONパーサーにより、それがアプリケーション・オブジェクトに変換されます。

関連項目:

RESTのためのSODAで定義された操作の詳細は、RESTのためのSODAのHTTP操作を参照

RESTのためのSODAのインストール

RESTのためのSODAのインストールについて、すべての手順を説明します。

RESTのためのSODAをインストールするには、次の手順を実行します。

1. Oracle Database 12c リリース1 (12.1.0.2)、およびMerge Label Request(MLR)バンドル・パッチ20885778がインストールされていることを確認します。(パッチ20885778によりパッチ20080249は廃止されました。)
パッチは、My Oracle Support(https://support.oracle.com)から入手してください。「パッチと更新版」タブを選択します。パッチ番号20885778を検索するか、または次のURL: https://support.oracle.com/rs?type=patch&id=20885778に直接アクセスします。

2. データベースを起動します。

3. Oracle REST Data Services(ORDS)をダウンロードし、zipファイルを解凍します。

手順の詳細は、『Oracle REST Data Servicesインストレーション、構成および開発ガイド』を参照してください。

4. ORDSを構成します。

- データベースが標準ポート1521を使用している場合:

java -jar ords.war install

- データベースが非標準ポート(1521を除くすべてのポート)を使用している場合:

java -jar ords.war install advanced

注意:

入力を求められたら、次のように指定します。

- Oracle REST Data Servicesスキーマの検証/インストールの手順をスキップしないでください。

- PL/SQLゲートウェイを構成する手順をスキップします。

- Application ExpressのRESTfulサービスのデータベース・ユーザーを構成するステップをスキップします。

- スタンドアロン・サーバーの起動を拒否します。

詳細は、『Oracle REST Data Servicesインストレーション、構成および開発ガイド』を参照してください。

5. ORDSからアクセスするスキーマに接続します。

6. 次のSQLコマンドを実行して、スキーマ内でORDSを有効にします。

EXEC ords.enable_schema;
COMMIT;

7. ロールSODA_APPを、手順6で有効にしたデータベース・スキーマ(ユーザー・アカウント) schemaに付与します。

GRANT SODA_APP TO schema;

8. 開発環境の場合のみ、次の手順を実行します。

a. デフォルトのセキュリティ制約を削除します。

BEGIN
ords.delete_privilege_mapping(
'oracle.soda.privilege.developer',
'/soda/*');
COMMIT;
END;

これにより、サービスへの匿名アクセスが有効になるため、本番システムではお薦めしません。セキュリティの詳細は、「セキュリティ」を参照してください。

b. スタンドアロン・モードでORDSを起動します。

java -jar ords.war standalone

詳細は、『Oracle REST Data Servicesインストレーション、構成および開発ガイド』を参照してください。

注意:

セキュリティを無効にしてスタンドアロン・モードでORDSを実行するのは、本番環境ではお薦めしません。

9. Webブラウザで、次のページを開きます。

http://localhost:8080/ords/schema/soda/latest/

ここで、schemaは、手順 6でORDSを有効にしたスキーマの小文字の名前です。インストールが成功した場合は、次のように表示されます。

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

関連項目:

- セキュリティ

- 『Oracle REST Data Servicesインストレーション、構成および開発ガイド』

RESTのためのSODAのスタート・ガイド

実行可能な例を使用して、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インストレーション、構成および開発ガイド』

手順

1. 新規コレクションの作成

2. 利用可能なコレクションのリストの取得

3. コレクションの削除

4. コレクションへのドキュメントの挿入

5. コレクションからのドキュメントの取得

6. コレクションからのドキュメントの削除

7. JSON配列からのドキュメントの一括挿入

8. コレクション内のドキュメントのリスト

9. コレクション内のドキュメントの更新

10. フィルタ仕様を使用したコレクションからのドキュメントの選択

新規コレクションの作成

新規コレクションの作成について例を示します。

新しいコレクションを作成するには、このコマンドを使用します。ここでの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オブジェクトです。

関連項目:

- GET schema

- コレクション仕様

- コレクションの削除

コレクションの削除

コレクションの削除について例を示します。

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

関連項目:

- DELETE collection

- コレクションへのドキュメントの挿入

コレクションへのドキュメントの挿入

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

この例では、ダウンロードに含まれている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"
}

関連項目:

- GET object

- コレクションからのドキュメントの削除

コレクションからのドキュメントの削除

コレクションからのドキュメントの削除について例を示します。

コレクションからのドキュメントの取得で取得したドキュメントを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操作)は、レスポンス・ボディを戻しません。

関連項目:

- DELETE object

- JSON配列からのドキュメントの一括挿入

JSON配列からのドキュメントの一括挿入

ドキュメントの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構文は使用できません。

関連項目:

- POST array insert

- コレクション内のドキュメントのリスト

コレクション内のドキュメントのリスト

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の値)をコピーします。

関連項目:

- GET collection

- コレクション内のドキュメントの更新

- コンテンツに基づいてドキュメントをリストする方法は、「フィルタ仕様を使用したコレクションからのドキュメントの選択」を参照

- 構成パラメータ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...."
}

関連項目:

- PUT object

- キーの割当て方法

- フィルタ仕様を使用したコレクションからのドキュメントの選択

フィルタ仕様を使用したコレクションからのドキュメントの選択

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

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

関連項目:

- POST query

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

QBE.1.json

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.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.3.jsonファイル内の例による問合せ(QBE)では、オブジェクトLineItems内のフィールドItemNumberの値が4より大きいドキュメントが選択されます。キーワード"$gt"は必要です。

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

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

QBE.4.json

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

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

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

関連項目:

Oracle Database SODA for Java開発者ガイド

RESTのためのSODAのHTTP操作

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

表1-1に、RESTのためのSODAによって提供されるHTTP操作をまとめます。操作の完全な説明を参照するには、左の列のリンクをクリックします。

表1-1 RESTのためのSODAのHTTP操作

操作

説明

GET schema

スキーマ内のコレクション名の一部またはすべてを取得します。

GET collection

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

GET object

指定したオブジェクトをコレクションから取得します。

PUT collection

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

PUT object

アップロードしたオブジェクト(通常は新規バージョン)で指定したオブジェクトを置き換えます。

コレクションがクライアントによって割り当てられたキーを持ち、アップロードしたオブジェクトがコレクションに存在しない場合は、PUTはアップロードしたオブジェクトをコレクションに挿入します。

DELETE collection

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

DELETE object

指定したオブジェクトをコレクションから削除します。

POST object

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

POST query

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

POST array insert

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

POST bulk delete

コレクションからオブジェクトのすべて、またはそのサブセットを削除します。

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

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操作のレスポンス・ボディ

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

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

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

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

フィールド

説明

key

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

etag

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

created

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

lastModified

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

value

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

mediaType

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

bytes

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

items

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

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

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

フィールド

説明

name

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

properties

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

hasMore

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

limit

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

offset

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

count

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

totalResults

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

links

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

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

例1-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は、スキーマ内のコレクション名のすべて、またはそのサブセットを取得します。

関連項目:

コレクション内のドキュメントのリスト

GET schemaのURLパターン

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

/ords/schema/soda/version/

パラメータを指定しなければ、GET schemaによりschema内のすべてのコレクション名が取得されます。

パラメータ

説明

limit=n

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

fromID=collection

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

GET 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

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

関連項目:

- POST queryは、パラメータのかわりにフィルタを使用してコレクションからオブジェクトのすべてまたはサブセットを取得します。戻されるオブジェクトのセットはページングできません。

- コレクション内のドキュメントのリスト

GET collectionのURLパターン

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

/ords/schema/soda/version/collection/

パラメータを指定しなければ、GET collectionにより、collectionからすべてのオブジェクト(キーとコンテンツの両方)が取得され、collection内のオブジェクトの数は戻されません。

注意:

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

パラメータ

説明

limit=n

リストするオブジェクトの数をnに制限します。

offset=n

最初のオブジェクトを取得する前にn個のオブジェクトをスキップします。

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より後のタイム・スタンプを持つオブジェクトのみを取得します。

until=timestamp

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

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のリンク配列

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

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

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

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

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

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

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

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

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

パラメータ

モード

リンク配列

fields=id

キーのみ

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

offset=n

オフセット

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

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

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

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

fromID=key

toID=key

after=key

before=key

キー

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

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

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

since=timestamp

until=timestamp

タイムスタンプ

存在しません。

GET object

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

関連項目:

コレクションからのドキュメントの取得

GET objectのURLパターン

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

/ords/schema/soda/version/collection/key/

パラメータはありません。

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

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

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

ヘッダー

説明

If-Modified-Since=timestamp

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

If-None-Match

オブジェクトのetagが現在のチェックサムまたはバージョンに一致する場合、レスポンス・コード304が戻されます。

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

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

200

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

204

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

304

etagオブジェクトと一致する変更日またはチェックサムから、どのオブジェクトも変更されていません(「GET objectのリクエスト・ヘッダー」を参照)。

401

コレクションまたはオブジェクトの読取りアクセスが許可されていません。

404

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

PUT collection

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

関連項目:

新規コレクションの作成

PUT collectionのURLパターン

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

/ords/schema/soda/version/collection/

パラメータはありません。

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

PUT collectionのリクエスト・ボディを説明します。

「コレクション仕様」を参照してください。

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

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

200

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

201

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

401

コレクションの作成が許可されていません。

PUT object

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

関連項目:

コレクション内のドキュメントの更新

PUT objectのURLパターン

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

/ords/schema/soda/version/collection/key/

パラメータはありません。

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

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

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

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

200

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

401

コレクションの更新が許可されていません。

405

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

DELETE collection

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

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

関連項目:

コレクションの削除

DELETE collectionのURLパターン

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

/ords/schema/soda/version/collection/

パラメータはありません。

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

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

200

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

401

コレクションの削除が許可されていません。

404

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

DELETE object

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

関連項目:

コレクションからのドキュメントの削除

DELETE objectのURLパターン

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

/ords/schema/soda/version/collection/key/

パラメータはありません。

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

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

200

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

401

コレクションからの削除、またはこのオブジェクトの削除のいずれかが許可されていません。

404

オブジェクトが見つかりませんでした。

405

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

POST object

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

コレクションが、クライアントによって割り当てられるキーを使用する場合は、PUT objectを使用します。キーの割当て方法の詳細は、「キーの割当て方法」を参照してください。

関連項目:

コレクションへのドキュメントの挿入

POST objectのURLパターン

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

/ords/schema/soda/version/collection/

パラメータはありません。

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

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

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

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

201

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

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

202

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

401

コレクションへの挿入が許可されていません。

405

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

501

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

POST query

POST queryは、サブセットを指定するフィルタを使用してコレクションからオブジェクトのすべて、またはそのサブセットを取得します。戻されるオブジェクトのセットはページングできません。

関連項目:

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

- フィルタ仕様を使用したコレクションからのドキュメントの選択

POST queryのURLパターン

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

/ords/schema/soda/version/collection?action=query

パラメータは、注意書きのある場合を除きオプションです。

パラメータ

説明

action=query

必須。アクションの種類を指定します。

limit=n

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

offset=n

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

fields={id|value|all}

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

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

POST queryのリクエスト・ボディからフィルタ仕様オブジェクトを省略した場合、操作ではコレクション内のすべてのオブジェクトが取得されます。

関連項目:

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

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

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

200

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

404

コレクションが見つからないか、コレクションへの読取りアクセスが許可されていないかのいずれかです。

POST array insert

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

関連項目:

JSON配列からのドキュメントの一括挿入

POST array insertのURLパターン

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

/ords/schema/soda/version/collection?action=insert

パラメータ

説明

action=insert

必須。アクションの種類を指定します。

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

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

オブジェクトの配列です。

POST array insertのレスポンス・コード

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

200

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

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

401

コレクションへの挿入が許可されていません。

404

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

405

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

POST bulk delete

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

注意:

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

POST bulk deleteのURLパターン

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

次のいずれかです。

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

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

パラメータ

説明

action=delete

必須。サブセットを指定するオプションのフィルタを使用してcollectionからオブジェクトのすべて、またはそのサブセットを削除することを指定します。次の警告を参照してください。

action=truncate

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

警告:

action=deleteを指定し、フィルタ仕様を省略するか、またはフィルタ仕様が空の場合、その操作によりコレクションのすべてのオブジェクトが削除されます。

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

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

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

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

200

成功 - レスポンス・ボディには削除されたコレクションの数が含まれています。次に例を示します。

{
"count" : 42
}

401

コレクションからの削除が許可されていません。

405

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

コレクション仕様

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

注意:

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

表1-5に、コレクション仕様のフィールドおよび使用可能な値を説明します。

注意:

オプション列(作成日のタイム・スタンプ、最終変更タイム・スタンプ、バージョンまたはメディア・タイプ)のいずれかをコレクション仕様から省略した場合、その列は作成されません。少なくとも、コレクションにはキー列とコンテンツ列があります。

表1-5 コレクション仕様のフィールド

フィールド

説明

使用可能な値

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言語リファレンス』を参照してください。

例1-2は、基本となる表がHR.EMPLOYEESであるオブジェクトのコレクション仕様です。

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

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

関連項目:

- キーの割当て方法

- バージョン管理方法

- SQL条件is jsonによって使用される構文の可能性の詳細は、『Oracle Database JSON開発者ガイド』を参照

- JSON RFC 4627標準については、http://tools.ietf.org/html/rfc4627を参照

- SecureFiles LOB記憶域の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照

キーの割当て方法

キーの割当て方法は、コレクションに挿入されたオブジェクトにどのようにキーを割り当てるかを決定します。

表1-6 キーの割当て方法

方法

説明

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が推奨されます。これにより、キーからデータベース・キャラクタ・セットへの変換がロスレスになります。

それ以外の場合、クライアント割当てキーにデータベース・キャラクタ・セットでサポートされない文字が含まれる場合、読取りまたは書込み操作時に、データベース・キャラクタ・セットへのキーの変換は失われます。これにより、挿入操作中に重複キー・エラーが発生することがあります。もっと一般的に言うと、予測できない結果が生じることがあります。たとえば、読取り操作で、予定したキーとは異なるキーに関連付けられている値が返されることがあります。

バージョン管理方法

バージョン管理方法は、オブジェクトがコレクションに挿入またはコレクション内のオブジェクトが置換されたとき、RESTサーバーがオブジェクトのバージョン値を計算する方法を決定します。

表1-7 バージョン管理方法

方法

説明

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

セキュリティ

RESTのためのSODAなどのORDSでは、サービスを保護するためにロールベースのアクセス制御が使用されます。ここでは、RESTのためのSODAに必要なロールおよび権限について説明しています。

この項を読む前に、ORDSのセキュリティ機能に精通している必要があります。関連する情報は、『Oracle REST Data Servicesインストレーション、構成および開発ガイド』を参照してください。

REST SODAを使用する前に、データベース・ロールSODA_APPをデータベース・ユーザーに付与する必要があります。さらに、ords.enable_schemaを使用してORDSでスキーマを有効にする際に、アプリケーション・サーバー・ロールSODA Developerを持つユーザーのみがサービスにアクセスできるように、権限が作成されます。具体的には、ords.enable_schemaは次の権限マッピングを作成します。

exec ords.create_role('SODA Developer');
exec ords.create_privilege(p_name => 'oracle.soda.privilege.developer',
p_role_name => 'SODA Developer');
exec ords.create_privilege_mapping('oracle.soda.privilege.developer', '/soda/*');

このことは、デフォルトで、JSONドキュメント・ストアにアクセスするにはユーザーはアプリケーション・サーバー・ロールSODA Developerを持っている必要があることに影響します。

カスタムの権限マッピングを追加することもできます。次に例を示します。

declare
l_patterns owa.vc_arr;
begin
l_patterns(1) := '/soda/latest/employee';
l_patterns(2) := '/soda/latest/employee/*';
ords.create_role('EmployeeRole');
ords.create_privilege(p_name      => 'EmployeePrivilege',
p_role_name => 'EmployeeRole');
ords.create_privilege_mapping(p_privilege_name => 'EmployeePrivilege',
p_patterns       => l_patterns);
commit;
end;

この例では、EmployeeRoleロールを持つユーザーのみがemployeeコレクションにアクセスできるように指定する権限マッピングを作成します。

複数の権限パターンが同じリソースに適用された場合、最も具体的なパターンを持つ権限が他の権限よりも優先されます。たとえば、パターン/soda/latest/employees/*および/soda/*は、どちらもリクエストURL http://example.org/ords/quine/soda/latest/employee/id1と一致します。

'/soda/latest/employees/*'は'/soda/*'よりも具体的であるため、EmployeePrivilege権限のみがこのリクエストに適用されます。

注意:

SODA_APPはOracle Databaseロールです。SODA Developerはアプリケーション・サーバー・ロールです。

認証メカニズム

ORDSは、様々な認証メカニズムをサポートしています。JSONドキュメント・ストアRESTサービスは、サーバー間の相互作用に使用されることを意図しています。このため、JSONドキュメント・ストアRESTサービスで使用する認証メカニズムとしては、Two-Legged OAuth(クライアント資格証明フロー)をお薦めします。しかし、HTTP Basic認証など、その他のメカニズムもサポートされています。

関連項目:

『Oracle REST Data Servicesインストレーション、構成および開発ガイド』

開発およびテストのセキュリティ上の考慮事項

開発およびテストのセキュリティ上の考慮事項を示します。

次のように、デフォルトの権限マッピングを削除することで、セキュリティを無効にし、匿名アクセスを許可できます。

exec ords.delete_privilege_mapping('oracle.soda.privilege.developer', '/soda/*')

しかし、本番システムで匿名アクセスを許可することはお薦めしません。匿名アクセスの許可は、認証されていないユーザーに任意のコレクションの読取り、更新、またはドロップを許可することになります。

また、ords.war userコマンド使用して特定のロールを持つテスト・ユーザーを作成できます。次に例を示します(new_passwordは、ユーザーbobのパスワードのプレースホルダです)。

# Create user bob with role SODA Developer
java -jar ords.war user bob "SODA Developer"

# Access the JSON document store as user bob using basic authentication
curl -u bob:new_password https://example.com/ords/scott/soda/latest/

索引

C  D  F  G  I  K  L  O  P  Q  R  S  U  V

C

- コレクション

- 作成 1

- 削除 1

- ドキュメントの削除 1

- リスト 1

- ドキュメントのリスト 1

- 仕様 1

D

- データベース・ロール

- SODA_APP 1

- DELETE collection操作 1

- DELETE object操作 1

- コレクションの削除 1

- コレクションからのドキュメントの削除 1

- ドキュメント

- コレクションからの削除 1

- コレクションのフィルタリング 1

- コレクションへの挿入

- JSON配列から一括 1

- 一度に1つ 1

- コレクションのリスト 1

- コレクションから取得 1

- コレクションの更新 1

F

- コレクション内のドキュメントのフィルタリング 1

G

- GET collection操作 1

- GET object操作 1

- GET schema操作 1

I

- コレクションへのドキュメントの挿入

- JSON配列から一括 1

- 一度に1つ 1

- RESTのためのSODAのインストール 1

K

- キーの割当て方法 1

L

- スキーマ内のコレクションのリスト 1

- コレクション内のドキュメントのリスト 1

O

- Oracle REST API 1

- Oracle REST APIのHTTP操作

- レスポンス・ボディ 1

- 概要 1

- URIフォーム 1

P

- POST array insert操作 1

- POST bulk delete操作 1

- POST object操作 1

- POST query操作 1

- PUT collection操作 1

- PUT object操作 1

Q

- 例による問合せ(QBE)

- 例 1

R

- RESTアーキテクチャ・スタイル 1

- コレクションからのドキュメントの取得 1

S

- セキュリティ 1

- SODA_APPデータベース・ロール 1

- 仕様

- コレクション 1

U

- コレクション内のドキュメントの更新 1

V

- バージョン管理方法 1

オラクルの法律上の注意点について

コピーライトについて

Copyright © 1994-2017, Oracle and/or its affiliates. All rights reserved.

ライセンス制約の保証と結果的に生じる損害の免責

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

保証免責

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクルまでご連絡ください。

制限付権利について

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

危険な用途への使用について

このソフトウェアまたはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアまたはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアまたはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアまたはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、Oracle Corporationおよびその関連会社は一切の責任を負いかねます。

商標と登録商標について

OracleおよびJavaはオラクルおよびその関連会社の登録商標です。その他の社名、商品名等は各社の商標または登録商標である場合があります。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

第三者のコンテンツ、製品、サービスに対する免責事項

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。適用されるお客様とOracle Corporationとの間の契約に別段の定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。適用されるお客様とOracle Corporationとの間の契約に定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

アルファ版およびベータ版ドラフト・ドキュメントについて

このドキュメントが試作版の場合:

このドキュメントは試作版であり、デモおよび暫定使用のみを目的としたものです。このソフトウェアを使用するハードウェアに限定するものではありません。Oracle Corporationおよびその関連会社は、このドキュメントに関して一切の責任を負わず、いかなる保証もいたしません。また、このドキュメントを使用したことによって損失、費用、あるいは損害が発生しても、一切の責任を負いかねます。

非公開のアルファ版およびベータ版ドラフト・ドキュメントについて

このドキュメントが非公開の試作版の場合:

このドキュメントに含まれる情報は、情報の共有のみを目的としたものであって、顧客諮問委員会(Customer Advisory Board)のメンバーとしてのお客様の立場でのみ、またはお客様のベータ・トライアル契約のみに従って検討されるべきものとします。マテリアル、コード、または機能の提供をお約束するものではなく、購入決定を行う際の判断材料とすべきではありません。このドキュメントに記載されている特徴または機能の開発、リリースおよび時期については、オラクルの裁量により決定されます。

このドキュメントには、ソフトウェアまたは印刷物などの形式を問わず、オラクルが独占的な権利を有する財産的情報が含まれています。この機密資料へのアクセスと使用は、お客様とオラクルとの間で締結され、お客様が遵守に同意した、Oracle Master Agreement、Oracle License and Oracle Services Agreement (オラクル・ライセンスおよびサービスに関する契約書)、Oracle PartnerNetwork Agreement、Oracle Distribution Agreementまたはその他のライセンス契約の条件に従うものとします。このドキュメントとその内容の開示、コピー、複製および配布には、オラクルによる事前の承諾を必要とします。このドキュメントはライセンス契約の一部となるものではなく、オラクルおよびその子会社や関連会社との契約を構成するものではありません。

ドキュメントのアクセシビリティについて

オラクルのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイトhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc を参照してください。

Oracle Supportへのアクセス

サポートをご契約のお客様には、My Oracle Supportを通して電子支援サービスを提供しています。詳細情報はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=infoか、聴覚に障害のあるお客様はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsを参照してください。