Oracle® REST Data Services

インストレーション、構成および開発ガイド

リリース3.0.11

E62039-09(原本部品番号:E87809-03)

2017年7月

Oracle REST Data Servicesをインストールおよび構成し、Oracle REST Data Servicesを使用するアプリケーションを開発する方法を説明します。

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

E62039-09

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

原本著者: Mamata Basapur、Chuck Murray

原本協力者: Colm Divilly、Sharon Kennedy、Ganesh Pitchaiah、Kris Rice、Elizabeth Saunders、Jason Straub、Vladislav Uvarov

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

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

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

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 Oracle REST Data Servicesのインストール

- 1.1 Oracle REST Data Servicesについて

- 1.2 インストール・プロセスの理解

- 1.2.1 サポートされるJava EEアプリケーション・サーバー

- 1.2.2 システム要件

- 1.2.3 Oracle REST Data Servicesのインストールについて

- 1.3 Oracle REST Data Servicesの構成およびインストール

- 1.3.1 コマンドライン・インタフェースの使用について

- 1.3.2 Oracle REST Data Servicesで使用されるデータベース・ユーザーについて

- 1.3.3 Oracle REST Data Servicesによって付与される権限

- 1.3.4 Oracle REST Data Servicesのダウンロード、構成およびインストール

- 1.3.4.1 パラメータ・ファイルを使用した簡易インストール

- 1.3.4.2 コマンドライン・プロンプトを使用した拡張インストール

- 1.3.4.3 Oracle REST Data Servicesインストールの検証

- 1.3.4.4 Oracle REST Data Servicesを再インストールまたはアンインストール(削除)する場合

- 1.3.5 SQL Developerを使用したOracle REST Data Servicesの管理(オプション)

- 1.3.5.1 SQL DeveloperのOracle REST Data Services管理について

- 1.3.5.2 管理者ユーザーの構成

- 1.3.6 非HTTPS環境でOAuth2の使用

- 1.4 スタンドアロン・モードでの実行

- 1.4.1 スタンドアロン・モードでの起動

- 1.4.1.1 DERへの秘密鍵の変換(LinuxおよびUNIX)

- 1.4.2 スタンドアロン・モードのサーバーの停止

- 1.4.3 非Application Expressの静的リソースのドキュメント・ルートの構成

- 1.5 Oracle WebLogic Serverへのデプロイ

- 1.5.1 Oracle WebLogic Serverについて

- 1.5.2 Oracle REST Data Servicesのダウンロード、インストールおよび構成

- 1.5.3 Oracle Application Expressイメージの構成

- 1.5.4 管理サーバー・コンソールの起動

- 1.5.5 Oracle WebLogic Serverデプロイのインストール

- 1.5.6 HTTPのBasicチャレンジを正しく処理するためのWebLogicの構成

- 1.5.7 ordsおよびiの状態と健全性の検証

- 1.6 GlassFish Serverへのデプロイ

- 1.6.1 GlassFish Serverについて

- 1.6.2 Oracle REST Data Servicesのダウンロード、インストールおよび構成

- 1.6.3 Oracle Application Expressイメージの構成

- 1.6.4 管理サーバー・コンソールの起動

- 1.6.5 GlassFish Serverデプロイのインストール

- 1.7 Apache Tomcatへのデプロイ

- 1.7.1 Apache Tomcatについて

- 1.7.2 Oracle REST Data Servicesのダウンロード、インストールおよび構成

- 1.7.3 Oracle Application Expressイメージの構成

- 1.7.4 Apache Tomcatデプロイのインストール

- 1.8 Oracle REST Data Servicesのアップグレード

- 1.9 Bequeath接続を使用したOracle REST Data Servicesのインストール、アップグレード、検証またはアンインストール

2 Oracle REST Data Servicesの構成(詳細)

- 2.1 複数データベースの構成

- 2.1.1 リクエストURLについて

- 2.1.2 追加のデータベースの構成

- 2.1.3 リクエスト・パスの接頭辞に基づくルーティング

- 2.1.3.1 リクエスト・パスの接頭辞に基づくルーティングの例

- 2.1.4 リクエストURLの接頭辞に基づくルーティング

- 2.1.4.1 リクエストURLの接頭辞に基づくルーティングの例

- 2.2 RAC Fast Connection Failoverのサポート

- 2.3 セキュリティ、キャッシュ、前処理と後処理、環境、およびExcel設定の構成

- 2.4 Oracle REST Data Servicesで使用するRESTfulサービスの開発

3 Oracle REST Data Servicesアプリケーションの開発

- 3.1 関連するソフトウェアの紹介

- 3.1.1 Oracle Application Expressについて

- 3.1.2 RESTful Webサービスについて

- 3.2 RESTfulサービスのスタート・ガイド

- 3.2.1 RESTfulサービスの用語

- 3.2.2 リクエスト・パスの構文要件について

- 3.2.3 インストールに含まれるドキュメント「スタート・ガイド」

- 3.2.4 cURLおよびRESTfulサービスのテストについて

- 3.2.5 RESTアクセスのためのスキーマ・オブジェクトの自動的な有効化(AutoREST)

- 3.2.5.1 例: RESTfulサービスを使用してオブジェクトにアクセスする

- 3.2.5.1.1 スキーマ・メタデータのGet

- 3.2.5.1.2 オブジェクト・メタデータのGet

- 3.2.5.1.3 オブジェクト・データのGet

- 3.2.5.1.4 ページ区切りを使用した表データのGet

- 3.2.5.1.5 問合せを使用した表データのGet

- 3.2.5.1.6 主キーを使用した表の行のGet

- 3.2.5.1.7 表の行の挿入

- 3.2.5.1.8 表の行の更新/挿入

- 3.2.5.1.9 フィルタを使用したDelete

- 3.2.5.1.10 バッチ・ロードによるPost

- 3.2.5.2 問合せでのフィルタリング

- 3.2.5.2.1 FilterObjectの文法

- 3.2.5.2.2 例: FilterObjectの記述

- 3.2.5.3 自動PL/SQL

- 3.2.5.3.1 PL/SQLオブジェクトの自動有効化がサポートされているメソッドとコンテンツ・タイプ

- 3.2.5.3.2 PL/SQLオブジェクトの自動有効化

- 3.2.5.3.3 PL/SQLエンドポイントの生成

- 3.2.5.3.4 リソース入力ペイロード

- 3.2.5.3.5 リソース・ペイロード・レスポンス

- 3.2.5.3.6 ファンクションの戻り値

- 3.2.6 SQLおよびPL/SQLを使用したRESTful Servicesの手動作成

- 3.2.6.1 Oracle REST Data Servicesのパラメータ引き渡しメカニズムについて

- 3.2.6.1.1 JSONを使用したパラメータの引き渡し

- 3.2.6.1.2 ルート・パターンを使用したパラメータの引き渡し

- 3.2.6.1.3 オプションのパラメータのための問合せ文字列の使用

- 3.2.6.2 SQL/JSONデータベース・ファンクションのORDSとの使用

- 3.2.6.2.1 ネストされたJSONオブジェクトの関係表への挿入

- 3.2.6.2.2 階層リレーショナル・データからのネストされたJSONオブジェクトの生成

- 3.2.6.2.3 RESTfulサービスのテスト

- 3.2.7 ORDSを使用した日付の処理

- 3.2.7.1 Oracle REST Data Servicesによる日時処理について

- 3.2.7.2 ORDSが使用するタイムゾーンの設定について

- 3.2.7.3 Application ExpressでのサンプルのRESTfulサービスの調査(チュートリアル)

- 3.3 RESTfulサービスへのセキュアなアクセスの構成

- 3.3.1 認証

- 3.3.1.1 ファースト・パーティのCookieベースの認証

- 3.3.1.2 サード・パーティのOAuth 2.0ベースの認証

- 3.3.1.2.1 Two-LeggedおよびThree-LeggedのOAuthフロー

- 3.3.2 リソースにアクセスするための権限について

- 3.3.3 リソースにアクセスするためのユーザーおよびロールについて

- 3.3.4 ファイルベースのユーザー・リポジトリについて

- 3.3.5 チュートリアル: リソースの保護およびアクセス

- 3.3.5.1 OAuthフローと各フローの用途

- 3.3.5.2 このチュートリアルの前提

- 3.3.5.3 このチュートリアルの手順

- 3.4 Oracle REST Data Servicesのユーザー・ロールについて

- 3.4.1 Oracle Application ExpressのユーザーとOracle REST Data Servicesのロールについて

- 3.4.1.1 Application ExpressユーザーにOracle REST Data Servicesロールを付与する

- 3.4.1.2 Application Expressユーザーに自動的にOracle REST Data Servicesロールを付与する

- 3.4.2 ロールによるRESTfulサービスのアクセス制御

- 3.4.2.1 RESTfulサービスのロールの定義について

- 3.4.2.2 ロールとRESTful権限の関連付け

- 3.5 WebLogic ServerおよびGlassFishユーザー・リポジトリに対する認証

- 3.5.1 WebLogic Serverに対する認証

- 3.5.1.1 WebLogic Serverユーザーの作成

- 3.5.1.2 WebLogic Serverユーザーの検証

- 3.5.2 GlassFishに対する認証

- 3.5.2.1 GlassFishユーザーの作成

- 3.5.2.2 GlassFishユーザーの検証

- 3.6 既存のグループ/ロール・モデルとの統合

- 3.6.1 role-mapping.xmlについて

- 3.6.1.1 マッピング・ルールのパラメータ化

- 3.6.1.2 パラメータの間接参照

- 3.6.1.3 間接マッピング

- 3.7 Oracle REST Data Services PL/SQL APIの使用

- 3.7.1 PL/SQL APIを使用したRESTfulサービスの作成

- 3.7.2 RESTfulサービスのテスト

4 NoSQLおよびOracle REST Data Services

- 4.1 NoSQLおよびOracle REST Data Servicesについて

- 4.1.1 テクノロジ環境

- 4.1.2 標準的なOracle REST Data Servicesの入力および出力

- 4.2 NoSQLストアのインストールおよび登録

- 4.3 Oracle REST Data Servicesで使用するNoSQLストアの追加および削除

- 4.4 NoSQL RESTサービス

- 4.4.1 メタデータ・サービス

- 4.4.1.1 メタデータ読取り(GET)

- 4.4.2 データ・サービス

- 4.4.2.1 データの読取り(GET)

- 4.4.2.2 べき等書込み(PUT)

- 4.4.2.3 書込み(POST)

- 4.4.2.4 削除(DELETE)

- 4.4.3 DDLサービス

- 4.4.3.1 作成/更新(POST)

- 4.4.3.2 ドロップ(POST)

- 4.4.3.3 ポーリング(GET)

- 4.4.4 共通パラメータ

- 4.4.4.1 結果をスキップおよび結果の数を制限するパラメータ

- 4.4.4.2 問合せ条件を指定するパラメータ

- 4.4.4.3 方向(順序)、一貫性および永続性保証を指定するパラメータ

5 ORDS PL/SQLパッケージのリファレンス

- 5.1 ORDS.CREATE_ROLE

- 5.2 ORDS.CREATE_SERVICE

- 5.3 ORDS.DEFINE_HANDLER

- 5.4 ORDS.DEFINE_MODULE

- 5.5 ORDS.DEFINE_PARAMETER

- 5.6 ORDS.DEFINE_PRIVILEGE

- 5.7 ORDS.DEFINE_SERVICE

- 5.8 ORDS.DEFINE_TEMPLATE

- 5.9 ORDS.DELETE_MODULE

- 5.10 ORDS.DELETE_PRIVILEGE

- 5.11 ORDS.DELETE_ROLE

- 5.12 ORDS.DROP_REST_FOR_SCHEMA

- 5.13 ORDS.ENABLE_OBJECT

- 5.14 ORDS.ENABLE_SCHEMA

- 5.15 ORDS.PUBLISH_MODULE

- 5.16 ORDS.RENAME_MODULE

- 5.17 ORDS.RENAME_PRIVILEGE

- 5.18 ORDS.RENAME_ROLE

- 5.19 ORDS.SET_MODULE_ORIGINS_ALLOWED

- 5.20 ORDS.SET_URL_MAPPING

6 OAUTH PL/SQLパッケージのリファレンス

- 6.1 OAUTH.CREATE_CLIENT

- 6.2 OAUTH.DELETE_CLIENT

- 6.3 OAUTH.GRANT_CLIENT_ROLE

- 6.4 OAUTH.RENAME_CLIENT

- 6.5 OAUTH.REVOKE_CLIENT_ROLE

- 6.6 OAUTH.UPDATE_CLIENT

A ORDSデータベース・タイプ・マッピング

- A.1 Oracle組込み型

- A.2 構造化されたデータベース・タイプの処理

- A.3 Oracle Geospacial Encoding

- A.4 データベース・マッピング・サポートの有効化

B Oracle REST Data Servicesの構成ファイルについて

- B.1 構成ファイルの検索

- B.2 構成ファイルの場所を設定する

- B.3 構成フォルダの構造を理解する

- B.4 構成ファイルの形式を理解する

- B.4.1 url-mapping.xmlファイルの形式を理解する

- B.5 構成可能なパラメータの理解

C Oracle REST Data Servicesのトラブルシューティング

- C.1 デバッグ・トレースの有効化

- C.2 詳細なリクエスト・エラー・メッセージの有効化

- C.3 Oracle REST Data ServicesでのApplication Expressの静的リソースの構成

D 開発チュートリアル: イメージ・ギャラリの作成

- D.1 はじめに

- D.1.1 URIについて

- D.1.2 ブラウザのサポートについて

- D.1.3 Application Expressワークスペースの作成

- D.2 ギャラリ・データベース表の作成

- D.3 ギャラリRESTfulサービス・モジュールの作成

- D.4 ギャラリRESTfulサービスの試用

- D.5 ギャラリ・アプリケーションの作成

- D.6 ギャラリ・アプリケーションの試用

- D.7 ギャラリRESTfulサービスの保護

- D.7.1 RESTfulサービスの保護

- D.7.2 ファースト・パーティ認証を使用するためのアプリケーションの変更

- D.8 サード・パーティ・アプリケーションからのRESTfulサービスへのアクセス

- D.8.1 サード・パーティの開発者ユーザーの作成

- D.8.2 サード・パーティ・アプリケーションの登録

- D.8.3 アクセス・トークンの取得

- D.8.4 アクセス・トークンの使用

- D.8.5 ブラウザのオリジンについて

- D.8.6 クロス・オリジン・リソース共有のためのRESTfulサービスの構成

- D.8.7 認可コード・プロトコル・フローを使用したトークンの取得

- D.8.7.1 クライアント・アプリケーションの登録

- D.8.7.2 認可コードの取得

- D.8.7.3 認可コードとアクセス・トークンの交換

- D.8.7.4 OAuth 2.0セッションの継続時間の延長

- D.8.8 アクセス・トークンの保護について

E Oracle REST Data Servicesでのマルチテナント・アーキテクチャの使用

- E.1 インストールの選択項目の理解

- E.2 Oracle REST Data ServicesのCDBへのインストール

- E.3 CDB環境でのOracle REST Data Servicesのアップグレード

- E.4 Oracle REST Data Servicesによって、すべてのPDBをアドレス可能にする(プラガブル・マッピング)

- E.5 CDB環境でのOracle REST Data Servicesのアンインストール

F RESTfulサービスのスタート・ガイド

- F.1 データベース表のREST対応

- F.2 SQL問合せからのRESTfulサービスの作成

- F.3 リソースの保護

- F.4 接続ナビゲータを介したRESTful Serviceの作成

- F.4.1 REST Data Services配下での権限の作成

- F.4.2 ロールの作成

- F.5 OAuthクライアント・アプリケーションの登録

索引

例の一覧

- 3-1 PL/SQLファンクションの有効化

- 3-2 PL/SQLプロシージャの有効化

- 3-3 ストアド・プロシージャのためのエンドポイントの生成

- 3-4 パッケージ・プロシージャおよびファンクションのエンドポイント

- 3-5 ネストされたLineItemsがあるネストされたJSON発注書

- 3-6 POSTリクエストに対して使用されたPL/SQLハンドラ・コード

- 3-7 関係表上でOracle REST Data Servicesの問合せを使用してネストされたJSONオブジェクトを生成するGETハンドラ・コード

- 3-8 demoモジュールに新しいtest/:id テンプレートおよびGETハンドラを作成するためのORDS PL/SQL APIコール

- 3-9 Duser.timezone Java環境変数のスタンドアロン・モードでの設定

- 3-10 Duser.timezone Java環境変数のJavaアプリケーション・サーバーでの設定

- 4-1 NoSQLデータベースからのメタデータの取得

- 6-1 複数の権限を追加する例

図一覧

- 3-1 「RESTサービスの有効化」オプションの選択

- 3-2 PL/SQLパッケージ・オブジェクトの自動有効化

- 3-3 無名PL/SQLブロックをPUTメソッドのハンドラとして追加する

- 3-4 PUTメソッドに引き渡すバインド・パラメータl_salarychangeの設定

- 3-5 「詳細」タブからコールするURLを取得する

- 3-6 SQL問合せからの結果を表示してPUTメソッドの実行を確認する

- 3-7 いくつかのパラメータまたはバインド変数のルート・パターンを含むテンプレート定義の作成

- 3-8 SQL問合せのハンドラへの追加

- 3-9 ルート・パターンを使用してGETメソッドといくつかの必須パラメータ値を送信した結果をブラウザを使用して表示する

- 3-10 問合せ文字列を使用してGETメソッドとともにいくつかのパラメータ名/値ペアを送信した結果をブラウザを使用して表示する

- 3-11 ネストされたJSONオブジェクトの生成

- 4-1 標準的な環境の概要

- F-1 RESTでのEMP表のスキーマの有効化

- F-2 RESTでのEMP表の有効化

- F-3 RESTを有効化した表のテスト

- F-4 新規RESTfulサービス接続の情報の入力

- F-5 モジュールの指定ページでの情報の入力

- F-6 「テンプレートの指定」ページでの情報の入力

- F-7 「ハンドラの指定」ページでの情報の入力

- F-8 SQL Queryから作成したRESTful Serviceのテスト

- F-9 権限の編集ダイアログ・ボックス

- F-10 接続ナビゲータ配下の「RESTデータ・サービス」オプション

- F-11 モジュールの指定ページでの情報の入力

- F-12 「テンプレートの指定」ページでの情報の入力

- F-13 リソース・ハンドラの作成ページへの情報入力

- F-14 権限を作成するダイアログ・ボックス

- F-15 新規ロール名の入力

表一覧

- 3-1 バッチ・ロードのパラメータ

- B-1 Oracle REST Data Servicesの構成ファイルのパラメータ

はじめに

Oracle REST Data Servicesインストレーション、構成および開発ガイドでは、Oracle REST Data Servicesをインストールおよび構成する方法について説明します。(Oracle REST Data Servicesは、リリース2.0.6の前はOracle Application Express Listenerと呼ばれていました。)

注意:

リリース3.0では、本書のタイトルはOracle REST Data Servicesインストレーション、構成および開発ガイドです。タイトルに「開発」を追加したのは、以前は非公式の別文書であった『開発者ガイド』の内容が本書の「Oracle REST Data Servicesアプリケーションの開発」に含まれているという事実を反映したものです。

トピック:

- 対象読者

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

- 関連ドキュメント

- 表記規則

- サード・パーティ・ライセンス情報

対象読者

このドキュメントは、Oracle REST Data Servicesをインストールおよび構成しようとするシステム管理者またはアプリケーション開発者を対象としています。このガイドは、読者がWebテクノロジ、特にREST(Representational State Transfer)に精通していて、WindowsおよびUNIXプラットフォームについての一般的な知識を持っていることを前提としています。

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

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を参照してください。

関連ドキュメント

Oracle REST Data Servicesに関する詳細情報およびリソースは、次のOracle Technology Network(OTN)のサイトを参照してください。

http://www.oracle.com/technetwork/developer-tools/rest-data-services/

表記規則

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

規則

意味

太字

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

イタリック体

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

固定幅フォント

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

サード・パーティ・ライセンス情報

Oracle REST Data Servicesには、サード・パーティのコードが含まれています。オラクル社が表示を求められているライセンス文書については、『Oracle Databaseライセンス情報』を参照してください。

ただし、Oracleプログラム(サード・パーティのソフトウェアを含む)を使用する権利は、この製品に付随するOracleプログラムのライセンスによって決定され、次の文書に含まれる条件でこの権利が変更されることはありません。

1 Oracle REST Data Servicesのインストール

この項では、Oracle REST Data Servicesをインストールおよびデプロイする方法について説明します。(RESTはRepresentational State Transferの略です。)

注意:

Oracle REST Data Servicesは、リリース2.0.6の前はOracle Application Express Listenerと呼ばれていました。

トピック:

- Oracle REST Data Servicesについて

- インストール・プロセスの理解

- Oracle REST Data Servicesの構成およびインストール

- スタンドアロン・モードでの実行

- Oracle WebLogic Serverへのデプロイ

- GlassFish Serverへのデプロイ

- Apache Tomcatへのデプロイ

- Oracle REST Data Servicesのアップグレード

- Bequeath接続を使用したOracle REST Data Servicesのインストール、アップグレード、検証またはアンインストール

1.1 Oracle REST Data Servicesについて

Oracle REST Data Servicesは、Oracle HTTP Serverおよびmod_plsqlのかわりとなるJava EEベースのサービスです。Java EEの実装では、コマンドライン・ベースの設定、セキュリティの強化、ファイル・キャッシュおよびRESTful Webサービスなどの豊富な機能が提供されます。また、Oracle REST Data Servicesでは、Oracle WebLogic Server、GlassFish Server、Apache Tomcatおよびスタンドアロン・モードを使用したデプロイをサポートすることで、高い柔軟性が提供されます。

Oracle Application Expressアーキテクチャでは、WebブラウザとOracle Application Expressエンジンとの間でリクエストを代理するため、なんらかの形態のWebサーバーが必要です。Oracle REST Data Servicesは、この要件を満たしていますが、Oracle Application Express構成の範囲を超えて使用されています。Oracle REST Data Servicesでは、埋込のJDBCドライバを使用して接続が提供され、Oracleホームが必要ないため、デプロイ・プロセスが単純です。

1.2 インストール・プロセスの理解

この項では、Oracle REST Data Servicesの概要を説明し、サポートされるJavaプラットフォーム、Enterprise Edition(Java EE)アプリケーション・サーバー、およびシステム要件についての情報を提供します。

トピック:

- サポートされるJava EEアプリケーション・サーバー

- システム要件

1.2.1 サポートされるJava EEアプリケーション・サーバー

Oracle REST Data Servicesでは、次のJava EEアプリケーション・サーバーがサポートされます。

アプリケーション・サーバー

サポートされているリリース

Oracle WebLogic Server

11g リリース1 (10.3.6)以上

GlassFish Server

リリース3.1.2以上

4.0(ただし4.1は除く)では、CDI 1-1のグローバル・スイッチは、次のように注入チェックを無効にして使用する必要があります。

asadmin set configs.config.server-config.cdi-service.enable-implicit-cdi=false

しかし、このようなグローバル・スイッチの設定は、そのWebサーバー上のすべての後続のデプロイに影響を与え、他のデプロイの失敗につながる可能性があるため、4.0は使用しないことを強くお薦めします。

Apache Tomcat

リリース7.0.56以上

1.2.2 システム要件

Oracle REST Data Servicesのシステムの要件は次のとおりです。

- Oracle Database(Enterprise Edition、Standard EditionまたはStandard Edition One) リリース11.1以上、またはOracle Database 11g リリース2 Express Edition。

- Java JDK 1.7以上。

- Java Servlet Specification 2.3以上。

- Webブラウザの要件:

- Microsoft Internet Explorer 8.0以上。

- Mozilla Firefox 3.0以上。

- Google Chrome 2.0以上。

注意:

Oracle Application ExpressはOracle REST Data Servicesを使用するための前提条件ではありません。

Oracle Application Expressがインストールされ、インストール時にRESTfulサービスが構成されている場合(『Oracle Application Expressインストレーション・ガイド』のRESTfulサービスの構成の手順を参照)は、Oracle Applicationで定義されたRESTfulサービスの実行を含め、Oracle REST Data Servicesはそれをサポートします。

1.2.3 Oracle REST Data Servicesのインストールについて

Oracle REST Data Servicesをインストールするには、次の手順を実行します。

1. Oracle REST Data Servicesをダウンロード、インストールおよび構成します。

2. Oracle REST Data Servicesをデプロイします。デプロイ・オプションには次のものがあります。

- スタンドアロン・モード。

- Oracle WebLogic Server。

- GlassFish Server。

- Apache Tomcat。

関連トピック

- スタンドアロン・モードでの実行

- Oracle WebLogic Serverへのデプロイ

- GlassFish Serverへのデプロイ

- Apache Tomcatへのデプロイ

1.3 Oracle REST Data Servicesの構成およびインストール

Oracle REST Data Servicesをデプロイする前に、コマンドライン・インタフェースを使用してそれをインストールおよび構成する必要があります。

トピック:

- コマンドライン・インタフェースの使用について

- Oracle REST Data Servicesで使用されるデータベース・ユーザーについて

- Oracle REST Data Servicesによって付与される権限

- Oracle REST Data Servicesのダウンロード、構成およびインストール

- SQL Developerを使用したOracle REST Data Servicesの管理(オプション)

- 非HTTPS環境でOAuth2の使用

関連項目:

NoSQLデータベース・ストアとともにOracle REST Data Servicesを使用する場合は、「NoSQLおよびOracle REST Data Services」を参照してください。

JSONデータの永続にOracle REST APIを使用する場合は、Oracle REST APIもインストールする必要があります。詳細は、『Oracle REST Data Services SODA for REST開発者ガイド』のOracle REST APIのインストールに関する項を参照してください。

1.3.1 コマンドライン・インタフェースの使用について

Oracle REST Data Servicesでは、いくつかのコマンドライン・コマンドが提供されています。たとえば、Oracle REST Data Servicesの構成ファイルを保存する場所を構成でき、Oracle REST Data Servicesで使用するデータベースを構成でき、Oracle REST Data Servicesをスタンドアロン・モードで開始できます。

利用可能なコマンドの完全なリストを表示するには、ords.warファイルが保存されているディレクトリまたはフォルダに移動し、次のコマンドを実行します。

java -jar ords.war help

使用可能なコマンドのリストが表示されます。各コマンドの使用方法の説明を表示するには、次のように「help」に続けてコマンド名を入力します。

java -jar ords.war help configdir

1.3.2 Oracle REST Data Servicesで使用されるデータベース・ユーザーについて

Oracle REST Data Servicesでは、次のデータベース・ユーザーが使用されます。

ユーザー名

必須かどうか

説明

APEX_PUBLIC_USER

Oracle Application ExpressでOracle REST Data Servicesを使用している場合のみ

Oracle Application ExpressとともにOracle REST Data Servicesを使用する場合、すべてのOracle Application Express操作など、PL/SQLゲートウェイ操作の起動に使用されるデータベース・ユーザーです。

APEX_PUBLIC_USERのロック解除の詳細は、『Oracle Application Expressインストレーション・ガイド』のAPEX_PUBLIC_USERアカウントの構成の項を参照してください。

APEX_REST_PUBLIC_USER

Application Expressで定義されたRESTfulサービスを使用している場合のみ

Application Expressのワークスペースに定義されているRESTfulサービスにアクセスする場合に、Oracle Application ExpressのRESTfulサービスの呼出しに使用されるデータベース・ユーザーです。

APEX_LISTENER

Application Expressで定義されたRESTfulサービスを使用している場合のみ

Application Expressのワークスペースに定義されているRESTfulサービスにアクセスする場合に、Oracle Application Expressに格納されているRESTfulサービス定義の問合せに使用されるデータベース・ユーザーです。

ORDS_METADATA

はい

Oracle REST Data Servicesの多くの機能の実装に使用されるPL/SQLパッケージの所有者です。ORDS_METADATAには、Oracle REST Data Services対応のスキーマのメタデータが格納されます。

Oracle REST Data Servicesから直接このメタデータにアクセスすることはなく、Oracle REST Data ServicesアプリケーションはORDS_METADATAスキーマへの接続を作成することはありません。スキーマ・パスワードはランダムな文字列に設定され、接続権限は削除、パスワードの有効期限は期限切れです。

ORDS_PUBLIC_USER

はい

Oracle REST Data Services対応のスキーマでRESTfulサービスを呼び出すためのユーザーです。

APEX_<xxx>ユーザーは、Oracle Application Expressのインストール・プロセスの中で作成されます。

1.3.3 Oracle REST Data Servicesによって付与される権限

Oracle REST Data Servicesインストールの一部として、次のような権限が複数のユーザーに付与されます。

- PUBLICには、多くのORDS_METADATA表およびビューのSELECT権限が付与されます。

- PUBLICには、ユーザーの起動できるPL/SQLパッケージのEXECUTE権限が付与されます。

- ORDS_METADATAには、次のもののEXECUTE権限が付与されます。

- SYS.DBMS_ASSERT

- SYS.DBMS_CRYPTO

- SYS.DBMS_LOB

- SYS.DBMS_OUTPUT

- SYS.DBMS_REGISTRY

- SYS.DBMS_SESSION

- SYS.DBMS_UTILITY

- SYS.VALIDATE_ORDS

- SYS.HTF

- SYS.HTP

- SYS.OWA

- SYS.WPG_DOCLOAD

- ORDS_METADATAには、次のもののSELECT権限が付与されます。

- SYS.DBA_DIRECTORIES

- SYS.DBA_OBJECTS

- ORDS_METADATAには、次のシステム権限が付与されます。

- ALTER USER

- CREATE TRIGGER

- ORDS_METADATAには、Application ExpressのRESTデータをORDS_METADATA表に移行するために必要なオブジェクト権限が付与されます。

1.3.4 Oracle REST Data Servicesのダウンロード、構成およびインストール

このトピックの手順は、従来の(非CDB)データベースにOracle REST Data Servicesをインストール場合に適用されます。マルチテナント・データベース環境にOracle REST Data Servicesをインストールして使用するには、「Oracle REST Data Servicesでのマルチテナント・アーキテクチャの使用」の項を参照してください。

注意:

アプリケーション・サーバーにデプロイする前に、この項の構成手順を完了する必要があります。

Oracle REST Data Servicesをインストールおよび構成するには、次の手順を実行します。

1. Oracle REST Data Servicesのダウンロード・ページからords.version.number.zipファイルをダウンロードします。
ファイル名のversion.numberに現在のリリース番号が反映されることに注意してください。

2. ダウンロードしたZIPファイルを任意のディレクトリ(フォルダ)に解凍します。

- UNIXおよびLinuxの場合: ords.version.number.zipを解凍します。

- Windowsの場合: Windowsエクスプローラでords.version.number.zipファイルをダブルクリックします。

3. 次のインストール・オプションのいずれかを選択します。

- パラメータ・ファイルを使用した簡易インストール。

- コマンドライン・プロンプトを使用した拡張インストール

4. Oracle REST Data Servicesは、必要に応じて再インストールまたはアンインストールできます。

関連トピック

- Oracle REST Data Servicesでのマルチテナント・アーキテクチャの使用

- Oracle REST Data Servicesで使用されるデータベース・ユーザーについて

- Oracle REST Data Servicesを再インストールまたはアンインストール(削除)する場合

関連項目:

http://www.oracle.com/technetwork/developer-tools/rest-data-services/downloads/index.html

1.3.4.1 パラメータ・ファイルを使用した簡易インストール

Oracle REST Data Servicesをインストールした場所にある<path-to-params-file>/ords_params.propertiesファイルに指定されているパラメータを使用して、簡易インストールを実行できます。このファイルを事前に編集し、使用環境や好みを反映してデフォルト値を変更できます。ファイルにパラメータが欠落している場合は、その入力を求められます。

パラメータ・ファイルを使用して簡易インストールを実行するには:

1. オプションで、データベースのデフォルトの表領域および一時表領域を使用する場合は、ords_params.propertiesファイルで次の表領域関連エントリを削除できます。

schema.tablespace.default=SYSAUX
schema.tablespace.temp=TEMP
user.tablespace.default=USERS
user.tablespace.temp=TEMP

2. 環境や好みにあわせて、必要な値をデフォルト値にします。表領域関連の値を変更する場合、指定する表領域がデータベースにすでに存在することを確認します。
デフォルトのords_params.propertiesファイルには次のものが含まれます。

db.hostname=localhost
db.port=1521
db.servicename=
db.sid=
db.username=APEX_PUBLIC_USER
migrate.apex.rest=false
rest.services.apex.add=
rest.services.ords.add=true
schema.tablespace.default=SYSAUX
schema.tablespace.temp=TEMP
standalone.http.port=8080
standalone.mode=true
standalone.static.images=
user.tablespace.default=USERS
user.tablespace.temp=TEMP

注意:

Microsoft Windowsシステムでは、standalone.static.imagesのApplication Expressの静的イメージの場所を指定した場合、バックスラッシュ(エスケープ文字)をコロンの前に指定し、スラッシュをフォルダのセパレータとして使用します。例: standalone.static.images=d\:/test/apex426/apex/images/

3. 次のいずれかのコマンドを入力します。

java -jar ords.war
java -jar ords.war install simple

(簡易インストールはデフォルトであるため、install simpleは省略可能です。)

Oracle REST Data Servicesを初めてインストールするときに、PL/SQLゲートウェイ・データベースのユーザーおよびORDS_PUBLIC_USERユーザーのパスワードの入力を求められます。暗号化されたパスワードはパラメータ・ファイルに格納されます(たとえば、user.public.password=@0585904F6C9B442532D5212962835D00C8のように)。

後でパスワードを変更する場合は、パラメータ・ファイルから暗号化されたパスワードを削除する必要があります。セキュリティ上の理由から、パラメータ・ファイルでは読みやすい(非暗号化)パスワードは許可されていません。

1.3.4.2 コマンドライン・プロンプトを使用した拡張インストール

拡張インストールを実行でき、拡張インストールでは必要なパラメータ値の入力を求めるメッセージが表示され、選択したパラメータの値はOracle REST Data Servicesをインストールした場所にあるparams/ords_params.propertiesファイルに格納されます。

拡張インストールを実行するには、次のコマンドを入力します。

java -jar ords.war install advanced

インストール中、Oracle REST Data Servicesにより、指定された構成フォルダにすでに構成ファイルが存在するかどうかがチェックされます。

- 構成ファイルがフォルダに存在しない場合は、作成されます(例: defaults.xml、apex_pu.xml)。

- 以前のリリースの構成ファイルがフォルダに存在する場合は、Oracle REST Data Servicesによって<name>_pu.xmlが存在するかチェックされ、存在しない場合はORDS_PUBLIC_USERアカウントのパスワードの入力を求めるメッセージが表示されます。リリース 2.0.nの構成ファイル<name>_al.xmlおよび<name>_rt.xmlが存在する場合は保持されます。(ただし、2.0.nリリースではRESTfulサービスはオプションだったため、構成フォルダにファイルが存在しない可能性もあります。)

- 以前のリリースの複数の構成ファイルが存在し(例: apex.xml、apex_al.xml、apex_rt.xml、sales.xml、sales_al.xml、sales_rt.xmlなど)、<name>_pu.xmlが存在しない場合は、データベース内にORDSスキーマが作成できるように、データベース構成を選択するように求められます。

次に拡張インストールの例を示します。この例では、「スタンドアロン・モードで起動するには1を、終了するには2を入力してください」 [1]のプロンプトに対して、デフォルト値の1を受け入れると、残りのプロンプトが表示され、Oracle Application Expressを使用する場合はAPEXの静的リソースの場所を指定する必要があります。

d:\ords>java -jar ords.war install advanced
This Oracle REST Data Services instance has not yet been configured.
Please complete the following prompts
Enter the location to store configuration data:d:\path\to\config\
Enter the name of the database server [localhost]:
Enter the database listen port [1521]:
Enter 1 to specify the database service name, or 2 to specify the database SID [1]:2
Enter the database SID [xe]:
Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]:
Enter the database password for ORDS_PUBLIC_USER:
Confirm password:
Please login with SYSDBA privileges to verify Oracle REST Data Services schema. Installation may be required.
Enter the username with SYSDBA privileges to verify the installation [SYS]:
Enter the database password for SYS:
Confirm password:
Oracle REST Data Services schema does not exist and will be created.
Enter the default tablespace for ORDS_METADATA [SYSAUX]:
Enter the temporary tablespace for ORDS_METADATA [TEMP]:
Enter the default tablespace for ORDS_PUBLIC_USER [USERS]:
Enter the temporary tablespace for ORDS_PUBLIC_USER [TEMP]:
Enter 1 if you want to use PL/SQL Gateway or 2 to skip this step [1]:
Enter the PL/SQL Gateway database user name [APEX_PUBLIC_USER]:
Enter the database password for APEX_PUBLIC_USER:
Confirm password:
Enter 1 to specify passwords for Application Express RESTful Services database users (APEX_LISTENER, APEX_REST_PUBLIC_USER) or 2 to skip this step [1]:
Enter the database password for APEX_LISTENER:
Confirm password:
Enter the database password for APEX_REST_PUBLIC_USER:
Confirm password:
Enter 1 if you wish to start in standalone mode or 2 to exit [1]:
Enter the APEX static resources location:d:\apex426\apex\images\
Enter 1 if using HTTP or 2 if using HTTPS [1]:
Enter the HTTP port [8080]:
OR
Enter 1 if using HTTP or 2 if using HTTPS [1]:2
Enter the HTTPS port [8443]:
Enter the SSL hostname:
Enter 1 to use the self-signed certificate or 2 if you will provide the SSL certificate [1]:

1.3.4.3 Oracle REST Data Servicesインストールの検証

Oracle REST Data Servicesインストールが有効であることを確認する場合は、ords.warファイルのあるディレクトリまたはフォルダに移動し、validateコマンドを次の形式で入力します。

java -jar ords.war validate [--database <dbname>]

注意:

ORDSのインストール時には、Oracle Application Express (APEX)スキーマの検出が試行され、ビューが作成されます。このビューは、APEXスキーマ内の関連する表をORDSスキーマ内の表に結合したものです。APEXより前にORDSをインストールすると、ORDSはAPEXスキーマを検出できないため、存在しないAPEX表の位置にスタブ・ビューを作成します。

ORDSをAPEXの後にインストールすることで、APEXオブジェクト(ORDSが問い合わせる必要があるもの)が確実に存在するようにしておくことを強くお薦めします。ORDSをAPEXの前にインストールする場合は、validateコマンドを使用して、APEXスキーマに対する問合せをORDSが再作成するよう強制してください。

-databaseを指定する場合、<dbname>はOracle REST Data Services構成ファイルに格納されているプール名です。

ホスト、ポート、SIDまたはサービス名、およびSYSDBA権限を持つユーザー(SYS AS SYSDBAなど)の名前とパスワードなど、プール名の構成からは入手できない必要情報の指定を求められます。

注意:

validateコマンドをCDBに対して実行すると、CDBとそのすべてのPDBが検証されます。

1.3.4.4 Oracle REST Data Servicesを再インストールまたはアンインストール(削除)する場合

Oracle REST Data Servicesを再インストールする場合は、まず既存のOracle REST Data Servicesをアンインストールする必要があります。そして、アンインストールの前にはOracle REST Data Servicesが停止していることを確認します。

Oracle REST Data Servicesをアンインストールすると、ORDS_METADATAスキーマ、ORDS_PUBLIC_USERユーザー、およびOracle REST Data Services関連のデータベース・オブジェクト(パブリック・シノニムを含む)がデータベースに存在している場合は、削除されます。Oracle REST Data Servicesをアンインストール(削除)するには、ords.warファイルのあるディレクトリまたはフォルダに移動し、次のようなuninstallコマンドを入力します。

java -jar ords.war uninstall

uninstallにより、いくつかの必要な情報(ホスト、ポート、SIDまたはサービス名、ユーザー名、パスワード)を入力するよう求められます。

関連項目:

Oracle REST Data ServicesをCDBからアンインストールするには、「Oracle REST Data Servicesでのマルチテナント・アーキテクチャの使用」を参照してください。

1.3.5 SQL Developerを使用したOracle REST Data Servicesの管理(オプション)

この項では、Oracle SQL Developerを使用してOracle REST Data Servicesを管理する方法について説明します。

関連項目:

『Oracle SQL Developerユーザーズ・ガイド』のOracle REST Data Servicesの管理の項を参照してください。

トピック:

- SQL DeveloperのOracle REST Data Services管理について

- 管理者ユーザーの構成

1.3.5.1 SQL DeveloperのOracle REST Data Services管理について

Oracle SQL Developerでは、グラフィカル・ユーザー・インタフェースを使用してOracle REST Data Servicesを管理できます。これらの管理機能をフルに活用するには、SQL Developerのリリース4.1以上を使用する必要があります。Oracle REST Data Services管理のためのSQL Developerの使用はオプションです。

グラフィカル・ユーザー・インタフェースを使用して、データベース接続、JDBC設定、URLマッピング、RESTful接続、セキュリティ(許可されたプロシージャ、ブロックされたプロシージャ、検証ファンクションおよびウイルス・スキャン)、キャッシング、事前/事後処理プロシージャ、環境、およびExcel設定を更新できます。Oracle SQL Developerでは、統計レポート、エラー・レポートおよびログも提供されます。

関連項目:

『Oracle SQL Developerユーザーズ・ガイド』のOracle REST Data Servicesの管理の項を参照してください。

1.3.5.2 管理者ユーザーの構成

SQL Developerを使用してOracle REST Data Servicesを管理する場合は、次のように管理者ユーザーを構成する必要があります。

- 次のコマンドを実行します。

java -jar ords.war user adminlistener "Listener Administrator"

- adminlistenerユーザーのパスワードを入力します。

- adminlistenerユーザーのパスワードを確認します。

- HTTPSを使用せずにOracle REST Data Servicesを使用する場合は、「非HTTPS環境でのOAuth2の使用」の手順に従います。

Oracle REST Data Services構成の取得またはアップロード(あるいはその両方)にSQL Developerを使用する場合は、プロンプトが表示されたら、前述のリストの資格証明を入力します。

1.3.6 非HTTPS環境でOAuth2の使用

RESTfulサービスは、非公開データへのアクセスを制御するOAuth2プロトコルで保護できます。データのスヌーピングを防ぐため、OAuth2では、OAuth2認証プロセスに関与するすべてのリクエストをHTTPSを使用して転送する必要があります。Oracle REST Data Servicesのデフォルトの動作では、OAuth2関連のすべてのリクエストはHTTPSを使用して受信されたことを検証されます。HTTPを介して受信するリクエストへのサービスは拒否され、403 ForbiddenのHTTPステータス・コードが返されます。

このデフォルトの動作は、HTTPSを使用できない環境では次のようにして無効にできます。

1. Oracle REST Data Servicesの構成が保存されているフォルダを検索します。

2. defaults.xmlという名前のファイルを編集します。

3. このファイルの最後にある</properties>タグの直前に次の設定を追加します。

<entry key="security.verifySSL">false</entry>

4. ファイルを保存します。

5. 実行中なら、Oracle REST Data Servicesを再起動します。

この設定の使用は、開発またはテスト環境でのみ適切であることに注意してください。ユーザーの資格証明がクリア・テキストで渡されることになるので、本番環境でこの設定を使用するのは適切ではありません。

注意:

Oracle REST Data Servicesは、構成の変更を行った後に再起動する必要があります。アプリケーションを再起動する方法はアプリケーション・サーバーのマニュアルを参照してください。

1.4 スタンドアロン・モードでの実行

Oracle REST Data ServicesではJava EEアプリケーション・サーバーがサポートされていますが、スタンドアロン・モードで実行するオプションもあります。この項では、Oracle REST Data Servicesをスタンドアロン・モードで実行する方法について説明します。

スタンドアロン・モードは、開発での使用に適しており、本番デプロイでサポートされています。ただし、スタンドアロン・モードの管理機能は、大部分のJava EEアプリケーション・サーバーと比べて最小限であり、環境によっては、本番使用に十分でない場合があります。

トピック:

- スタンドアロン・モードでの起動

- スタンドアロン・モードのサーバーの停止

- 非Application Expressの静的リソースのドキュメント・ルートの構成

関連トピック

- サポートされるJava EEアプリケーション・サーバー

1.4.1 スタンドアロン・モードでの起動

スタンドアロン・モードでOracle REST Data Servicesを起動するには、次の手順を実行します。

1. スタンドアロン・モードで起動するには、次のコマンドを実行します。

java -jar ords.war

まだ構成が完了していない場合は、構成を行うことを求められます。

ヒント:

スタンドアロン・モードのオプションのヘルプを表示するには、次のコマンドを実行します。

java -jar ords.war help standalone

注意:

セキュアなアクセスを必要とするRESTfulサービスを使用する場合には、HTTPSを使用する必要があります。

2. プロンプトが表示されたら、Oracle REST Data Servicesが使用するOracle Application Expressの静的リソースを含むフォルダの場所を指定するか、場所を指定しない場合は[Enter]を押します。

3. プロンプトが表示されたら、Oracle REST Data Servicesによって自己署名証明書が自動生成されるようにするか、自分の証明書を指定するかを選択します。自分の証明書を使用する場合は、プロンプトが表示されたら、証明書およびDERエンコードされた関連の秘密鍵のパスを指定します。

秘密鍵をDERにまだ変換していない場合は、ここで値を入力する前に、「DERへの秘密鍵の変換(LinuxおよびUNIX)」を参照してください。

これらの値は、スタンドアロン・モードの初回起動時にのみ入力を求められます。

注意:

選択したポートで他のサーバーがリスニングしていないことを確認してください。デフォルトのポート8080は、通常、埋込みのPL/SQLゲートウェイを含むHTTPまたはアプリケーション・サーバーによって使用されます。デフォルトのセキュア・ポート8443は、通常、HTTPSによって使用されます。

関連トピック

- 非HTTPS環境でOAuth2の使用

- DERへの秘密鍵の変換(LinuxおよびUNIX)

1.4.1.1 DERへの秘密鍵の変換(LinuxおよびUNIX)

通常、秘密鍵および証明書署名リクエストを作成してから、署名証明書を取得します。秘密鍵は、Oracle REST Data Servicesで適切に読み取れるようにDERに変換する必要があります。

たとえば、OpenSSLツールを使用して次のいずれかのようなコマンドで、元の秘密鍵を作成したとします。

openssl req -new -newkey rsa:2048 -nodes -keyout yourdomain.key -out yourdomain.csr

または

openssl genrsa -out private.em 2048

この場合、次のようなコマンドを実行して秘密鍵を変換し、暗号化を解除する必要があります。openssl pkcs8 -topk8 -inform PEM -outform DER -in yourdomain.key -out yourdomain.der -nocrypt

openssl pkcs8 -topk8 -inform PEM -outform DER -in yourdomain.key -out yourdomain.der -nocrypt

そのようにすると、Oracle REST Data Servicesでプロンプトが表示されたときにyourdomain.derへのパスを含めることも、conf/ords/standalone/standalone.propertiesの次のエントリを変更することもできます。

ssl.cert=<path to yourdomain.crt>
ssl.cert.key=<path to yourdomain.der>
ssl.host=yourdomain

また、jetty.secure.portが必ず設定されます。

1.4.2 スタンドアロン・モードのサーバーの停止

スタンドアロン・モードのOracle REST Data Servicesサーバーを停止するには、コマンド・プロンプトで[Ctrl+C]を押します。

1.4.3 非Application Expressの静的リソースのドキュメント・ルートの構成

Application Expressの静的リソースで予約された/iフォルダ以外の静的リソースをデプロイするためにスタンドアロン・モードのドキュメント・ルートを構成できます。

構成するには、次の例に示すように、--doc-rootパラメータをスタンドアロン・モード・コマンドで指定します。

java -jar ords.war standalone --doc-root /var/www/html

前述の例では、http://server:port/の下の/var/www/htmlにあるすべてのリソースを使用できるようにします。たとえば、ファイル/var/www/html/hello.txtが存在する場合、http://server:port/hello.txtでアクセス可能です。

--doc-rootに指定された値は、standalone.doc.rootプロパティの${config.dir}/ords/standalone/standalone.propertiesに格納されます。カスタム・ドキュメント・ルートが--doc-rootを使用して指定されていない場合、${config.dir}/ords/standalone/doc_rootのデフォルトのdoc-root値が使用されます。このフォルダに格納されているすべてのフォルダはルート・コンテキストで使用できます。

このアプローチには、次の機能および考慮事項があります。

- HTMLリソースはファイル拡張子なしでアドレス可能です。たとえば、hello.htmlという名前のファイルがドキュメント・ルートに存在する場合、URI http://server:port/helloでアクセスできます。

- ファイル拡張子ありでHTMLリソースにアドレスしようとすると、ファイル拡張子なしの場所にリダイレクトされます。たとえば、URI http://server:port/hello.htmlにアクセスしようとすると、クライアントはhttp://server:port/helloにリダイレクトされます。
通常のプラクティスはHTMLリソースにファイル拡張子なしで使用することであるため、この機能はそのプラクティスを手助けし、さらにリダイレクトはファイル拡張子ありでアドレスされたリソースを扱います。

- フォルダの索引ページがサポートされます。フォルダにindex.htmlまたはindex.htmという名前のファイルがある場合、そのファイルはフォルダの索引ページとして使用されます。たとえば、/var/www/htmlに/abc/xyz/index.htmlがある場合、http://server:port/abc/xyz/にアクセスすると、index.htmlの内容が表示されます。

- 末尾にスラッシュなしでフォルダをアドレス入力すると、末尾にスラッシュありのURIにリダイレクトされます。たとえば、クライアントがhttp://server:port/abc/xyzにアクセスした場合、サーバーはhttp://server:port/abc/xyz/へのリダイレクトを発行します。

- リソースは、ファイルの修正スタンプに基づき弱いetagと、リソースを1時間キャッシュするキャッシュ制御ヘッダー付きで生成されます。

1.5 Oracle WebLogic Serverへのデプロイ

この項では、Oracle WebLogic ServerにOracle REST Data Servicesをデプロイする方法について説明します。Oracle WebLogic Serverのインストール・プロセスを完了し、Oracle WebLogic Serverに精通した読者を前提としています。ドメイン、管理対象サーバー、デプロイ、セキュリティ、ユーザーおよびロールに不慣れな場合は、Oracle WebLogic Serverのドキュメントを参照してください。

トピック:

- Oracle WebLogic Serverについて

- Oracle REST Data Servicesのダウンロード、インストールおよび構成

- Oracle Application Expressイメージの構成

- 管理サーバー・コンソールの起動

- Oracle WebLogic Serverデプロイのインストール

- HTTPのBasicチャレンジを正しく処理するためのWebLogicの構成

- ordsおよびiの状態と健全性の検証

1.5.1 Oracle WebLogic Serverについて

Oracle WebLogic ServerはOracle Technology Networkからダウンロードできます。

Oracle WebLogic Serverのインストールの詳細は、『Oracle Fusion Middleware Oracle WebLogic Serverインストレーション・スタート・ガイド』および『Oracle Fusion Middleware Oracle WebLogic Serverインストレーション・ガイド』を参照してください。

関連項目:
http://www.oracle.com/technetwork/middleware/weblogic/downloads/index.html

1.5.2 Oracle REST Data Servicesのダウンロード、インストールおよび構成

Oracle REST Data ServicesをWebLogicにデプロイする前に、この手順を完了する必要があります。

関連トピック

- Oracle REST Data Servicesの構成およびインストール

1.5.3 Oracle Application Expressイメージの構成

Oracle Application Expressを使用している場合、Oracle Application Expressを参照するためにWebアーカイブ(イメージ・ファイル)を作成する必要があります。ただし、Oracle Application Expressを使用していない場合、Oracle Application Expressイメージを構成することに関するこの項の以降の手順をスキップできます。

作業を開始する前に、Oracle Application Expressのイメージ・ファイルを参照するWebアーカイブ(WAR)ファイルを作成する必要があります。i.warという名前のWebアーカイブ・ファイルを作成するには、次のようにstaticコマンドを使用します。

java -jar ords.war static <apex directory>\images

説明:

- <apex directory>は、Oracle Application Expressディレクトリの場所です。

このコマンドにより、ords.warファイルに含まれるstaticコマンドが実行されます。これにより、Application Expressの静的イメージがi.warという名前のアーカイブ・ファイルにパッケージ化されます。

作成されるイメージのWARには静的リソースは含まれず、そのかわりに静的リソースが保存されている場所が参照されます。このため、WARがデプロイされるサーバー上の指定したパスで静的リソースが利用可能である必要があります。

ヒント:

staticコマンドのすべてのオプションを確認するには、java -jar ords.war help staticを使用します。

i.warファイルは、次の手順でWebLogicへのデプロイに使用します。

1. 管理サーバー・コンソールの起動

2. Oracle WebLogic Serverデプロイのインストール

3. HTTPのBasicチャレンジを正しく処理するためのWebLogicの構成

1.5.4 管理サーバー・コンソールの起動

管理サーバー・コンソールを起動するには、次の手順を実行します。

1. 管理サーバーを起動します。

2. Webブラウザに次のURLを入力して、WebLogic管理コンソールを起動します。

http://<host>:<port>/console

説明:

- <host>は、管理サーバーのDNS名またはIPアドレスです。

- <port>は、管理サーバーでリクエストをリスニング中のポートです(デフォルトでは7001ポート)。

3. WebLogic管理者のユーザー名およびパスワードを入力します。

4. ドメインが本番モードの場合、「チェンジ・センター」サブメニューの下の左ペインの「ロックして編集」ボタンをクリックします。ドメインが開発モードの場合は、このボタンは表示されません。

1.5.5 Oracle WebLogic Serverデプロイのインストール

ヒント:

この作業を開始する前に、Oracle REST Data Servicesのファイルであるords.warおよびi.warが使用可能になっている必要があります。

デプロイをインストールするには、次の手順を実行します。

1. WebLogic Serverのホームページに移動します。「ドメイン構成」の下で、「デプロイメント」を選択します。
「デプロイメントの概要」が表示されます。

2. 「インストール」をクリックします。

3. ords.warファイルの場所を指定し、「次」をクリックします。
ords.warファイルは、Oracle REST Data ServicesのZIPファイルを解凍したフォルダにあります。

ヒント:

WebLogic Serverは、WARアーカイブのファイル名からコンテキスト・ルートを決定します。下位互換を維持する必要がある場合は、URLがhttp://server/ords/...ではなくhttp://server/apex/...という形式になるように、デプロイ前にords.warという名前をapex.warに変更する必要があります。

アプリケーション・インストール・アシスタントが表示されます。

4. 「このデプロイメントをアプリケーションとしてインストールする」を選択して「次へ」をクリックします。

5. アプリケーションまたはモジュールのデプロイ先とするサーバーまたはクラスタを選択して、「次」をクリックします。

ヒント:

追加の管理対象サーバーまたはクラスタを作成していない場合、このアシスタント・ページは表示されません。

6. 「オプション設定」では、次のように指定します。

a. 名前 - 次を入力します。

ords

b. セキュリティ - 次を選択します。
カスタム・ロール: 管理コンソール内に定義されたロールを使用します。デプロイメント記述子内に定義されたポリシーを使用します。

c. ソースのアクセス可能性 - 次を選択します。
デプロイメントのターゲットに定義されるデフォルトを使用

7. 「次へ」をクリックします。
概要ページが表示されます。

8. 「追加構成」の下で、次のいずれかを選択します。

- はい、デプロイメントの構成画面に移動します。 - 構成ページが表示されます。

- いいえ、後で構成を確認します。 - 「デプロイメントのサマリー」ページに戻ります。

9. 指定した構成設定の概要を確認します。

10. 「終了」をクリックします。

11. 前述の手順を繰り返してi.warファイルをデプロイします。
オプション設定では、次のように指定します。

a. 名前 - 次を入力します。

i

b. セキュリティ - 次を選択します。
カスタム・ロール: 管理コンソール内に定義されたロールを使用します。デプロイメント記述子内に定義されたポリシーを使用します。

c. ソースのアクセス可能性 - 次を選択します。
デプロイメントのターゲットに定義されるデフォルトを使用

12. ドメインが本番モードの場合、「チェンジ・センター」で「変更のアクティブ化」をクリックします。

関連トピック

- Oracle REST Data Servicesの構成およびインストール

- Oracle Application Expressイメージの構成

1.5.6 HTTPのBasicチャレンジを正しく処理するためのWebLogicの構成

デフォルトでは、WebLogic Serverにより、すべてのHTTP Basic認証のチャレンジのインターセプトが試行されます。Oracle REST Data Servicesを正常に機能させるには、このデフォルトの動作を無効にする必要があります。そのためには、enforce-valid-basic-auth-credentialsフラグを更新します。WebLogic Server管理コンソールでは、enforce-valid-basic-auth-credentials設定は表示されません。WebLogic Scripting Tool (WLST)コマンド使用して、実行中のサーバーの値を確認および編集できます。

次のWLSTコマンドによりドメイン設定が表示されます。

connect('weblogic','weblogic','t3://localhost:7001')
cd('SecurityConfiguration')
cd('mydomain')
ls()

ドメイン設定が表示されたら、次のエントリを含めます。

-r--   EnforceValidBasicAuthCredentials             true

次に、このエントリをfalseに設定する必要があります。

エントリをfalseに設定するには、次のようにWLSTコマンドを使用します。

connect('weblogic', 'weblogic', 't3://localhost:7001')
edit()
startEdit()
cd('SecurityConfiguration')
cd('mydomain')
set('EnforceValidBasicAuthCredentials','false')
save()
activate()
disconnect()
exit()

注意:
新しい設定を有効にするには、WebLogic Serverを再起動する必要があります。

前述の例は、次のとおりです。

- weblogicは管理権限を持つWebLogicユーザーです

- weblogicはパスワードです

- mydomainはドメインです

- AdminServerはローカルホストおよびポート7001上で実行されています

関連トピック

- WebLogic Serverコマンド・リファレンス

1.5.7 ordsおよびiの状態と健全性の検証

「デプロイメントのサマリー」で、「制御」タブを選択し、ordsおよびiの両方の「状態」が「アクティブ」および「ヘルス」状態でOKであることを確認します。

ordsまたはi、あるいはその両方が「アクティブ」でない場合は、有効にします。「デプロイメント」表で、ordsまたはi(あるいはその両方)の隣にあるチェック・ボックスを選択します。「開始」をクリックし、「すべてのリクエストを処理」を選択してそれらをアクティブにします。

1.6 GlassFish Serverへのデプロイ

この項では、GlassFish ServerにOracle REST Data Servicesをデプロイする方法について説明します。

トピック:

- GlassFish Serverについて

- Oracle REST Data Servicesのダウンロード、インストールおよび構成

- Oracle Application Expressイメージの構成

- 管理サーバー・コンソールの起動

- GlassFish Serverデプロイのインストール

ヒント:

この項は、GlassFish Serverのインストール・プロセスを完了し、GlassFish Serverに精通した読者を前提としています。ドメイン、サーバー、アプリケーション、セキュリティ、ユーザーおよびロールに不慣れな場合は、GlassFish Serverのドキュメントを参照してください。

1.6.1 GlassFish Serverについて

GlassFish ServerにOracle REST Data Servicesをインストールできます。GlassFish ServerはOracle Technology Networkからダウンロードできます。

関連トピック

- Oracle REST Data Servicesのダウンロード、インストールおよび構成

関連項目:

http://www.oracle.com/us/products/middleware/application-server/oracle-glassfish-server/index.html

1.6.2 Oracle REST Data Servicesのダウンロード、インストールおよび構成

Oracle REST Data ServicesをGlassFishにデプロイする前に、この手順を完了する必要があります。

1.6.3 Oracle Application Expressイメージの構成

Oracle Application Expressを使用している場合、Oracle Application Expressを参照するためにWebアーカイブ(イメージ・ファイル)を作成する必要があります。ただし、Oracle Application Expressを使用していない場合、Oracle Application Expressイメージを構成することに関するこの項の以降の手順をスキップできます。

作業を開始する前に、Oracle Application Expressのイメージ・ファイルを参照するWebアーカイブ(WAR)ファイルを作成する必要があります。i.warという名前のWebアーカイブ・ファイルを作成するには、次のようにstaticコマンドを使用します。

java -jar ords.war static <apex directory>\images

説明:

- <apex directory>は、Oracle Application Expressディレクトリの場所です。

作成されるイメージのWARには静的リソースは含まれず、そのかわりに静的リソースが保存されている場所が参照されます。このため、WARがデプロイされるサーバー上の指定したパスで静的リソースが利用可能である必要があります。

ヒント:

staticコマンドのすべてのオプションを確認するには、java -jar ords.war help staticを使用します。

i.warファイルは、次の手順でGlassFishへのデプロイに使用します。

1. 管理サーバー・コンソールの起動

2. GlassFish Serverデプロイのインストール

1.6.4 管理サーバー・コンソールの起動

管理コンソールを起動する前に、少なくとも1つのGlassFishのサーバー・ドメインが起動している必要があります。

管理コンソールを起動するには、次の手順を実行します。

1. Webブラウザに次のURLを入力して、管理コンソールを起動します。

http://localhost:4848

2. プロンプトが表示される場合は、管理コンソールにログインします。

ヒント:

GlassFish Serverをインストールしたときに、管理者パスワードを要求することを選択した場合、ログインするように求められます。

1.6.5 GlassFish Serverデプロイのインストール

ヒント:

この作業を開始する前に、Oracle REST Data Servicesのファイルであるords.warおよびi.warが使用可能になっている必要があります。

デプロイをインストールするには、次の手順を実行します。

1. ナビゲーション・ツリーで、「アプリケーション」ノードをクリックします。
「アプリケーション」ページが表示されます。

2. 「デプロイ」ボタンをクリックします。
「アプリケーションおよびモジュールのデプロイ」ページが表示されます。

3. サーバーにアップロードするパッケージ・ファイルを選択し、「参照」をクリックします。

4. ords.warファイルの場所に移動し、ファイルを選択して「開く」をクリックします。
「アプリケーションおよびモジュールのデプロイ」ページが表示されます。

5. 「アプリケーションおよびモジュールのデプロイ」ページで、次を選択します。

a. タイプ: Webアプリケーション

b. コンテキスト・ルート: ords

ヒント:

コンテキスト・ルートの値のデフォルトはordsです。しかし、下位互換を維持する必要がある場合は、apexに変更でき、URLはhttp://server/ords/...ではなくhttp://server/apex/...という形式になります。

c. アプリケーション名: ords

d. ステータス: 有効

e. 説明: Oracle REST Data Services

f. その他のデフォルト設定をすべて受入れ、「OK」をクリックします。

6. 前述の手順を繰り返してi.warファイルをデプロイします。コンテキスト・ルートとしてsun-web.xml内の設定が使用されるように「コンテキスト・ルート」フィールドをクリアします。

「アプリケーション」ページが表示されます。ordsの「有効」フォールドにチェック・マークが表示されるはずです。

ヒント:

ordsの「有効」列にチェックマークが表示されない場合は、ordsの隣にあるチェック・ボックスを選択して「有効化」をクリックします。

関連トピック

- Oracle REST Data Servicesの構成およびインストール

- Oracle Application Expressイメージの構成

1.7 Apache Tomcatへのデプロイ

この項では、Apache TomcatにOracle REST Data Servicesをデプロイする方法について説明します。

トピック:

- Apache Tomcatについて

- Oracle REST Data Servicesのダウンロード、インストールおよび構成

- Oracle Application Expressイメージの構成

- Apache Tomcatデプロイのインストール

1.7.1 Apache Tomcatについて

ヒント:

この項は、Apache Tomcatのインストール・プロセスを完了し、Apache Tomcatに精通した読者を前提としています。ドメイン、サーバー、アプリケーション、セキュリティ、ユーザーおよびロールに不慣れな場合は、Apache Tomcatのドキュメントを参照してください。

Apache Tomcatは次のURLからダウンロードできます。

関連項目:

http://tomcat.apache.org/download-70.cgi

1.7.2 Oracle REST Data Servicesのダウンロード、インストールおよび構成

Oracle REST Data ServicesをApache Tomcatにデプロイする前に、この手順を完了する必要があります。

関連トピック

- Oracle REST Data Servicesの構成およびインストール

1.7.3 Oracle Application Expressイメージの構成

Oracle Application Expressを使用している場合、Oracle Application Expressを参照するためにWebアーカイブ(イメージ・ファイル)を作成する必要があります。ただし、Oracle Application Expressを使用していない場合、Oracle Application Expressイメージを構成することに関するこの項の以降の手順をスキップできます。

Apache Tomcat上でOracle Application Expressイメージを構成するには、次のようにします。

- <apex directory>/imagesフォルダのコンテンツを<Tomcat directory>/webapps/i/にコピーします。
説明:

- <apex directory>は、Oracle Application Expressディストリビューションのディレクトリの場所です。

- <Tomcat directory>は、Apache Tomcatがインストールされているフォルダです。

1.7.4 Apache Tomcatデプロイのインストール

ヒント:

この作業を開始する前に、Oracle REST Data Servicesのファイルであるords.warが使用可能になっている必要があります。

Apache Tomcatデプロイをインストールするには、次の手順を実行します。

1. ords.warファイルをApache Tomcatがインストールされているwebappsフォルダに移動します。

ヒント:

Apache Tomcatは、WARアーカイブのファイル名からコンテキスト・ルートを決定します。下位互換を維持する必要がある場合は、URLがhttp://server/ords/...ではなくhttp://server/apex/...という形式になるように、webappsフォルダに移動する前に、ords.warという名前をapex.warに変更する必要があります。

2. Webブラウザに次のURLを入力して、Oracle Application Expressにアクセスします。

http://<hostname>:<port>/ords/

説明:

- <hostname>は、Apache Tomcatが実行されているサーバーの名前です。

- <port>は、Apache Tomcatアプリケーション・サーバー用に構成されたポート番号です。

関連トピック

- Oracle REST Data Servicesの構成およびインストール

- Oracle Application Expressイメージの構成

1.8 Oracle REST Data Servicesのアップグレード

新しいリリースのOracle REST Data Servicesにアップグレードする場合は、次のようにする必要があります。

1. Oracle REST Data Servicesインスタンスを停止します。

- アプリケーション・サーバー(Oracle WebLogic Server、GlassFish ServerまたはApache Tomcatなど)上でOracle REST Data Servicesを実行している場合は、Oracle REST Data Servicesを停止します。

- Oracle REST Data Servicesをスタンドアロン・モードで実行している場合は、「スタンドアロン・モードのサーバーの停止」を参照してください。

2. 新しいOracle REST Data Servicesリリース・ディストリビューションを解凍したフォルダに移動します。

3. コマンドラインに次のコマンドを入力します。

java -jar ords.war install advanced

または

java -jar ords.war

4. 構成フォルダの入力を求められたら、Oracle REST Data Servicesの構成ファイルが格納されている構成フォルダを使用します。(構成場所は、ords.warファイルに収録されます。)

- 構成ファイルが格納されている既存のOracle REST Data Servicesの構成フォルダを指定すると、Oracle REST Data Servicesでは、構成フォルダ内に定義されている各データベースに接続して、インストール済バージョンをチェックしようとします。

- 存在しないOracle REST Data Servicesの構成フォルダを指定すると、データベース接続情報、ORDS_PUBLIC_USER資格証明およびその他の構成情報の入力を求められます。Oracle REST Data Servicesでは、そのデータベースに接続してインストール済バージョンをチェックしようとします。

Oracle REST Data Servicesによるインストール済バージョンのチェックでは、データベースにすでにインストールされているバージョンが3.0.nより前かどうかに応じて、次のように処理が行われます。

- インストール済バージョンが3.0.nより前のバージョンのOracle REST Data Servicesである場合は、Oracle REST Data Servicesでインプレース・アップグレードを適用できるようにSYS資格証明の入力を求められます。インプレース・アップグレードでは、既存のインストールが変更され、更新されたスキーマ・オブジェクトおよびパッケージが追加されます。ORDSスキーマに格納されている既存のメタデータは元の状態のままです。

- Oracle REST Data Servicesがデータベースにまだインストールされていない場合(またはリリース2.0.nからアップグレードしている場合)は、Oracle REST Data Servicesでインストールを実行できるようにSYS資格証明の入力だけでなく、ORDS_METADATAスキーマのデフォルトの表領域および一時表領域とORDS_PUBLIC_USERの入力も求められます。

アップグレードまたはインストールが完了すると、ords.warファイルをアプリケーション・サーバーに再度デプロイすることも、スタンドアロン・モードでOracle REST Data Servicesを起動することもできます。

関連トピック

- Oracle REST Data Servicesのトラブルシューティング

- スタンドアロン・モードのサーバーの停止

1.9 Bequeath接続を使用したOracle REST Data Servicesのインストール、アップグレード、検証またはアンインストール

Bequeath接続を使用して、Oracle REST Data Servicesのインストール、アップグレード、検証またはアンインストールを実行できます。インストーラからは、操作のSYSユーザー名とパスワードの入力を求められません。

パラメータ・ファイルに次のプロパティを追加します: bequeath.connect=true

Oracle REST Data Servicesのインストール、検証またはアンインストールへのBequeath接続の使用は、Oracle Databaseリリース12の場合はLinuxおよびWindowsシステムでサポートされていますが、Oracle Databaseリリース11の場合はLinuxシステムでのみサポートされています。

使用するコマンドは、DBAグループのメンバーであるオペレーティング・システム・ユーザーが実行する必要があります。Oracle REST Data Servicesのインストールの例を次に示します。

java -jar ords.war

Linuxを使用したBequeath接続

Linuxシステムでは、Bequeath接続を使用するように次の環境変数を設定する必要があります。

- ORACLE_HOME

- ORACLE_SID

- LD_LIBRARY_PATH (ORACLE_HOME/libを指すため)

Oracle Databaseリリース11 (リリース12ではなく)の場合、オプション-DuseOracleHome=trueを指定する必要があります。LinuxシステムでのOracle REST Data Servicesのインストールの例を次に示します。

- Oracle Databaseリリース11の場合: java -DuseOracleHome=true -jar ords.war

- Oracle Databaseリリース12の場合: java -jar ords.war

関連トピック

- パラメータ・ファイルを使用した簡易インストール

2 Oracle REST Data Servicesの構成(詳細)

この項では、リクエストをルーティングして複数のデータベースに接続するようにOracle REST Data Servicesを構成する方法を説明し、その他の構成情報については、その他のドキュメント・ソースを参照します。

注意:

Oracle REST Data Servicesは、構成の変更を行った後に再起動する必要があります。アプリケーションを再起動する方法はアプリケーション・サーバーのマニュアルを参照してください。

トピック:

- 複数データベースの構成

- RAC Fast Connection Failoverのサポート

- セキュリティ、キャッシュ、前処理と後処理、環境、およびExcel設定の構成

- Oracle REST Data Servicesで使用するRESTfulサービスの開発

2.1 複数データベースの構成

Oracle REST Data Servicesでは、複数のデータベースに接続する機能がサポートされています。この項では、リクエストを適切なデータベースにルーティングするための異なる戦略を説明します。

トピック:

- リクエストURLについて

- 追加のデータベースの構成

- リクエスト・パスの接頭辞に基づくルーティング

- リクエストURLの接頭辞に基づくルーティング

2.1.1 リクエストURLについて

Oracle REST Data Servicesは、リクエストを適切なデータベースにルーティングするための多数の異なる戦略をサポートしています。これらの戦略はすべて、リクエストURLを調べ、URLのどこかの一致に基づいてデータベースを選択することを利用しています。それは、リクエストURLの関連する部分をまとめるのに役立ちます。次のURLについて考えます。

https://www.example.com/ords/sales/f?p=1:1

このURLは、次のセクションで構成されています。

- プロトコル: https

- ホスト名: www.example.com

- コンテキスト・ルート: /ords
コンテキスト・ルートは、アプリケーション・サーバー上のOracle REST Data Servicesがデプロイされている場所です。

- リクエスト・パス: /sales/f?p=1.1
これは、リクエストURLのコンテキスト・ルートからの相対となる部分です。

異なるアプリケーションに対しては、リクエスト・パス内の特定の接頭辞またはリクエストURL全体の特定の接頭辞に基づいてリクエストをルーティングすることが重要です。

複数データベースを構成するには、次の2つの手順を行います。

1. データベース接続情報の構成

2. どのリクエストをどのデータベースにルーティングするかの構成

2.1.2 追加のデータベースの構成

最初にOracle REST Data Servicesを構成するとき、apexという名前のデフォルトのデータベース接続を構成します。setupコマンドを使用して追加のデータベース接続を作成できます。

ヒント:

setupコマンドの完全なヘルプを表示するには、次のように入力します。

java -jar ords.war help setup

データベース接続を作成するには、次のように入力します。

java -jar ords.war setup --database <database name>

説明:

- <database name>データベース接続に付ける名前です。

データベースを構成するために必要な情報を入力するように求められます。追加のデータベースを設定したあと、リクエストが適切なデータベースまでルーティングされる方法のルールを定義します。

関連トピック

- Oracle REST Data Servicesの構成およびインストール

- リクエスト・パスの接頭辞に基づくルーティング

- リクエストURLの接頭辞に基づくルーティング

2.1.3 リクエスト・パスの接頭辞に基づくルーティング

map-urlコマンドを使用してリクエストのルーティング・ルールを作成します。

ヒント:

map-urlコマンドの完全なヘルプを表示するには、次のように入力します。

java -jar ords.war help map-url

URLのリクエスト・パスの一部の接頭辞の一致に基づいてリクエストをルーティングする場合は、map-urlコマンドを次のように使用します。

java -jar ords.war map-url --type base-path --workspace-id <workspace name> <path prefix> <database name>

説明:

- <workspace name>この接続用のRESTfulサービスが定義されているOracle Application Expressワークスペースの名前です。RESTfulサービスを使用していない場合は省略できます。

- <path prefix>は、必ずリクエスト・パスの先頭にある接頭辞です。

- <database name>は、前の手順で設定したデータベース接続の名前です。

関連トピック

- 追加のデータベースの構成

2.1.3.1 リクエスト・パスの接頭辞に基づくルーティングの例

Oracle REST Data Servicesがexample.comという名前のシステムに/ordsというコンテキスト・パスでデプロイされているとすると、次のルールを作成します。

java -jar ords.war map-url --type base-path --workspace-id sales_rest /sales sales_db

このルールは、https://example.com/ords/sales/...に一致するすべてのリクエストがsales_dbというデータベース接続にルーティングされることを意味します。sales_dbデータベースに定義されているsales_restワークスペースで、RESTfulサービスの定義が検索されます。

前述のルールは、次のすべてのリクエストと一致します。

https://example.com/ords/sales/f?p=1:1
https://example.com/ords/sales/leads/
https://www.example.com/ords/sales/forecasting.report?month=jan  (If www.example.com resolves to the same system as example.com.)

前述のルールは、次のリクエストのいずれにも一致しません。

http://example.com/ords/sales/f?p=1:1  (The protocol is wrong.)
https://example.com:8080/ords/sales/f?p=1:1  (The port is wrong: 443 is default for https, but don't specify if using default.)
https://example.com/ords/f?p=1:1  (Missing the /sales prefix.)
https://example.com/pls/sales/leads/  (The context path is wrong.)

2.1.4 リクエストURLの接頭辞に基づくルーティング

リクエストURLの接頭辞の一致に基づいてリクエストをルーティングする場合は、map-urlコマンドを次のように使用します。

java -jar ords.war map-url --type base-url --workspace-id <workspace name> <url prefix> <database name>

説明:

- <workspace name>この接続用のRESTfulサービスが定義されているOracle Application Expressワークスペースの名前です。RESTfulサービスを使用していない場合は省略できます。

- <url prefix>は、リクエストURLの先頭に必要な接頭辞です。

- <database name>は、データベース接続の名前です。

2.1.4.1 リクエストURLの接頭辞に基づくルーティングの例

Oracle REST Data Servicesがexample.comという名前のシステムに/ordsというコンテキスト・パスでデプロイされているとすると、次のルールを作成します。

java -jar ords.war map-url --type base-url --workspace-id sales_rest https://example.com/ords/sales sales_db

このルールは、https://example.com/ords/sales/...に一致するすべてのリクエストがsales_dbというデータベース接続にルーティングされることを意味します。sales_dbデータベースに定義されているsales_restワークスペースで、RESTfulサービスの定義が検索されます。

前述のルールは、次のすべてのリクエストと一致します。

https://example.com/ords/sales/f?p=1:1
https://example.com/ords/sales/leads/
https://example.com/ords/sales/forecasting.report?month=jan

前述のルールは、次のリクエストのいずれにも一致しません。

http://example.com/ords/sales/f?p=1:1  (The protocol is wrong.)
https://example.com:8080/ords/sales/f?p=1:1  (The port is wrong: 443 is default for https, but don't specify if using default.)
https://example.com/ords/f?p=1:1  (Missing the /sales segment of the base URL.)
https://example.com/pls/sales/leads/  (The context path is wrong.)
https://www.example.com/ords/sales/forecasting.report?month=jan  (The host name is wrong.)

2.2 RAC Fast Connection Failoverのサポート

Oracle REST Data Service (ORDS)は、Oracle Real Application Clusters (Oracle RAC)のFast Connection Failover (FCF)機能をサポートします。

Oracle REST Data Serviceは、WebLogic、Tomcat、GlassFishなど、サポートするすべてのApplication Server環境でUniversal Connection Pool (UCP)とともに実行されます。また、UCPはFast Connection Failoverをサポートします。FCFを有効化するには、Oracle Notification Service (ONS)が有効化されている必要があります。ONSを有効化するには、次のコード・スニペットに示すように、Oracle REST Data Services defaults.xml構成ファイルにあるプロパティのリストにエントリを追加します。

<entry key="jdbc.enableONS">true</entry>
<entry key= "jdbc.ONSConfig">nodes=racnode1:4200,racnode2:4200\nwalletfile=/oracle11/onswalletfile</entry>

ONSは、Fast Application Notification (FAN)イベントを送信するために使用されるメッセージング機能です。ONSが有効の場合、ORDSがFCFを自動的に有効化します。フェイル・オーバーや、ロード・バランシングなどのその他の高度なFCF機能など、特定のFCF機能を有効化するには、次のコード・スニペットに示すようにカスタム接続に対応するエントリを構成ファイルに追加する必要があります。

<entry key="db.connectionType">customurl</entry>
<entry key="db.customURL">jdbc:oracle:thin:@(DESCRIPTION=(FAILOVER=ON)(ADDRESS_LIST=
(LOAD_BALANCE=ON)(ADDRESS=(PROTOCOL=TCP)(HOST=prod_scan.example.com)(PORT=1521)))
(CONNECT_DATA=(SERVICE_NAME=ISPRD)))|</entry>

defaults.xml構成ファイルを更新した後、ORDSを再起動するまで変更は有効になりません。

UCPはFast Connection Failoverをサポートします。FCFは、FANイベントをリッスンし、それに応答することで次の2つのシナリオに対応します。

- 計画外停止 : RACはインスタンス障害を検出するとFAN Downイベントを生成し、それをFCFが捕捉します。 FCFは失敗したインスタンスへのすべての接続を終了し、それ以降のすべてのリクエストを、残っているRACインスタンスに送ります。

- 計画停止 : たとえば、データベース管理者(DBA)が、一部のメンテナンス・アクティビティを実行するためにRACインスタンスを正常にシャットダウンしたいことがあります。インスタンス・シャットダウンはFAN Planned Downイベントを生成し、それをFCFが捕捉します。 続いてFCFはすべての新しいリクエストを他のRACインスタンスに送り、現在アクティブなトランザクションを排出するか完了させます。

注意:
長い間実行されているトランザクションは、強制終了が必要な場合があります。

2.3 セキュリティ、キャッシュ、前処理と後処理、環境、およびExcel設定の構成

セキュリティ、キャッシュ、前処理と後処理、環境およびExcel設定の構成は、「SQL Developerを使用したOracle REST Data Servicesの管理(オプション)」を参照してください。

2.4 Oracle REST Data Servicesで使用するRESTfulサービスの開発

Oracle REST Data Servicesで使用するRESTfulサービスを開発する方法の詳細は、「Oracle REST Data Servicesアプリケーションの開発」を参照してください。

3 Oracle REST Data Servicesアプリケーションの開発

この項では、Oracle REST Data Servicesを使用するアプリケーションを開発する方法を説明します。これにはガイダンスと例を含みます。

注意:

すぐに開始する場合は、ここで「RESTfulサービスのスタート・ガイド」のチュートリアルを試すことができます。ただし、後でこの章に戻り、主要な概念と技術を理解してください。

注意:

チュートリアルおよび例を試してみる前に、Oracle Application Express 4.2以上およびOracle REST Data Services 3.0以上の両方がインストールされ、構成されていることを確認してください。

JSONデータの永続にOracle REST APIを使用する場合は、まずOracle REST APIをインストールする必要があります。詳細は、『Oracle REST Data Services SODA for REST開発者ガイド』のOracle REST APIのインストールに関する項を参照してください。

読者はOracle Application Expressに精通していることを前提としています。Oracle Application Expressを初めて使用する場合は、Oracle Application Expressのドキュメントを参照してください。

トピック:

- 関連するソフトウェアの紹介

- RESTfulサービスのスタート・ガイド

- RESTアクセスのためのスキーマ・オブジェクトの自動的な有効化(AutoREST)

- 問合せでのフィルタリング

- RESTfulサービスへのセキュアなアクセスの構成

- Oracle REST Data Servicesのユーザー・ロールについて

- WebLogic ServerおよびGlassFishユーザー・リポジトリに対する認証

- 既存のグループ/ロール・モデルとの統合

- Oracle REST Data Services PL/SQL APIの使用

また、補足的な拡張例として、アプリケーションの構築にOracle Application Expressを使用する「開発チュートリアル: イメージ・ギャラリの作成」を確認することもできます。

3.1 関連するソフトウェアの紹介

この項では、Oracle REST Data Servicesを使用するアプリケーションを開発するための、いくつかの重要な関連ソフトウェアについて説明します。

トピック:

- Oracle Application Expressについて

- RESTful Webサービスについて

関連トピック

- Oracle REST Data Servicesについて

3.1.1 Oracle Application Expressについて

Oracle Application Expressは、Oracleデータベースのための宣言型のラピッドWebアプリケーション開発ツールです。これは、完全にサポートされている、Oracleデータベースのすべてのエディションで利用可能なコスト不要のオプションです。Webブラウザのみを使用して、高速でセキュアなプロフェッショナル・アプリケーションを開発し、デプロイできます。

3.1.2 RESTful Webサービスについて

Representational State Transfer (REST)は、World Wide Webのような分散ハイパーメディア・システムのためのソフトウェア・アーキテクチャのスタイルです。APIは、RESTの原則に適合する場合にRESTfulと称されます。RESTの詳しい説明はこのマニュアルの対象外ですが、RESTful APIの特性を次に示します。

- データは一連のリソースとしてモデル化されます。リソースはURIで識別されます。

- リソースの操作には、小さく統一的な操作セットが使用されます(たとえば、PUT、POST、GET、DELETE)。

- リソースは、複数の形式で表示できます(たとえば、ブログはHTML形式およびRSS形式で表示できます)。

- サービスはステートレスですが、クライアントが関連リソースへのアクセスを望む可能性があるため、戻される表現の中で(通常はハイパーテキスト・リンクを提供することで)関連リソースを示します。

Oracle Application Expressのリリース4.2では、Oracle REST Data Servicesの機能を活用し、RESTful Webサービスを定義およびテストするための使いやすいグラフィカル・ユーザー・インタフェースが開発者に提供されています。

3.2 RESTfulサービスのスタート・ガイド

この項では、RESTfulサービスを紹介し、RESTfulサービスを使用するアプリケーションを開発するためのガイドラインと例を提供します。

トピック:

- RESTfulサービスの用語

- リクエスト・パスの構文要件について

- インストールに含まれるドキュメント「スタート・ガイド」

- cURLおよびRESTfulサービスのテストについて

- RESTアクセスのためのスキーマ・オブジェクトの自動的な有効化(AutoREST)

- SQLおよびPL/SQLを使用したRESTful Servicesの手動作成

- ORDSを使用した日付の処理

関連トピック

- Oracle REST Data Servicesアプリケーションの開発

3.2.1 RESTfulサービスの用語

この項では、このドキュメント全体で使用されている共通の用語をいくつか紹介します。

- RESTfulサービス: RESTfulアーキテクチャ・スタイルの原則に準拠したHTTP Webサービス。

- リソース・モジュール: 関連するリソース・テンプレートをグループ化するために使用される構成単位。

- リソース・テンプレート: 一部のURI (Universal Resource Identifiers)のセットにサービス要求を行える個別のRESTfulサービス。URIのセットは、リソース・テンプレートのURIパターンで定義されます

- URIパターン: リソース・テンプレートのパターン。ルート・パターンの使用をお薦めしますが、ルート・パターンまたはURIテンプレートのいずれにもできます。

- ルート・パターン: URIのパス部分をコンポーネント・パーツに分解することに重点をおくパターン。たとえば、/:object/:id?のパターンは/emp/101と一致し(101のidでempリソースにあるアイテムのリクエストと一致)、/emp/とも一致します(:idパラメータには?修飾子の注釈が付き、これはidパラメータがオプションであることを示すため、empリソースのリクエストとも一致します)。
ルート・パターンの詳細な説明は、<sqldeveloper-install>\ordsおよびOracle REST Data Servicesを手動でインストールした場所(存在する場合)の下にあるdocs\javadoc\plugin-api\route-patterns.htmlを参照してください。

- URIテンプレート: 所定のリソース・テンプレートが処理可能な特定のURIパターンを定義する簡易文法。たとえば、employees/{id}というパターンは、パスがemployees/で始まる任意のURI (employees/2560など)に一致します。

- リソース・ハンドラ: 特定のリソース・テンプレートで特定のHTTPメソッドのサービスを行うために必要なロジックを提供します。たとえは、前のリソース・テンプレートでGET HTTPメソッドを行うためのロジックは次のようになります。

select empno, ename, dept from emp where empno = :id

- HTTP操作: HTTP (HyperText Transport Protocol)により、GET(リソース内容の取得)、POST(新規リソースの格納)、PUT(既存のリソースの更新)およびDELETE(リソースの削除)という、リソースで実行可能な標準メソッドが定義されます。

関連トピック

- RESTful Webサービスについて

3.2.2 リクエスト・パスの構文要件について

Oracle REST Data Servicesは、パス・ベースの攻撃を防ぐために、各リクエストURLのパス要素の構文に対していくつかの検証チェックを実行します。

各パスは、次のルールに準拠する必要があります。

- 空や空白文字のみでない

- 次のいずれの文字も含まない: ?、#、;、%

- null文字(\u0000)を含まない

- 次の範囲の文字を含まない: \u0001-\u0031

- ホワイトスペースまたはピリオド(.)で終わらない

- 二重のフォワード・スラッシュ(//)または二重のバックスラッシュ(\\)を含まない

- 連続する2つ以上のピリオドを含まない(..、...など)

- 全長が{@value #MAX_PATH_LENGTH}文字以下である

- ファイル拡張子を含んで、または含まないで、次のいずれの名前にも一致しない(大文字と小文字は区別されない): CON、PRN、AUX、CLOCK$、NUL、COM0、COM1、COM2、COM3、COM4、COM5、COM6、COM7、COM8、COM9、LPT0、LPT1、LPT2、LPT3、LPT4、LPT5、LPT6、LPT7、LPT8、LPT9

オブジェクトを自動REST有効化する場合、これらの要件を満たさないオブジェクト名は避けてください。たとえば、#EMPSという名前の表は作成しないでください。不適格な名前を持つオブジェクトを自動REST有効化するには、要件を満たす別名を使用する必要があります。

これらの要件は、URLデコードされた形式のURLに適用され、パーセント・エンコーディングによる回避の試みを阻止します。

3.2.3 インストールに含まれるドキュメント「スタート・ガイド」

Oracle REST Data Servicesをインストールすると、参考になるサブフォルダやファイルの入った例のフォルダが作成されます。インストール・フォルダの階層には、次のものがあります。

ords
conf
docs
examples
soda
getting-started
getting-started-nosql
...

階層の内容:

- examples\soda: 『Oracle REST Data Services SODA for REST開発者ガイド』の中のいくつかの例で使用されるサンプルのJSONドキュメントが含まれています。

- examples\getting-started: index.htmlをダブルクリックすると、Oracle REST Data Servicesを使用したRESTfulサービスの開発を開始する方法についての簡潔なドキュメントが表示されます。このマニュアルでは、まず初めにSQL Developerの使用を中心に説明します。(SQL Developerは、Oracle REST Data Servicesを管理するための主ツールです。たとえば、スキーマおよび表のRESTサポートを自動的に有効にする機能は、SQL Developerでのみ使用可能です。)

- examples\getting-started-nosql: index.htmlをダブルクリックすると、Oracle REST Data Servicesを使用したNoSQLストア・アクセスを開始する方法についての簡潔なドキュメントが表示されます。

3.2.4 cURLおよびRESTfulサービスのテストについて

他の項で、Webブラウザを使用したRESTfulサービスのテストについて説明しています。しかし、RESTfulサービスをテストするもう1つの便利な方法に、cURLという名前のコマンドライン・ツールを使用する方法があります。

この強力なツールはほとんどのプラットフォームで利用可能で、RESTfulサービスとの間で送受信されるデータを確認および制御できます。

curl -i https://server:port/ords/workspace/hr/employees/7369

この例では、次のようなレスポンスが生成されます。

HTTP/1.1 200 OK
Server: Oracle-REST-Data-Services/2.0.6.78.05.25
ETag: "..."
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 28 Mar 2014 16:49:34 GMT

{
"empno":7369,
"ename":"SMITH",
"job":"CLERK",
"mgr":7902,
"hiredate":"1980-12-17T08:00:00Z",
"sal":800,
"deptno":20
}

-iオプションは、cURLに対し、サーバーから戻されたHTTPヘッダーを表示するように指示します。

関連トピック

- Application ExpressでのサンプルのRESTfulサービスの調査(チュートリアル)

関連項目:
cURL
この項の例では、「サンプルのRESTfulサービスの調査(チュートリアル)」で説明したサービスでcURLを使用します。

3.2.5 RESTアクセスのためのスキーマ・オブジェクトの自動的な有効化(AutoREST)

Oracle REST Data Servicesがデータベース接続に関連付けられたシステムにインストールされている場合、AutoREST機能を使用して、そのデータベース接続と関連付けられたスキーマ内の指定された表およびビューへのOracle REST Data Servicesアクセスを簡単に有効または無効にすることができます。表、ビューまたはPL/SQLファンクション、プロシージャまたはパッケージへのRESTアクセスを有効化すると、RESTfulサービスを介したアクセスが可能になります。

AutoRESTは、データベース表をRESTリソースとして公開する素早く簡単な方法です。労力を削減するために、柔軟性とカスタマイズの容易性を若干犠牲にします。AutoRestによってデータを素早く公開できますが、(例えた言い方をすると)ガイド・レールのセットに乗せてしまいます。たとえば、出力形式や入力形式をカスタマイズできず、追加の検証も実行できません。

一方、手動で作成したリソース・モジュールでは、RESTリソースをサポートするためにSQLおよびPL/SQLを指定する必要があります。リソース・モジュールを使用することは労力を要しますが、柔軟性を向上します。たとえば、どのフィールドを含めるかのカスタマイズ、複数の表の結合、およびPL/SQLを使用した受信データの検証を実現できます。

そのため、アプリケーション開発者は、AutoRESTの「ガイド・レール」を使用するか、まさに必要なことを実行するためにリソース・モジュールを作成するかを選択する必要があります。AutoRESTを選択した場合、スキーマ内で表(または表のセット)を有効にするだけです。

スキーマを有効化することは、スキーマ内のすべての表とビューを有効化することとは異なることに注意してください。Oracle REST Data Servicesにスキーマが存在することを認識させ、HTTPに公開するリソースがゼロまたはそれ以上ある可能性があることを意味するのみです。それらのリソースは、AutoRESTリソースでも、リソース・モジュール・リソースでもかまいません。

Oracle SQL Developerの便利なウィザードを使用して、Oracle REST Data Servicesの問合せによる個々のデータベース・スキーマ・オブジェクト(表、ビュー、およびPL/SQL)へのアクセスを自動的に有効にできます。(これらの機能は、Oracle REST Data Services対応のスキーマでのみ有効で、Oracle Application Expressワークスペースでは有効でないことに注意してください。)

1つ以上の指定した表またはビューに対するOracle REST Data Servicesアクセスを有効にするには、SQL Developerで次を実行する必要があります。

1. RESTアクセス用にスキーマ(接続に関連付けられているスキーマ)を有効にします。
スキーマ・レベル: 接続に関連付けられているスキーマの(次の手順で指定する)選択したオブジェクトへのOracle REST Data Servicesアクセスを有効にするには、「接続」ナビゲータでその名前を右クリックし、「RESTサービス」、「RESTサービスの有効化」の順に選択します。

(接続に関連付けられているスキーマのオブジェクトへのOracle REST Data Servicesアクセスのサポートを削除するには、「接続」ナビゲータでその名前を右クリックし、「RESTサービス」、「RESTサービスの削除」の順に選択します。)

2. 希望するオブジェクトのRESTアクセスを個別に有効化します。
表またはビュー・レベル: 指定した表またはビューへのOracle REST Data Servicesアクセスを有効化するには、「接続」ナビゲータでその名前を右クリックし、「RESTサービスの有効化」の順に選択します。

使用方法の詳細は、SQL Developerのウィザードまたはダイアログ・ボックスの「ヘルプ」ボタンをクリックします。

3.2.5.1 例: RESTfulサービスを使用してオブジェクトにアクセスする

この項では、Oracle REST Data Services問合せの使用例およびREST対応した後の表やビューに対するその他の操作の例を示します。

SQL Developerを使用して、表オブジェクトおよびビュー・オブジェクトを自動的にRESTfulサービスとして公開できます。この項では、これらのRESTfulサービスにアクセスする例を説明します。

ヒント:

こうした例は、これらのリソースにアクセスするのに使用するURLパターンを示しますが、クライアントはこれらのURLの構造の知識をハード・コーディングしないでください。かわりに、クライアントはリソースのハイパーリンクに従ってリソース間を移動してください。URLパターンの構造は、将来のリリースで進化したり、変更されたりする可能性があります。

この項では、RESTfulサービスを使用してオブジェクトにアクセスする例を説明します。

- スキーマ・メタデータのGet

- オブジェクト・メタデータのGet

- オブジェクト・データのGet

- ページ区切りを使用した表データのGet

- 問合せを使用した表データのGet

- 主キーを使用した表の行のGet

- 表の行の挿入

- 表の行の更新/挿入

- フィルタを使用したDelete

- バッチ・ロードによるPost

3.2.5.1.1 スキーマ・メタデータのGet

この例では、指定したスキーマの別名で、使用可能なリソースの一覧を取得します。表またはビューを自動的に有効化することで作成されるRESTfulサービスと、リソース・モジュールによって作成されるRESTfulサービスを示します。

この例では、指定したスキーマの別名で、使用可能なリソースの一覧を取得します。

パターン: GET http://<HOST>:<PORT>/ords/<SchemaAlias>/metadata-catalog/

例: GET http://localhost:8080/ords/ordstest/metadata-catalog/

結果:

{
"items": [
{
"name": "EMP",
"links": [
{
"rel": "describes",
"href": "http://localhost:8080/ords/ordstest/emp/"
},
{
"rel": "canonical",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/emp/",
"mediaType": "application/json"
}
]
},
{
"name": "oracle.examples.hello",
"links": [
{
"rel": "describes",
"href": "http://localhost:8080/ords/ordstest/examples/hello/"
},
{
"rel": "canonical",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/examples/hello/",
"mediaType": "application/json"
}
]
}
],
"hasMore": false,
"limit": 25,
"offset": 0,
"count": 2,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/"
},
{
"rel": "first",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/"
}
]
}

リソースの一覧には、次が含まれます。

- REST対応の表またはビューを示すリソース。

- リソース・モジュールによって定義されているリソース。具体的なパス(つまり、パラメータを含まない)のリソースのみが表示されることに注意してください。たとえば、/module/some/path/のパスのリソースは表示されますが、/module/some/:parameter/のパスのリソースは表示されません。

有効な各リソースには、次の2つのハイパーリンクがあります。

- 関係にdescribesのあるリンクは実際のリソースを指します。

- 関係にcanonicalのあるリンクはリソースを説明します。

3.2.5.1.2 オブジェクト・メタデータのGet

この例では、個別オブジェクトのメタデータ(オブジェクトを説明するメタデータ)を取得しています。メタデータの場所はcanonicalリンクの関係で指定されています。

パターン: GET http://<HOST>:<PORT>/ords/<SchemaAlias>/metadata-catalog/<ObjectAlias>/

例: GET http://localhost:8080/ords/ordstest/metadata-catalog/emp/

結果:

{
"name": "EMP",
"primarykey": [
"empno"
],
"members": [
{
"name": "empno",
"type": "NUMBER"
},
{
"name": "ename",
"type": "VARCHAR2"
},
{
"name": "job",
"type": "VARCHAR2"
},
{
"name": "mgr",
"type": "NUMBER"
},
{
"name": "hiredate",
"type": "DATE"
},
{
"name": "sal",
"type": "NUMBER"
},
{
"name": "comm",
"type": "NUMBER"
},
{
"name": "deptno",
"type": "NUMBER"
}
],
"links": [
{
"rel": "collection",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/",
"mediaType": "application/json"
},
{
"rel": "canonical",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/emp/"
},
{
"rel": "describes",
"href": "http://localhost:8080/ords/ordstest/emp/"
}
]
}

3.2.5.1.3 オブジェクト・データのGet

この例では、オブジェクトのデータを取得します。オブジェクトの各行は、JSON配列に埋め込まれているJSONオブジェクトに対応します

パターン: GET http://<HOST>:<PORT>/ords/<SchemaAlias>/<ObjectAlias>/

例: GET http://localhost:8080/ords/ordstest/emp/

結果:

{
"items": [
{
"empno": 7499,
"ename": "ALLEN",
"job": "SALESMAN",
"mgr": 7698,
"hiredate": "1981-02-20T00:00:00Z",
"sal": 1600,
"comm": 300,
"deptno": 30,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/7499"
}
]
},
...
{
"empno": 7934,
"ename": "MILLER",
"job": "CLERK",
"mgr": 7782,
"hiredate": "1982-01-23T00:00:00Z",
"sal": 1300,
"comm": null,
"deptno": 10,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/7934"
}
]
}
],
"hasMore": false,
"limit": 25,
"offset": 0,
"count": 13,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/"
},
{
"rel": "edit",
"href": "http://localhost:8080/ords/ordstest/emp/"
},
{
"rel": "describedby",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/emp/"
},
{
"rel": "first",
"href": "http://localhost:8080/ords/ordstest/emp/"
}
]
}

3.2.5.1.4 ページ区切りを使用した表データのGet

この例では、結果データのページ区切りを制御するパラメータのoffsetおよびlimitを指定します。

パターン: GET http://<HOST>:<PORT>/ords/<SchemaAlias>/<ObjectAlias>/?offset=<Offset>&limit=<Limit>

例: GET http://localhost:8080/ords/ordstest/emp/?offset=10&limit=5

結果:

{
"items": [
{
"empno": 7900,
"ename": "JAMES",
"job": "CLERK",
"mgr": 7698,
"hiredate": "1981-12-03T00:00:00Z",
"sal": 950,
"comm": null,
"deptno": 30,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/7900"
}
]
},
...
{
"empno": 7934,
"ename": "MILLER",
"job": "CLERK",
"mgr": 7782,
"hiredate": "1982-01-23T00:00:00Z",
"sal": 1300,
"comm": null,
"deptno": 10,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/7934"
}
]
}
],
"hasMore": false,
"limit": 5,
"offset": 10,
"count": 3,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/"
},
{
"rel": "edit",
"href": "http://localhost:8080/ords/ordstest/emp/"
},
{
"rel": "describedby",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/emp/"
},
{
"rel": "first",
"href": "http://localhost:8080/ords/ordstest/emp/?limit=5"
},
{
"rel": "prev",
"href": "http://localhost:8080/ords/ordstest/emp/?offset=5&limit=5"
}
]
}

3.2.5.1.5 問合せを使用した表データのGet

この例では、戻されるオブジェクトを制限するフィルタ句を指定します。

パターン: GET http://<HOST>:<PORT>/ords/<SchemaAlias>/<ObjectAlias>/?q=<FilterClause>

例: GET http://localhost:8080/ords/ordstest/emp/?q={"deptno":{"$lte":20}}

結果:

{
"items": [
{
"empno": 7566,
"ename": "JONES",
"job": "MANAGER",
"mgr": 7839,
"hiredate": "1981-04-01T23:00:00Z",
"sal": 2975,
"comm": null,
"deptno": 20,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/7566"
}
]
},
...
{
"empno": 7934,
"ename": "MILLER",
"job": "CLERK",
"mgr": 7782,
"hiredate": "1982-01-23T00:00:00Z",
"sal": 1300,
"comm": null,
"deptno": 10,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/7934"
}
]
}
],
"hasMore": false,
"limit": 25,
"offset": 0,
"count": 7,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/?q=%7B%22deptno%22:%7B%22%24lte%22:20%7D%7D"
},
{
"rel": "edit",
"href": "http://localhost:8080/ords/ordstest/emp/?q=%7B%22deptno%22:%7B%22%24lte%22:20%7D%7D"
},
{
"rel": "describedby",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/emp/"
},
{
"rel": "first",
"href": "http://localhost:8080/ords/ordstest/emp/?q=%7B%22deptno%22:%7B%22%24lte%22:20%7D%7D"
}
]
}

3.2.5.1.6 主キーを使用した表の行のGet

この例では、オブジェクトを識別するキーの値を指定することでオブジェクトを取得します。

パターン: GET http://<HOST>:<PORT>/ords/<SchemaAlias>/<ObjectAlias>/<KeyValues>

ここで、<KeyValues>はカンマで区切ったキー値のリストです(キー順)。

例: GET http://localhost:8080/ords/ordstest/emp/7839

結果:

{
"empno": 7839,
"ename": "KING",
"job": "PRESIDENT",
"mgr": null,
"hiredate": "1981-11-17T00:00:00Z",
"sal": 5000,
"comm": null,
"deptno": 10,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/7839"
},
{
"rel": "edit",
"href": "http://localhost:8080/ords/ordstest/emp/7839"
},
{
"rel": "describedby",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/emp/item"
},
{
"rel": "collection",
"href": "http://localhost:8080/ords/ordstest/emp/"
}
]
}

3.2.5.1.7 表の行の挿入

この例では、オブジェクトにデータを挿入します。リクエストに付加するボディのデータは、挿入するデータを格納したJSONオブジェクトです。

オブジェクトに主キーがある場合、オブジェクトには主キー・フィールドに移入する挿入トリガーが必要です。表に主キーがない場合には、行のROWIDがアイテムの識別子として使用されます。

オブジェクトに主キー値を割り当てるトリガーがない場合、次の項「表の行の更新/挿入」で説明されているPUT操作をかわりに使用してください。

パターン: POST http://<HOST>:<PORT>/ords/<SchemaAlias>/<ObjectAlias>/

例:

curl -i -H "Content-Type: application/json" -X POST -d "{ \"empno\" :7, \"ename\": \"JBOND\", \"job\":\"SPY\", \"deptno\" :11 }" "http://localhost:8080/ords/ordstest/emp/
Content-Type: application/json

{ "empno" :7, "ename": "JBOND", "job":"SPY", "deptno" :11 }

結果:

{
"empno": 7,
"ename": "JBOND",
"job": "SPY",
"mgr": null,
"hiredate": null,
"sal": null,
"comm": null,
"deptno": 11,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/7"
},
{
"rel": "edit",
"href": "http://localhost:8080/ords/ordstest/emp/7"
},
{
"rel": "describedby",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/emp/item"
},
{
"rel": "collection",
"href": "http://localhost:8080/ords/ordstest/emp/"
}
]
}

3.2.5.1.8 表の行の更新/挿入

この例では、オブジェクト内のデータを挿入または更新します(「アップサート」とも呼ばます)。リクエストに付加するボディのデータは、挿入または更新するデータを格納したJSONオブジェクトです。

パターン: PUT http://<HOST>:<PORT>/ords/<SchemaAlias>/<ObjectAlias>/<KeyValues>

例:

curl -i -H "Content-Type: application/json" -X PUT -d "{ \"empno\" :7, \"ename\": \"JBOND\", \"job\":\"SPY\", \"deptno\" :11 }" "http://localhost:8080/ords/ordstest/emp/7
Content-Type: application/json

{ "empno" :7, "ename": "JBOND", "job":"SPY", "deptno" :11 }

結果:

{
"empno": 7,
"ename": "JBOND",
"job": "SPY",
"mgr": null,
"hiredate": null,
"sal": null,
"comm": null,
"deptno": 11,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/emp/7"
},
{
"rel": "edit",
"href": "http://localhost:8080/ords/ordstest/emp/7"
},
{
"rel": "describedby",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/emp/item"
},
{
"rel": "collection",
"href": "http://localhost:8080/ords/ordstest/emp/"
}
]
}

3.2.5.1.9 フィルタを使用したDelete

この例では、フィルタ句で指定されたオブジェクトのデータを削除します。

パターン: DELETE http://<HOST>:<PORT>/ords/<SchemaAlias>/<ObjectAlias>/?q=<FilterClause>

例: curl -i -X DELETE http://localhost:8080/ords/ordstest/emp/?q={"deptno":11}"

結果:

{
"itemsDeleted": 1
}

3.2.5.1.10 バッチ・ロードによるPost

この例では、バッチ・ロード機能を使用してオブジェクトのデータを挿入します。リクエストに付加するボディのデータはCSVファイルです。バッチ操作の動作はオプションの問合せパラメータを使用して制御できます。このパラメータは表3-1で説明しています。

パターン: POST http://<HOST>:<PORT>/ords/<SchemaAlias>/<ObjectAlias>/batchload?<Parameters>

パラメータ:

表3-1 バッチ・ロードのパラメータ

パラメータ

説明

batchesPerCommit

コミットの頻度を設定します。バッチがデータベースに送信された後、オプションのコミット・ポイントを設定できます。デフォルトは10個のバッチごとです。0はロードの終了までコミットを延期することを示します。型: Integer。

batchRows

データベースに送信する各バッチ内の行数を設定します。デフォルトは、バッチ当たり50行です。型: Integer。

dateFormat

日付データ型の書式マスクを設定します。入力データを日付型の列に変換するときに、この形式が使用されます。型: String。

delimiter

ファイル内のフィールドのフィールド区切り文字を設定します。デフォルトはカンマ(,)です。

enclosures

embeddedRightDouble

errors

エラー数の制限に使用されるユーザー・オプションを設定します。エラーの数がerrorsMax(サービスのオプション)またはerrors(ユーザーのオプション)に指定された値を超えた場合、ロードが終了します。

エラーを許容しない場合は、0を指定します。すべてのエラーを許容する(errorsMaxの値まで)場合は、UNLIMITED(-1)を指定します。

errorsMax

ユーザーによって許容されるエラーの数を制限するために使用されるサービスのオプションです。これは、サービス・プロバイダ用のオプションとして用意されており、ユーザーのオプションとしては公開しません。エラーの数がerrorsMax(サービスのオプション)またはerrors(ユーザーのオプション)に指定された値を超えた場合、ロードが終了します。

エラーを許容しない場合は、0を指定します。すべてのエラーを許容する場合は、UNLIMITED(-1)を指定します。

lineEnd

行の終わり(ターミネータ)を設定します。ファイルに、標準的な行の終了文字(\r、\r\nまたは\n)が含まれている場合は、lineEndを指定する必要はありません。

lineMax

データ・ストリーム中の行(row)当たりの行(line)数を識別するための最大の行(line)の長さを設定します。lineMaxの値により、誤ったlineEnd文字が使用された場合に、ストリーム全体を単一の行として読むことを防止できます。デフォルトは無制限。

locale

ロケールを設定します。

responseEncoding

レスポンス・ストリームのエンコーディングを設定します。

responseFormat

レスポンス・ストリームの形式を設定します。この形式は、メッセージや不良データを書式化する方法を決定します。有効な値: RAW、SQL。

timestampFormat

タイム・スタンプ・データ型の書式マスクを設定します。入力データをタイム・スタンプ型の列に変換するときに、この形式が使用されます。

timestampTZFormat

タイム・スタンプのタイムゾーン・データ型の書式マスクを設定します。入力データをタイム・スタンプのタイムゾーン型の列に変換するときに、この形式が使用されます。

truncate

ロードする前に表のデータ行を削除するか、または削除する方法、あるいはその両方を示します。False(デフォルト)の場合、ロード前に表のデータを削除しません。Trueの場合、SQL文のDELETEで表のデータが削除されます。Truncateの場合、SQL文のTRUNCATEで表のデータが削除されます。

例:

POST http://localhost:8080/ords/ordstest/emp/batchload?batchRows=25
Content-Type: text/csv

empno,ename,job,mgr,hiredate,sal,comm,deptno
0,M,SPY MAST,,2005-05-01 11:00:01,4000,,11
7,J.BOND,SPY,0,2005-05-01 11:00:01,2000,,11
9,R.Cooper,SOFTWARE,0,2005-05-01 11:00:01,10000,,11
26,Max,DENTIST,0,2005-05-01 11:00:01,5000,,11

結果:

#INFO Number of rows processed: 4
#INFO Number of rows in error: 0
#INFO Elapsed time: 00:00:03.939 - (3,939 ms) 0 - SUCCESS: Load processed without errors

3.2.5.2 問合せでのフィルタリング

この項では、REST対応の表やビューに対する問合せでのフィルタリングの例を示し、説明します。

フィルタリングは、全コレクションで見つかった項目のサブセットが含まれている複数ページのリソース全体に対し、リクエストごとの動的フィルタ定義を使用してコレクション・リソースを制限する処理です。フィルタリングは、大規模なコレクションの効率的な走査を可能にします。

問合せでフィルタリングするには、q=FilterObjectパラメータを含め、FilterObjectはリソースに適用するカスタムな選択やソートを表すJSONオブジェクトです。たとえば、次のようなリソースを仮定します。

https://example.com/ords/scott/emp/

次の問合せには、ENAME列を「JOHN」に制限するフィルタが含まれています。

https://example.com/ords/scott/emp/?q={"ENAME":"JOHN"}

3.2.5.2.1 FilterObjectの文法

FilterObjectは、次の構文に準拠したJSONオブジェクトである必要があります。

FilterObject { orderby , asof, wmembers }

orderby、asofおよびwmembers属性はオプションで、その定義は次のとおりです。

orderby
"$orderby": {orderByMembers}

orderByMembers
orderByProperty
orderByProperty , orderByMembers

orderByProperty
columnName : sortingValue

sortingValue
"ASC"
"DESC"
"-1"
"1"
-1
1

asof
"$asof": date
"$asof": "datechars"
"$asof": scn
"$asof": +int

wmembers
wpair
wpair , wmembers

wpair
columnProperty
complexOperatorProperty

columnProperty
columnName : string
columnName : number
columnName : date
columnName : simpleOperatorObject
columnName : complexOperatorObject
columnName : [complexValues]

columnName
"\p{Alpha}[[\p{Alpha}]]([[\p{Alnum}]#$_])*$"

complexOperatorProperty
complexKey : [complexValues]
complexKey : simpleOperatorObject

complexKey
"$and"
"$or"

complexValues
complexValue , complexValues

complexValue
simpleOperatorObject
complexOperatorObject
columnObject

columnObject
{columnProperty}

simpleOperatorObject
{simpleOperatorProperty}

complexOperatorObject
{complexOperatorProperty}

simpleOperatorProperty
"$eq" : string | number | date
"$ne" : string | number | date
"$lt" :  number | date
"$lte" : number | date
"$gt" : number | date
"$gte" : number | date
"$instr" : string
"$ninstr" : string
"$like" : string
"$null" : null
"$notnull" : null
"$between" : betweenValue

betweenValue
[null , betweenNotNull]
[betweenNotNull , null]
[betweenRegular , betweenRegular]

betweenNotNull
number
date

betweenRegular
string
number
date

データ型の定義には次のものがあります。

string
JSONString
number
JSONNumber
date
{"$date":"datechars"}
scn
{"$scn": +int}

説明:

datechars is an RFC3339 date format in UTC (Z)

JSONString
""
" chars "
chars
char
char chars
char
any-Unicode-character except-"-or-\-or-control-character
\"
\\
\/
\b
\f
\n
\r
\t
\u four-hex-digits

JSONNumber
int
int frac
int exp
int frac exp
int
digit
digit1-9 digits
- digit
- digit1-9 digits
frac
. digits
exp
e digits
digits
digit
digit digits
e
e
e+
e-
E
E+
E-

FilterObjectはRFC3986の第2.1項に従って符号化する必要があります。

3.2.5.2.2 例: FilterObjectの記述

FilterObjectの記述における演算子の例を次に示します。

ORDER BY property ($orderby)

Order by with literals

{
"$orderby": {"SALARY":  "ASC","ENAME":"DESC"}
}

Order by with numbers

{
"$orderby": {"SALARY":  -1,"ENAME":  1}
}

ASOF property ($asof)

With SCN (Implicit)

{
"$asof": 1273919
}

With SCN (Explicit)

{
"$asof": {"$scn": "1273919"}
}

With Date (Implicit)

{
"$asof": "2014-06-30T00:00:00Z"
}

With Date (Explicit)

{
"$asof": {"$date": "2014-06-30T00:00:00Z"}
}

EQUALS operator ($eq)

(Implicit and explicit equality supported._

Implicit (Support String and Dates too)

{
"SALARY": 1000
}

Explicit

{
"SALARY": {"$eq": 1000}
}

Strings

{
"ENAME": {"$eq":"SMITH"}
}

Dates

{
"HIREDATE": {"$date": "1981-11-17T08:00:00Z"}
}

NOT EQUALS operator ($ne)

Number

{
"SALARY": {"$ne": 1000}
}

String

{
"ENAME": {"$ne":"SMITH"}
}

Dates

{
"HIREDATE": {"$ne": {"$date":"1981-11-17T08:00:00Z"}}
}

LESS THAN operator ($lt)
(Supports dates and numbers only)

Numbers

{
"SALARY": {"$lt": 10000}
}

Dates

{
"SALARY": {"$lt": {"$date":"1999-12-17T08:00:00Z"}}
}

LESS THAN OR EQUALS operator ($lte)
(Supports dates and numbers only)

Numbers

{
"SALARY": {"$lte": 10000}
}

Dates

{
"HIREDATE": {"$lte": {"$date":"1999-12-17T08:00:00Z"}}
}

GREATER THAN operator ($gt)
(Supports dates and numbers only)

Numbers

{
"SALARY": {"$gt": 10000}
}

Dates

{
"SALARY": {"$gt": {"$date":"1999-12-17T08:00:00Z"}}
}

GREATER THAN OR EQUALS operator ($gte)
(Supports dates and numbers only)

Numbers

{
"SALARY": {"$gte": 10000}
}

Dates

{
"HIREDATE": {"$gte": {"$date":"1999-12-17T08:00:00Z"}}
}

In string operator ($instr)
(Supports strings only)

{
"ENAME": {"$instr":"MC"}
}

Not in string operator ($ninstr)
(Supports strings only)

{
"ENAME": {"$ninstr":"MC"}
}

#### LIKE operator ($like)
(Supports strings. Eescape character not supported to try to match expressions with _ or % characters.)

{
"ENAME": {"$like":"AX%"}
}

#### BETWEEN operator ($between)
(Supports string, dates, and numbers)

Numbers

{
"SALARY": {"$between": [1000,2000]}
}

Dates

{
"SALARY": {"$between": [{"$date":"1989-12-17T08:00:00Z"},{"$date":"1999-12-17T08:00:00Z"}]}
}

Strings

{
"ENAME": {"$between": ["A","C"]}
}

Null Ranges ($lte equivalent)
(Supported by numbers and dates only)

{
"SALARY": {"$between": [null,2000]}
}

Null Ranges ($gte equivalent)
(Supported by numbers and dates only)

{
"SALARY": {"$between": [1000,null]}
}

#### NULL operator ($null)

{
"ENAME": {"$null": null}
}

#### NOT NULL operator ($notnull)

{
"ENAME": {"$notnull": null}
}

#### AND operator ($and)
(Supports all operators, including $and and $or)

Column context delegation
(Operators inside $and will use the closest context defined in the JSON tree.)

{
"SALARY": {"$and": [{"$gt": 1000},{"$lt":4000}]}
}

Column context override
(Example: salary greater than 1000 and name like S%)

{
"SALARY": {"$and": [{"$gt": 1000},{"ENAME": {"$like":"S%"}} ] }
}

Implicit and in columns

```
{
"SALARY": [{"$gt": 1000},{"$lt":4000}]
}
```

High order AND
(All first columns and or high order operators -- $and and $ors -- defined at the first level of the JSON will be joined and an implicit AND)
(Example: Salary greater than 1000 and name starts with S or T)

{
"SALARY": {"$gt": 1000},
"ENAME": {"$or": [{"$like":"S%"}, {"$like":"T%"}]}
}

Invalid expression (operators $lt and $gt lack column context)

{
"$and": [{"$lt": 5000},{"$gt": 1000}]
}

Valid alternatives for the previous invalid expression

{
"$and": [{"SALARY": {"$lt": 5000}}, {"SALARY": {"$gt": 1000}}]
}

{
"SALARY": [{"$lt": 5000},{"$gt": 1000}]
}

{
"SALARY": {"$and": [{"$lt": 5000},{"$gt": 1000}]}
}

OR operator ($or)
(Supports all operators including $and and $or)

Column context delegation
(Operators inside $or will use the closest context defined in the JSON tree)

{
"ENAME": {"$or": [{"$eq":"SMITH"},{"$eq":"KING"}]}
}

Column context override
(Example: name starts with S or salary greater than 1000)

{
"SALARY": {"$or": [{"$gt": 1000},{"ENAME": {"$like":"S%"}} ] }
}

3.2.5.3 自動PL/SQL

この項では、HTTP(S)を介してPL/SQLをリモート・プロシージャ・コール(RPC)のために利用可能にする方法について説明します。

自動PL/SQL機能は、ステートレスなWebサービス環境でエンコーディングとデータ転送の整合性を提供するために標準を使用します。この機能を使用すると、ORDSを介してパッケージ・レベルでOracle DatabaseのストアドPL/SQLファンクションおよびプロシージャを有効化できます。ビューや表を有効化する方法と同様です。

PL/SQLサブプログラムの自動有効化

ORDSは、カタログ・オブジェクト識別子に基づいて、次のPL/SQLオブジェクトの自動有効化をサポートします。

- PL/SQLプロシージャ

- PL/SQLファンクション

- PL/SQLパッケージ

PL/SQLパッケージ内のファンクションおよびプロシージャはPL/SQLパッケージ・オブジェクトの範囲内で名前を付けられているオブジェクトなので、個々に有効化することはできません。このため、粒度レベルがパッケージ・レベルでオブジェクトを有効化します。この粒度レベルは、そのパブリック・ファンクションおよびプロシージャをすべて公開可能にします。

ファンクションおよびプロシージャのサブセットのみを有効化する場合、別の委任パッケージを作成し、ファンクションおよびプロシージャのそのサブセットだけを公開できるようにする必要があります。

注意:
オーバーロードしたパッケージ・ファンクションとプロシージャはサポートされていません。

3.2.5.3.1 PL/SQLオブジェクトの自動有効化がサポートされているメソッドとコンテンツ・タイプ

この項では、この機能によってサポートされるメソッドおよびコンテンツ・タイプについて説明します。

PL/SQLオブジェクトの自動有効化機能は、POSTをHTTPメソッドとしてサポートします。POSTメソッドでは、入力パラメータはペイロード内でエンコードされ、出力パラメータはレスポンスからデコードされます。

注意:
この機能はRPCスタイルのインタラクションを行うため、CRUDからHTTPメソッドへの標準データ・マッピングには適用できません。

サポートされるコンテンツ・タイプは、application/jsonです。

3.2.5.3.2 PL/SQLオブジェクトの自動有効化

この項では、ORDSを介してPL/SQLオブジェクトを自動的に有効化する方法を説明します。

次のいずれかの方法でPL/SQLオブジェクトを有効化できます。

- ORDS PL/SQL APIを使用した自動有効化

- SQL Developerを使用したPL/SQLオブジェクトの自動有効化

3.2.5.3.2.1 ORDS PL/SQL APIを使用した自動有効化

ORDS PL/SQL APIを使用してPL/SQLオブジェクトを有効化できます。

PL/SQLパッケージを有効化するには、次のサンプル・コード・スニペットに示すように、ORDS PL/SQL APIを使用します。

BEGIN
ords.enable_object(
p_enabled => TRUE,
p_schema => 'MY_SCHEMA',
p_object => 'MY_PKG',
p_object_type => 'PACKAGE',
p_object_alias => 'my_pkg',
p_auto_rest_auth => FALSE);
commit;
END;
/

例3-1 PL/SQLファンクションの有効化

PL/SQLファンクションを有効化するには、次のサンプル・コード・スニペットに示すように、ORDS PL/SQL APIを使用します。

BEGIN
ords.enable_object(
p_enabled => TRUE,
p_schema => 'MY_SCHEMA',
p_object => 'MY_FUNC',
p_object_type => 'FUNCTION',
p_object_alias => 'my_func',
p_auto_rest_auth => FALSE);

commit;
END;
/

例3-2 PL/SQLプロシージャの有効化

PL/SQLプロシージャを有効化するには、次のサンプル・コード・スニペットに示すように、ORDS PL/SQL APIを使用します。

BEGIN
ords.enable_object(
p_enabled => TRUE,
p_schema => 'MY_SCHEMA',
p_object => 'MY_PROC',
p_object_type => 'PROCEDURE',
p_object_alias => 'my_proc',
p_auto_rest_auth => FALSE);

commit;
END;
/

3.2.5.3.2.2 SQL Developerを使用したPL/SQLオブジェクトの自動有効化

この項では、SQL Developer 4.2以降を使用してPL/SQLオブジェクトを有効化する方法を説明します。

SQL Developerを使用してPL/SQLオブジェクト(たとえば、パッケージ)を有効化するには、次の手順を実行します。

注意:
これでパッケージ、ファンクションおよびプロシージャを有効化できるようになりました。ただし、有効化の粒度は、パッケージ全体レベル、スタンドアロン・ファンクション・レベル、またはスタンドアロン・プロシージャ・レベルのいずれかです。

1. SQL Developerで、次の図に示すようにパッケージを右クリックします。

図3-1 「RESTサービスの有効化」オプションの選択

2. 「RESTfulサービスを有効にする」を選択して、次のウィザード・ページを表示します。

図3-2 PL/SQLパッケージ・オブジェクトの自動有効化

- オブジェクトの有効化: このオプションを有効にします(つまり、パッケージのRESTアクセスを有効にします)。

- オブジェクト別名: オブジェクト別名としてregistry_pkgを受け入れます。

- 承認が必要: 簡潔性を保つため、このオプションは無効にしておきます。

- ウィザードのRESTfulサマリー・ページで「終了」をクリックします。

3.2.5.3.3 PL/SQLエンドポイントの生成

HTTPエンドポイントは、有効なデータベース・オブジェクトに対してリクエストに応じて動的に生成されます。ORDSは、問合せを使用してエンドポイントを生成するために、接続したデータベース・カタログを使用します。

HTTPエンドポイントを生成するため、すべてのデータベース・オブジェクトに対して次のルールが適用されます。

- 名前はすべて小文字に変換されます

- エンドポイントがすでに割り当てられていなければ、生成されます

ストアド・プロシージャおよびストアド・ファンクションのエンドポイント

ファンクションまたはプロシージャ名は、同じネームスペースの表やビューと同じ方法でURL内に生成されます。

例3-3 ストアド・プロシージャのためのエンドポイントの生成

CREATE OR REPLACE PROCEDURE MY_SCHEMA.MY_PROC IS
BEGIN
NULL;
END;

次のエンドポイントが生成されます。

http://localhost:8080/ords/my_schema/my_proc/

例3-4 パッケージ・プロシージャおよびファンクションのエンドポイント

パッケージ、ファンクションおよびプロシージャ・エンドポイントは、パッケージ名を親として生成されます。オーバーロードしていないか、小文字名がまだ使用されていないファンクションとプロシージャのエンドポイントが生成されます。

次のコード・スニペットで定義されているようにMY_PKGパッケージがある場合:

CREATE OR REPLACE  PACKAGE MY_SCHEMA.MY_PKG AS
PROCEDURE MY_PROC;
FUNCTION MY_FUNC RETURN VARCHAR2;
PROCEDURE MY_PROC2;
PROCEDURE "my_proc2";
PROCEDURE MY_PROC3(P1 IN VARCHAR);
PROCEDURE MY_PROC3(P2 IN NUMBER);
END MY_PKG;

次のエンドポイントが生成されます。

http://localhost:8080/ords/my_schema/my_pkg/MY_PROC
http://localhost:8080/ords/my_schema/my_pkg/MY_FUNC

注意:
プロシージャmy_proc2のエンドポイントは、名前を小文字に変換すると一意にならないため生成されません。プロシージャmy_proc3のエンドポイントは、オーバーロードしているため生成されません。

3.2.5.3.4 リソース入力ペイロード

入力ペイロードは、REST標準に従った値を持つJSONドキュメントです。

ペイロードは、次のコード・スニペットに示すように、INまたはIN OUTの各パラメータに対する名前/値ペアを含んでいる必要があります。

{
"p1": "abc",
"p2": 123,
"p3": null
}

注意:
INまたはIN OUTパラメータがない場合、次のコード・スニペットに示すように、空のJSONボディが必要です。

{

}

ORDSは、データベース・カタログ・メタデータを使用してJSONペイロードをOracleデータベース・タイプにアンマーシャリングし、そこではJDBCを介してデータベースに渡される準備ができています。

3.2.5.3.5 リソース・ペイロード・レスポンス

PL/SQLオブジェクトが正常に実行されると、JSONボディが戻されます。

戻されるJSONボディは、すべてのOUTおよびIN OUT出力パラメータ値を含んでいます。ORDSは、次のコード・スニペットで示すように、データベース・カタログ・メタデータを使用して結果の実行をJSON内にマーシャリングします。

{
"p3" : "abc123",
"p4" : 1
}

OUTまたはIN OUTパラメータがない場合、次のコード・スニペットに示すように、空のJSONボディが戻されます。

{

}

3.2.5.3.6 ファンクションの戻り値

ファンクションの戻り値には関連した名前がありません。

ファンクションの戻り値に関連した名前がないため、次のコード・スニペットに示すように名前"~ret"が使用されます。

{
"~ret" : "abc123"
}

3.2.6 SQLおよびPL/SQLを使用したRESTful Servicesの手動作成

この項では、SQLおよびPL/SQLを使用して手動でRESTful Servicesを作成する方法を説明し、JSONドキュメントを使用してRESTリクエストのボディにあるストアド・プロシージャにパラメータを渡す方法を表示します。

この項には次のトピックが含まれます:

- Oracle REST Data Servicesのパラメータ引き渡しメカニズムについて

- SQL/JSONデータベース・ファンクションのORDSとの使用

3.2.6.1 Oracle REST Data Servicesのパラメータ引き渡しメカニズムについて

この項では、Oracle REST Data Servicesがサポートしている、REST HTTPを使用して開発者作成のハンドラにパラメータを引き渡す主要なメカニズムについて説明します。

- JSONを使用したパラメータの引き渡し
RESTリクエスト(たとえばPOSTまたはPUTメソッド)のボディでJSONを使用できます。ここで、各パラメータはJSONの名前/値ペアです。

- ルート・パターンを使用したパラメータの引き渡し
URIの必須パラメータに対して、および他の特別な事例でルート・パターンを使用して、ボディを持たないRESTリクエスト(GETメソッドなど)のパラメータを指定できます。

- オプションのパラメータのための問合せ文字列の使用
URIのオプションのパラメータに対して、および他の特別な事例で問合せ文字列を使用して、ボディを持たないRESTリクエスト(GETメソッドなど)のパラメータを指定できます。

パラメータ引き渡しタスク実行前に完了しておく必要がある前提条件セットアップ・タスク

この前提条件セットアップ情報は、「RESTfulサービスのスタート・ガイド」の項の手順1および2を完了していることを前提にしています。そこでは、ordstestスキーマおよびempデータベース・テーブルをREST対応にし(手順1)、SQL問合せからRESTfulサービスを作成、テストしました(手順2)。これら2つの手順を、パラメータ引き渡しタスクを実行する前に完了する必要があります(次以降のサブセクションを参照)。

関連トピック

- RESTfulサービスのスタート・ガイド

3.2.6.1.1 JSONを使用したパラメータの引き渡し

この項では、RESTリクエスト(たとえばPOSTまたはPUTメソッド)のボディでJSONドキュメントを使用してストアド・プロシージャにパラメータを渡す方法を示します(各パラメータは名前/値ペア)。この操作はレコード上で更新を実行し、その結果、レコードに対する変更がOUTパラメータとして戻されます。

次の手順を実行します。

1. 注意:

次のストアド・プロシージャは、emp表内の既存のレコード上で次の一部または全部を変更することによって更新を実行して従業員を昇格します: ジョブ、給与、委任、部門番号および管理者。ストアド・プロシージャは、OUTパラメータとして給与の変更を戻します。

create or replace procedure promote ( l_empno IN number,  l_job IN varchar2,
l_mgr IN number, l_sal IN number,  l_comm IN number,  l_deptno IN number,
l_salarychange OUT number)
is
oldsalary   number;
begin
select nvl(e.sal, 0)into oldsalary FROM emp e
where e.empno = l_empno;
update emp e set
e.job = nvl(l_job, e.job),
e.mgr = nvl(l_mgr, e.mgr),
e.sal = nvl(l_sal, e.sal),
e.comm = nvl(l_comm, e.comm),
e.deptno = nvl(l_deptno, e.deptno)
where e.empno = l_empno;
l_salarychange := nvl(l_sal, oldsalary) - oldsalary;
end;

特権ordstestユーザーとしてordstestスキーマに接続し、promoteストアド・プロシージャを作成します。

2. 次の手順を実行してempリソース上にPUTリクエストのハンドラをセットアップし、JSONドキュメントのPUTメソッドのボディのパラメータをpromoteストアド・プロシージャに引き渡します。

a. Oracle SQL Developerを使用して、REST Developmentセクションで、empテンプレート上で右クリックし、PUTメソッドに対応する「ハンドラの追加」を選択します。

b. リソース・ハンドラを作成するダイアログで、緑色のプラス記号をクリックしてMIMEタイプapplication/jsonを追加し、「適用」をクリックしてPUTメソッドのボディにあるJSONドキュメントを送信します。

c. SQLワークシートを使用して、次の無名PL/SQLブロックを追加します: begin promote (:l_empno, :l_job, :l_mgr, :l_sal, :l_comm, :l_deptno, :l_salarychange); end;(次の図を参照)。

図3-3 無名PL/SQLブロックをPUTメソッドのハンドラとして追加する

d. 「パラメータ」タブをクリックして、「バインド・パラメータ」をl_salarychangeに、「アクセス方法」をOUTパラメータに、「ソース・タイプ」をRESPONSEに、および「データ型」をINTEGERに設定します(次の図を参照)。これは昇格手順の出力で、JSON名前/値形式を取る、給与の変更に等しい整数値です。

図3-4 PUTメソッドに引き渡すバインド・パラメータl_salarychangeの設定

e. 「詳細」タブをクリックしてコールするURLを取得します(次の図の「例」のセクションを参照)。このURLをクリップボードにコピーします。

図3-5 「詳細」タブからコールするURLを取得する

f. testモジュールを右クリックしてモジュールをアップロードします。この手順を忘れないでください。

3. RESTfulサービスをテストするには、コマンド・プロンプトで次のcURLコマンドを実行します:curl -i -H "Content-Type: application/json" -X PUT -d "{ \"l_empno\" : 7499, \"l_sal\" : 9999, \"l_job\" : \"Director\", \"l_comm\" : 300}

注意:
利用できる任意のRESTクライアントを使用してRESTfulサービスをテストすることもできます。

cURLコマンドは、次のレスポンスを戻します。

HTTP/1.1 200 OK
Content-Type: application/json Transfer-Encoding: chunked
{"salarychange":8399}

4. SQL Developer SQLワークシートで、emp表でSELECT文: SELECT * from empを実行してPUTメソッドが実行されたのを確認し、続いて「DATA」タブを選択してEMP表のレコードを表示します。

図3-6 SQL問合せからの結果を表示してPUTメソッドの実行を確認する

注意:

- すべてのパラメータはオプションです。 JSONドキュメントでパラメータの名前/値ペアを省略すると、パラメータはNULLに設定されます。

- 名前/値ペアは、JSONドキュメント内に、任意の順序で並べることができます。 JSONを使用すると、JSONドキュメントでこの点に多くの柔軟性を得られます。

- 1レベルのJSONのみサポートされます。JSONオブジェクトまたは配列をネストすることはできません。

3.2.6.1.2 ルート・パターンを使用したパラメータの引き渡し

この項では、URIでルート・パターンを使用してRESTリクエストにパラメータを指定する方法を説明します(ボディを持たないGETメソッドなど)。

まず、多くのバインド変数を持つemp表で、問合せに対してGETメソッド・ハンドラを作成します。この手順では、ルート・パターンを使用して、必要なパラメータ値を指定します。

ルート・パターンを使用していくつかの必要なパラメータ値を持つGETメソッドを送信するには、次の手順を実行します。

1. SQL Developerで、テスト・モジュールを右クリックし、「テンプレートの追加」を選択してempをコールする新しいテンプレートを作成します。ただし、この場合、テンプレート定義に、メソッドのボディでなくURIに含まれる、パラメータまたはバインド変数のルート・パターンが含まれます。必要なパラメータを定義するには、jobおよびdeptnoパラメータの前に/:を指定することによってルート・パターンを使用します。たとえば、URIパターンの場合、emp/:job/:deptnoと入力します(次の図参照)。

図3-7 いくつかのパラメータまたはバインド変数のルート・パターンを含むテンプレート定義の作成

2. 「次」をクリックして「RESTデータ・サービス — 手順2/3」に移動し、「次」をクリックして「RESTデータ・サービス — 手順3/3」に移動し,次に「終了」をクリックしてテンプレートを完成します。

3. emp/:job/:deptnoテンプレートを右クリックし、GETメソッドに対して「ハンドラの追加」を選択します。

4. GETメソッド上で右クリックしてハンドラを開きます。

5. SQLワークシートに次の問合せを追加します: select * from emp e where e.job = :job and e.deptno = :deptno and e.mgr = NVL (:mgr, e.mgr) and e.sal = NVL (:sal, e.sal); (次の図も参照)。

図3-8 SQL問合せのハンドラへの追加

6. 「詳細」タブをクリックして、コールするURLを取得します。このURLをクリップボードにコピーします。

7. testモジュールを右クリックしてモジュールをアップロードします。 この手順を忘れないでください。

8. RESTエンドポイントをテストします。Webブラウザで、次の図に示すように、URL http://localhost:8080/ords/ordstest/test/emp/SALESMAN/30を入力します。

図3-9 ルート・パターンを使用してGETメソッドといくつかの必須パラメータ値を送信した結果をブラウザを使用して表示する

問合せは、Ward、MartinおよびTurnerという名のセールスマンに対応する3件のレコードを戻します。

関連項目:

ルート・パターンの詳細は、ORDSディストリビューションに含まれるドキュメントdocs/javadoc/plugin-api/route-patterns.htmlと、ドキュメント「Oracle REST Data Servicesのルート・パターン」を参照してください。

3.2.6.1.3 オプションのパラメータのための問合せ文字列の使用

この項では、URIでルート・パターンを使用してRESTリクエストにパラメータを指定する方法を説明します(ボディを持たないGETメソッドなど)。任意の問合せにおいて、その他のオプションのバインド変数に対して問合せ文字列を使用できます。

問合せ文字列を使用する構文は次のとおりです: ?parm1=value1&parm2=value2 … &parmN=valueN。

たとえば、問合せhttp://localhost:8080/ords/ordstest/test/emp/SALESMAN/30をさらにフィルタする場合、問合せ文字列を使用していくつかのパラメータ名/値ペアとともにGETメソッドを送信するには、mgr(管理者)が7698でsal(給与)が1500である従業員を、問合せ文字列?mgr=7698&sal=1500をURLに付加することで選択します: http://localhost:8080/ords/ordstest/test/emp/SALESMAN/30?mgr=7698&sal=1500。

エンドポイントをテストするには、WebブラウザにURL「http://localhost:8080/ords/ordstest/test/emp/SALESMAN/30?mgr=7698&sal=1500」を入力します(次の図を参照)。

図3-10 問合せ文字列を使用してGETメソッドとともにいくつかのパラメータ名/値ペアを送信した結果をブラウザを使用して表示する

この問合せは、名前がTurner、部門が30、給与が1500、管理者が7698であるセールスマンに対応する1件のレコードを戻します。

次の点に注意してください:

- パラメータ値をURLエンコードするのは有効です。必ずしも必要ではないこともありますが、行っても安全です。これにより、インターネットにより何かが改変されること、たとえば、特殊文字が障害を引き起こす可能性がある他の文字に変換されることを防げます。RESTクライアントにこの機能があることもありますし、フレーズurlエンコーダでインターネットを検索することでその機能があるツールを見つけることもできます。

- URIでパラメータ・リストの末尾に決してバックスラッシュを入れないでください。そうしないと、404 Not Foundエラーが表示される場合があります。

関連項目:

JSONを使用してパラメータ値を渡す経験をさらに充実させるには、ORDSチュートリアル(OBE)の演習4およびデータベース・アプリケーション開発仮想イメージを参照します。

3.2.6.2 SQL/JSONデータベース・ファンクションのORDSとの使用

この項では、Oracle Database 12c リリース2 (12.2)で利用できるSQL/JSONデータベース・ファンクションを使用して、ネストされたJSONオブジェクトと階層関係表を互いにマップするために説明します。

この項には次のトピックが含まれます:

- ネストされたJSONオブジェクトの関係表への挿入

- 階層リレーショナル・データからのネストされたJSONオブジェクトの生成

3.2.6.2.1 ネストされたJSONオブジェクトの関係表への挿入

この項では、ネスト配列を持つJSONオブジェクトを複数の階層的な関係表に挿入する方法を説明します。

この機能を実装するために使用される2つの主要なテクノロジは次のとおりです。

- ORDSが提供してPOSTおよび他のRESTコールのボディにあるJSONおよび他のコンテンツをPL/SQL RESTハンドラに配信する:bodyバインド変数

- Oracle Database 12cリリース2 (12.2)で提供されるJSON_TABLEおよびその他のSQL/JSON演算子

関係表にデータを挿入するためのこれらのテクノロジを使用する利点のいくつかを次に示します。

- 機能を実装するための要件が最小限です。たとえば、JSONパーサー・ソフトウェアのインストールは不要です

- JSONからの関係マッピングが単純な場合、書くのも読むのも簡単な、単純な宣言型コードを使用できます

- より複雑なマッピングを処理する機能は強力で洗練されています。次のものが含まれます。

- NULLSおよびブール値をマッピングするためのメカニズム

- JSONを処理するための洗練されたメカニズム。JSONは時間とともに進化します。このため、マッピング・コードは、JSONドキュメントの古いバージョンも新しいバージョンも処理できる必要があります。
たとえば、単純なスカラー値が進化して、複数のスカラーまたはネストされたスカラー値やオブジェクトの配列を含むJSONオブジェクトになる場合があります。スカラー値を戻すSQL/JSON演算子は、単純なスカラーがこれらのより精巧な構造内に埋め込まれた場合でも、引き続き機能できます。特別なメカニズム(Ordinality列と呼ばれます)を使用して、値が導出されたところから構造を決定することができます。

関連項目:

JSON_TABLEおよび他のSQL/JSON演算子、およびOrdinality列メカニズムに関する詳細は、次のページ:

- https://blogs.oracle.com/jsondb/

- https://blogs.oracle.com/jsondb/entry/the_new_sql_json_query3

3.2.6.2.1.1 :bodyバインド変数の使用法

この項では、:bodyバインド変数を使用するために役に立つヒントをいくつか提供します。

:bodyバインド変数を使用する際に役に立ついくつかのヒントを次に示します。

- :bodyバインド変数は、一度のみ、アクセスまたは参照解除できます。以降のアクセスは、NULL値を戻します。このため、2つのJSON_Table操作で使用するには、その前にローカルのL_PO変数に:bodyにバインド変数を割り当てる必要があります。

- :bodyバインド変数はBLOBデータ型であり、BLOB変数にのみ割り当てることができます。

注意:
L_POはBLOB変数なので、JSON_TABLEファンクションの式の後にFORMAT JSON句を使用する必要があります。詳細は項を参照。

:bodyバインド変数は、画像データなど、他のタイプのデータとともに使用できます。

関連項目:

- 開発チュートリアル: 画像ギャラリの作成。画像データを持つ:bodyバインド変数の使用の作業例。

- Database SQL言語リファレンス

3.2.6.2.1.2 ネストされたLineItemsがあるJSON発注書の例

この項では、ネストされたLineItemsがあるJSON発注書を取得し、PurchaseOrder表の行およびLineItem表の行に挿入する例を示します。

例3-5 ネストされたLineItemsがあるネストされたJSON発注書

{"PONumber"        : 1608,
"Requestor"      : "Alexis Bull",
"CostCenter"     : "A50",
"Address"        : {"street"  : "200 Sporting Green",
"city"    : "South San Francisco",
"state"   : "CA",
"zipCode" : 99236,
"country" : "United States of America"},
"LineItems"      : [ {"ItemNumber" : 1,
"Part"       : {"Description" : "One Magic Christmas",
"UnitPrice"   : 19.95,
"UPCCode"     : 1313109289},
"Quantity"   : 9.0},
{"ItemNumber" : 2,
"Part"       : {"Description" : "Lethal Weapon",
"UnitPrice"   : 19.95,
"UPCCode"     : 8539162892},
"Quantity"   : 5.0}]}'

3.2.6.2.1.3 PurchaseOrderおよびLineItems表の表定義

この項では、PurchaseOrderおよびLineItem表に定義を提供します。

PurchaseOrderおよびLineItems表の定義は次のとおりです。

CREATE TABLE PurchaseOrder (
PONo NUMBER (5),
Requestor VARCHAR2 (50),
CostCenter VARCHAR2 (5),
AddressStreet VARCHAR2 (50),
AddressCity VARCHAR2 (50),
AddressState VARCHAR2 (2),
AddressZip VARCHAR2 (10),
AddressCountry VARCHAR2 (50),
PRIMARY KEY (PONo));

CREATE TABLE LineItem (
PONo NUMBER (5),
ItemNumber NUMBER (10),
PartDescription VARCHAR2 (50),
PartUnitPrice NUMBER (10),
PartUPCCODE NUMBER (10),
Quantity NUMBER (10),
PRIMARY KEY (PONo,ItemNumber));

3.2.6.2.1.4 POSTリクエストのPL/SQLハンドラ・コード

この項では、POSTリクエストに対応するサンプルのPL/SQLハンドラ・コードを示します。ハンドラ・コードは、PurchaseOrder表の行およびLineItem表の行に発注書を挿入するために使用されます。

例3-6 POSTリクエストに対して使用されたPL/SQLハンドラ・コード

Declare
L_PO     BLOB;

Begin
L_PO := :body;

INSERT INTO PurchaseOrder
SELECT * FROM json_table(L_PO  FORMAT JSON, '$'
COLUMNS (
PONo            Number    PATH '$.PONumber',
Requestor       VARCHAR2  PATH '$.Requestor',
CostCenter      VARCHAR2  PATH '$.CostCenter',
AddressStreet   VARCHAR2  PATH '$.Address.street',
AddressCity     VARCHAR2  PATH '$.Address.city',
AddressState    VARCHAR2  PATH '$.Address.state',
AddressZip      VARCHAR2  PATH '$.Address.zipCode',
AddressCountry  VARCHAR2  PATH '$.Address.country'));

INSERT INTO LineItem
SELECT * FROM json_table(L_PO  FORMAT JSON, '$'
COLUMNS (
PONo  Number PATH '$.PONumber',
NESTED             PATH '$.LineItems[*]'
COLUMNS (
ItemNumber        Number   PATH '$.ItemNumber',
PartDescription   VARCHAR2   PATH '$.Part.Description',
PartUnitPrice     Number   PATH '$.Part.UnitPrice',
PartUPCCode       Number   PATH '$.Part.UPCCode',
Quantity          Number   PATH '$.Quantity')));
commit;
end;

3.2.6.2.1.5 REST APIサービスの作成によるハンドラの起動

この項では、REST APIサービスを作成してハンドラを起動する方法を説明します。Oracle REST Data Servicesを使用します。

REST APIサービスをセットアップするために、RESTコールの対象となるリソースを識別するためにURIが定義されます。URIは、Oracle REST Data Servicesが特定のハンドラにREST HTTPコールをルーティングするためにも使用されます。 このURIの一般的な書式は次のとおりです。

<server>:<port>/ords/<schema>/<module>/<template>/<parameters>

ここで、<server>:<port>は、Oracle REST Data Serviceがインストールされた場所です。テスト目的で、URIのmoduleおよびtemplateの代わりに、それぞれdemoおよびtestを使用することができます。モジュールは、REST APIの対象となるリソースを定義する関連のテンプレートをまとめてグループ化するために使用されます。

REST APIサービスを作成するには、次のいずれかの方法を使用します。

- ORDS PL/SQL APIを使用して、POST挿入のためにRESTサービスとハンドラを定義します。次に、PurchaseOrderおよびLineItem表を含むデータベース・サーバー上のjsontableスキーマに接続します。

注意:
JSON_TABLEおよび他のSQL/JSON演算子は、エスケープする必要があるため、一重引用符を使用します。たとえば、すべての一重引用符(’)を二重引用符(“)に置き換える必要があります。

- SQL Developerで、ORDSの「REST開発」ペインを使用してRESTサービスを定義します。

3.2.6.2.1.6 ORDS PL/SQL APIを使用したREST Serviceおよびハンドラの定義

この項では、Oracle REST Data Services (ORDS) PL/SQL APIを使用して、POST挿入のためにREST Serviceとハンドラを定義する方法を示します。

代替として、SQL DeveloperでORDSの「REST開発」ペインを使用してモジュール、テンプレートおよびハンドラを作成できます。

BEGIN
ORDS.ENABLE_SCHEMA(
p_enabled             => TRUE,
p_schema              => 'ORDSTEST',
p_url_mapping_type    => 'BASE_PATH',
p_url_mapping_pattern => 'ordstest',
p_auto_rest_auth      => FALSE);

ORDS.DEFINE_MODULE(
p_module_name    => 'demo',
p_base_path      => '/demo/',
p_items_per_page =>  25,
p_status         => 'PUBLISHED',
p_comments       => NULL);
ORDS.DEFINE_TEMPLATE(
p_module_name    => 'demo',
p_pattern        => 'test',
p_priority       => 0,
p_etag_type      => 'HASH',
p_etag_query     => NULL,
p_comments       => NULL);
ORDS.DEFINE_HANDLER(
p_module_name    => 'demo',
p_pattern        => 'test',
p_method         => 'POST',
p_source_type    => 'plsql/block',
p_items_per_page =>  0,
p_mimes_allowed  => '',
p_comments       => NULL,
p_source         => '
declare
L_PO BLOB := :body;
begin

INSERT INTO PurchaseOrder
SELECT * FROM json_table(L_PO  FORMAT JSON, ''$''
COLUMNS (
PONo                  Number           PATH ''$.PONumber'',
Requestor            VARCHAR2  PATH ''$.Requestor'',
CostCenter          VARCHAR2   PATH ''$.CostCenter'',
AddressStreet      VARCHAR2  PATH ''$.Address.street'',
AddressCity         VARCHAR2  PATH ''$.Address.city'',
AddressState        VARCHAR2  PATH ''$.Address.state'',
AddressZip           VARCHAR2  PATH ''$.Address.zipCode'',
AddressCountry    VARCHAR2  PATH ''$.Address.country''));

INSERT INTO LineItem
SELECT * FROM json_table(L_PO  FORMAT JSON, ''$''
COLUMNS (
PONo  Number PATH ''$.PONumber'',
NESTED                      PATH ''$.LineItems[*]''
COLUMNS (
ItemNumber       Number      PATH ''$.ItemNumber'',
PartDescription  VARCHAR2    PATH ''$.Part.Description'',
PartUnitPrice      Number     PATH ''$.Part.UnitPrice'',
PartUPCCode     Number     PATH ''$.Part.UPCCode'',
Quantity              Number    PATH ''$.Quantity'')));

commit;
end;'
);

COMMIT;
END;

関連トピック

- Oracle REST Data Services PL/SQL APIの使用

- Oracle REST Data Servicesのパラメータ引き渡しメカニズムについて

- ORDS PL/SQLパッケージのリファレンス

3.2.6.2.2 階層リレーショナル・データからのネストされたJSONオブジェクトの生成

この項では、Oracle REST Data Servicesを使用して、階層(親/子)関係内の関係表を問い合わせ、ネストされたJSON形式でデータを戻す方法を説明します。

この機能を実装するために使用される2つの主要なテクノロジは次のとおりです。

- Oracle Database 12c リリース2 (12.2)で利用できる新しいSQL/JSONファンクション。json_objectsを使用して関係表からJSONオブジェクトを生成したり、json_arrayaggを使用してネストされた(子)関係表からネストされたJSON配列を生成したりできます。

- RESTサービス・ハンドラが次の種類のデータを戻すSQL問合せを実行できるようにするために使用されるORDSメディア・ソース・タイプ:

- データのHTTP Content-Type (この場合はapplication/json)

- json_objectによって戻されるJSONデータ

この手法を使用する利点のいくつかを次に示します。

- 機能を実装するための要件が最小限です。たとえば、JSONパーサー・ソフトウェアのインストールは不要です

- 書きやすく読みやすいシンプルな宣言型コーディングにより、JSONオブジェクトから関係表へのマッピングがシンプルになる。

- より複雑なマッピングを処理する機能は強力で洗練されています。これには、NULLSおよびブール値をマッピングするためのメカニズムが含まれます。
たとえば、Oracle DatabaseのNULLは、JSON要素の欠如、またはJSONのNULL値に変換できます。Oracle Database はブール型を格納しませんが、SQL/JSONファンクションでは、データベース内の文字列または数値の値をブーリアンのTRUEまたはFALSEの値にマッピングできます。

3.2.6.2.2.1 階層関係表からのネストされたJSONオブジェクトの生成例

この項では、ネストされたJSON発注書の形式でPurchaseOrderおよびLineItem関係表に挿入したデータを問い合わせるか、GETする方法を説明します。

例3-7 関係表上でOracle REST Data Servicesの問合せを使用してネストされたJSONオブジェクトを生成するGETハンドラ・コード

SELECT 'application/json', json_object('PONumber' VALUE po.PONo,
'Requestor' VALUE po.Requestor,
'CostCenter' VALUE po.CostCenter,
'Address' VALUE
json_object('street' VALUE po.AddressStreet,
'city' VALUE po.AddressCity,
'state' VALUE po.AddressState,
'zipCode' VALUE po.AddressZip,
'country' VALUE po.AddressCountry),
'LineItems' VALUE (select json_arrayagg(
json_object('ItemNumber' VALUE li.ItemNumber,
'Part' VALUE
json_object('Description' VALUE li.PartDescription,
'UnitPrice' VALUE li.PartUnitPrice,
'UPCCode' VALUE li.PartUPCCODE),
'Quantity' VALUE li.Quantity))
FROM LineItem li WHERE po.PONo = li.PONo))
FROM PurchaseOrder po
WHERE po.PONo = :id

3.2.6.2.2.2 テンプレートとGETハンドラを定義するためのORDS PL/SQL APIコール

この項では、作成したモジュールに新しいテンプレートを作成するためのORDS PL/SQL APIコールの例を提供します。

例3-8 demoモジュールに新しいtest/:id テンプレートおよびGETハンドラを作成するためのORDS PL/SQL APIコール

Begin
ords.define_template(
p_module_name => 'demo',
p_pattern => 'test/:id');

ords.define_handler(
p_module_name => 'demo',
p_pattern => 'test/:id',
p_method  => 'GET',
p_source_type => ords.source_type_media,
p_source => '

SELECT ''application/json'', json_object(''PONumber'' VALUE po.PONo,
''Requestor'' VALUE po.Requestor,
''CostCenter'' VALUE po.CostCenter,
''Address'' VALUE
json_object(''street'' VALUE po.AddressStreet,
''city'' VALUE po.AddressCity,
''state'' VALUE po.AddressState,
''zipCode'' VALUE po.AddressZip,
''country'' VALUE po.AddressCountry),
''LineItems'' VALUE (select json_arrayagg(
json_object(''ItemNumber'' VALUE li.ItemNumber,
''Part'' VALUE
json_object(''Description'' VALUE li.PartDescription,
''UnitPrice'' VALUE li.PartUnitPrice,
''UPCCode'' VALUE li.PartUPCCODE),
''Quantity'' VALUE li.Quantity))
FROM LineItem li WHERE po.PONo = li.PONo))
FROM PurchaseOrder po
WHERE po.PONo = :id '
);

Commit;
End;

3.2.6.2.3 RESTfulサービスのテスト

この項では、Oracleデータベースにアクセスして結果をJSON形式で取得するためにPOSTおよびGET RESTful Servicesをテストする方法を示します。

この項には次のトピックが含まれます:

- JSONオブジェクトのデータベースへの挿入

- データベースからのJSONオブジェクトの生成

3.2.6.2.3.1 JSONオブジェクトのデータベースへの挿入

この項では、JSON発注書のデータベースへの挿入をテストする方法を表示します。

URIパターン: http://<HOST>:<PORT>/ords/<SchemaAlias>/<module>/<template>

例:

メソッド: POST

URIパターン: http://localhost:8080/ords/ordstest/demo/test/

RESTfulサービスをテストするには、PONumber 1608に対する次のデータを使用して、po1.jsonのようにファイルを作成します。

{"PONumber"        : 1608,
"Requestor"       : "Alexis Bull",
"CostCenter"      : "A50",
"Address"         : {"street"  : "200 Sporting Green",
"city"    : "South San Francisco",
"state"   : "CA",
"zipCode" : 99236,
"country" : "United States of America"},
"LineItems"  : [ {"ItemNumber" : 1,
"Part"     : {"Description" : "One Magic Christmas",
"UnitPrice"   : 19.95,
"UPCCode"     : 1313109289},
"Quantity"   : 9.0},
{"ItemNumber" : 2,
"Part"       : {"Description" : "Lethal Weapon",
"UnitPrice"   : 19.95,
"UPCCode"     : 8539162892},
"Quantity"   : 5.0}]}'

その後、コマンド・プロンプトで次のcURLコマンドを実行します。

curl -i -H "Content-Type: application/json" -X POST -d @po1.json "http://localhost:8080/ords/ordstest/demo/test/"
cURLコマンドは、次のレスポンスを戻します。

HTTP/1.1 200 OK
Transfer-Encoding: chunked

3.2.6.2.3.2 データベースからのJSONオブジェクトの生成

この項では、データベースからJSONオブジェクトをフェッチするためのGETメソッドの結果を示します。

メソッド: GET

URIパターン: http://<HOST>:<PORT>/ords/<SchemaAlias>/<module>/<template>/<parameters>

例:

RESTfulサービスをテストするには、次の図に示すようにWebブラウザにURL http://localhost:8080 /ords/ordstest/demo/test/1608を入力します。

図3-11 ネストされたJSONオブジェクトの生成

3.2.7 ORDSを使用した日付の処理

ORDSを使用すると、開発者は、Oracle Database、Oracle Database 12c JSONドキュメント・ストアおよびOracle NoSQL DatabaseへのRESTインタフェースを可能な限り短時間で簡単に作成できます。Oracle Databaseで作業する場合、開発者は表に対してAutoREST機能を使用したり、より複雑な操作のためにSQLおよびPL/SQLルーチンを使用してカスタム・モジュールを作成したりできます。

文字列中の日付をエンコーディングするために、ORDSはRFC3339標準を使用します。通常、使用される日付形式はdd-mmm-yyyyです(例: 15-Jan-2017)。ORDSは、Oracle Databaseで値の挿入や更新などの操作を実行したときに、指定された形式のJSON文字列をOracle日付データ型に自動的に変換します。JSON文字列に再変換する場合、ORDSはOracle日付データ型を文字列形式に自動的に変換します。

注意:
JSONは日付データ型をサポートしませんが、Oracle Databaseは日付データ型をサポートします。

この項には次のトピックが含まれます:

- Oracle REST Data Servicesによる日時処理について

- ORDSが使用するタイムゾーンの設定について

関連項目:

時刻やタイムゾーンの処理方法などの詳細は次のページを参照してください: https://jsao.io/2016/10/working-with-dates-using-ords/

3.2.7.1 Oracle REST Data Servicesによる日時処理について

データがRESTリクエストから到着すると、Oracle REST Data Services (ORDS)がISO 8601文字列を解析し、Oracle DatabaseのTIMESTAMPデータ型に変換する場合があります。これは、AutoREST (POSTおよびPUT)でも、カスタム・モジュールのバインド変数でも発生します。TIMESTAMPがタイムゾーン関連のコンポーネントをサポートしないのを思い出してください。このため、DATETIME値が、変換処理時にORDSが使用するタイムゾーンに設定されます。

RESTリクエストへのレスポンスを作成する場合、ORDSはOracle DatabaseのDATETIME値をズールー語のISO 8601文字列に変換します。これは、AutoREST (GET)と、SQL問合せ(GET)にマッピングされるカスタム・モジュールで発生します。DATEおよびTIMESTAMPデータ型の場合、タイムゾーン関連のコンポーネントを持たないため、タイムゾーンはORDSが実行されているタイムゾーンとみなされ、ズールー語への変換はそこから行われます。

RESTに対してORDSで処理する場合(つまり、APEXでない)の一般的な推奨事項を次にいくつか示します。

- ORDSがデータベースのデータに従って適切なタイムゾーンを使用していることを確認します(たとえば、日付をデータベースに入れたいタイムゾーン)。

- NLS設定(time_zone)をストリーム中で変更しないでください。

ISO 8601文字列について説明していますが、ORDSは実際には文字列をサポートしている点に注意してください。RFC3339文字列はISO 8601文字列に準拠しているサブセットです。JSON.stringify(date)によって戻されるデフォルトの形式がサポートされます。

警告:

TIMESTAMP WITH TIME ZONEまたはTIMESTAMP WITH LOCAL TIME ZONEへの暗黙的なデータ変換に関する問題を防止するために、ORDSが使用するタイムゾーンは、セッション・タイムゾーンとの同期を維持することが重要です。デフォルトでORDSは自動的にこれを行いますが、開発者はALTER SESSION文でセッション・タイムゾーンを変更できます。

関連項目:
RFC3339

3.2.7.2 ORDSが使用するタイムゾーンの設定について

Oracle REST Data Services (ORDS)の起動時に、それにより内部で実行されるJVMは、ORDSが様々なタイムゾーン変換に使用するタイムゾーンを取得およびキャッシュします。デフォルトで、タイムゾーンはオペレーティング・システム(OS)から取得されるため、ORDSが使用するタイムゾーンを変更する簡単な方法は、OSのタイムゾーンを変更し、続いてORDSまたはそれが実行されているアプリケーション・サーバーを再起動することです。言うまでもなく、タイムゾーンを変更するための指示は、オペレーティング・システムにより異なります。

もしなんらかの理由でOSと同じタイムゾーンを使用したくない場合、Java環境変数Duser.timezoneを使用してデフォルトをオーバーライドすることができます。その変数が正確にはどのように設定されているかは、スタンドアロン・モードとJavaアプリケーション・サーバーのどちらで実行されているかにより異なります。次のトピックではいくつか例を示します。

スタンドアロン・モード

ORDSをスタンドアロン・モードで実行する場合、-jarオプションの前のコマンドライン・オプションとして指定することで、Java環境変数を設定できます。

例3-9 Duser.timezone Java環境変数のスタンドアロン・モードでの設定

次のコード例は、スタンドアロン・モードでコマンドラインからタイムゾーンを設定する方法を示しています。

$ java -Duser.timezone=America/New_York -jar ords.war standalone

Javaアプリケーション・サーバー — Tomcat 8

Javaアプリケーション・サーバー、Tomcat 8では、おそらくバージョンに関係なく、環境変数CATALINA_OPTSを使用してタイムゾーンを設定できます。これに関して推奨される方法は、CATALINA_BASE/bin/catalina.shを直接変更しないことです。その代わりに、CATALINA_BASE/binにsetenv.shという名前のスクリプトを作成することで環境変数を設定します。

例3-10 Duser.timezone Java環境変数のJavaアプリケーション・サーバーでの設定

次のコード例は、Javaアプリケーション・サーバー — Tomcat 8でタイムゾーンを設定するための、setenv.shスクリプトの内容を示しています。

CATALINA_TIMEZONE="-Duser.timezone=America/New_York"
CATALINA_OPTS="$CATALINA_OPTS $CATALINA_TIMEZONE

3.2.7.3 Application ExpressでのサンプルのRESTfulサービスの調査(チュートリアル)

最近のORDSリリース(3.0.X)をサポートするSQL Developerを使用してORDSアプリケーションを開発することを強くお薦めします。Application Expressは、RESTおよびORDSの基本概念を学ぶために役立つチュートリアルを提供します。ただし、チュートリアルは以前のORDSリリース(2.0.X)を使用しています。使用方法のチュートリアルで説明されている役に立つヒントのいくつかを次に示します。

Application Expressインスタンスがサンプルのアプリケーションおよびサンプルのデータベース・オブジェクトを自動的にワークスペースに追加するように構成されている場合、リソース・モジュールのリストにoracle.example.hrという名前のサンプルのリソース・モジュールが表示されます。リソース・モジュールがリストにない場合は、RESTfulサービス・ページの右側にあるサンプル・データのリセットタスクをクリックし、サンプルのリソース・モジュールを作成できます。

1. oracle.example.hrをクリックし、モジュール内に定義されているリソース・テンプレートとリソース・ハンドラを表示します。モジュールがどのようにhr/という値のURI接頭辞を持つのかに注意してください。これは、このモジュールが処理するすべてのURIはhr/という文字列で始まることを意味します。

2. employees/{id}という名前のリソース・テンプレートをクリックします。テンプレートがどのようにemployees/{id}という値のURIテンプレートを持つのかに注意してください。これは、hr/employees/で始まるすべてのURIがこのリソース・テンプレートで処理されることを意味します。

リソース・テンプレートでサポートされているHTTPメソッドは、リソース・テンプレートの下に表示されます。この場合は、サポートされているメソッドはGETメソッドのみです。

3. hr/employees/{id}のリソース・ハンドラの「GET」をクリックし、その構成を表示します。

このハンドラの「ソース・タイプ」は「1行問い合せる」です。これは、このリソースの問合せ結果セットの単一行へのマッピングが予想されることを意味します。このハンドラのソースは、次のとおりです。

select * from emp
where empno = :id

empno列が一意であると仮定すると、この問合せの結果は1行(または、:idの一致が見つからない場合は結果なし)になるはずです。試してみるには、「テスト」ボタンを押します。次のエラー・メッセージが表示されるはずです。

400 - 不正なリクエストです - バインドされていないパラメータがリクエスト・パスに含まれています: id

ブラウザに表示されるURIは次のようになります。

https://server:port/ords/workspace/hr/employees/{id}

説明:

- serverは、Oracle Application ExpressがデプロイされているサーバーのDNS名

- portは、サーバーがリスニング中のポート

- workspaceは、ログインしているOracle Application Expressワークスペースの名前

URIの最後の部分のhr/employees/{id}に注意してください。エラー・メッセージには有効なURIではないと表示され、問題は{id}という名前のパラメータを具体的な値に置き換えていなかったことです。修正するには、ブラウザの「戻る」ボタンを押し、「バインド変数の設定」をクリックします。

4. :idという名前のバインド変数の値として7369を入力し、「テスト」を押します。

新規のブラウザ・ウィンドウに、次のJSON(JavaScript Object Notation)が表示されます。

{
"empno":7369,
"ename":"SMITH",
"job":"CLERK",
"mgr":7902,
"hiredate":"1980-12-17T08:00:00Z",
"sal":800,
"deptno":20
}

ブラウザに表示されるこのリソースのURIにも注意してください。

https://server:port/ords/workspace/hr/employees/7369

URIテンプレートのパラメータ{id}がSQLのバインド変数:idにバインドされ(この場合は7369という具体的な値が指定され)、RESTfulサービスに実行される問合せは次のようになります。

select * from emp
where empno = 7369

この問合せの結果は、前述のJSONとしてレンダリングされます。

ヒント:

JSONを読むのは困難な場合があります。読みやすくするには、JSONを自動整形(pretty print)するブラウザ拡張機能をインストールします。たとえば、Mozilla FirefoxおよびGoogle Chromeは、どちらも拡張機能があります。

- FirefoxのJSONView

- JSON Formatter (Chrome)

ここで、存在しないリソースのURIを入力したときに何が起こるかを見てみます。

5. バインド変数の設定ページで、:idの値を7369から1111に変更し、「テスト」を押します。

前述のように新規のウィンドウがポップアップ表示され、JSONリソースの表示ではなく、次のエラー・メッセージが表示されます。

404 - Not Found

これは、このハンドラの予想どおりの動作です。:idにemp表に存在しない値がバインドされた場合、問合せの結果は生成されず、標準HTTPステータス・コード「404 - 見つかりません」が戻されます。

従業員のIDを知っていれば個別の従業員に関する情報を提供するサービスは可能ですが、有効な従業員IDのセットはどのように検出するのでしょう。

6. 「取消」を押して、リソース・モジュールの内容が表示されている前のページに戻ります。

7. employees/という名前のテンプレートをクリックします。

次の手順では、まず生成されるリソースを確認し、その後でロジックの理解に役立つ説明を見ていきます。

8. employees/の下にある「GET」ハンドラをクリックし、「テスト」をクリックします。

次のようなリソースが表示されます(まだブラウザにJSONビューア拡張機能をインストールしていないなら、出力を見やすくするため、この機会にインストールをお薦めします)。

{
"next":
{"$ref":
"https://server:port/ords/workspace/hr/employees/?page=1"},
"items": [
{
"uri":
{"$ref":
"https://server:port/ords/workspace/hr/employees/7369"},
"empno": 7369,
"ename": "SMITH"
},
{
"uri":
{"$ref":
"https://server:port/ords/workspace/hr/employees/7499"},
"empno": 7499,
"ename": "ALLEN"
},
...
{
"uri":
{"$ref":
"https://server:port/ords/workspace/hr/employees/7782"},
"empno": 7782,
"ename": "CLARK"
}
]
}

このJSONドキュメントには注目すべき点が多数あります。

- ドキュメントの最初の要素にはnextという名前が付けられ、結果の次のページを指すURIがあります。(ページ分割された結果がどのようにサポートされるかは、この後の手順で説明します)

- 第2の要素はitemsという名前で、多数の子要素が含まれています。各子要素は、問合せによって生成される結果セットの行に対応します。

- 各子要素の最初の要素はuriという名前で、各従業員の詳細情報を提供するサービスを指すURIが含まれています。URIの後半部分がどのようにURIテンプレートのemployees/{id}と一致しているかに注意してください。つまり、クライアントがこれらのURIのいずれかにアクセスすると、そのリクエストは前述のemployees/{id}のRESTfulサービスによって処理されます。

このサービスは、すべての有効な従業員のリソースをリストするリソースを生成することで、有効な従業員IDの特定という問題に対処しています。ここで理解すべき重要な点は、サービスがID値のみをリストし、クライアントがこのIDを取得して予備知識のemployees/{id}サービスと組み合せて従業員のURIを生成するのではなく、サービスが各従業員のURIをリストしている点です。

この理由は、有効な従業員のリストは大きくなる可能性があるためで、サービスがリストを小さいページに分割した場合でも、クライアントに結果の次のページを検索する場所を通知できるように、URIが使用されています。

このサービスの実装方法を確認するには、次の手順に進みます。

9. ブラウザで「戻る」ボタンを押し、「GET」ハンドラの定義に戻ります。

「ソース・タイプ」が「問合せ」であることに注意してください。これはデフォルトのソース・タイプで、リソースにゼロ以上の結果を含められることを示しています。「ページ区切りサイズ」は7で、これは結果の各ページに7つの項目があることを意味します。最終的に、ハンドラのソースは次のようになります。

select empno "$uri", empno, ename from (
select emp.*,
row_number() over (order by empno) rn
from emp
) tmp
where
rn between :row_offset and :row_count

問合せの内容:

- 1行目は、3つの列を戻したいことを示しています。最初の列は従業員IDのempnoですが、列名に$uriという別名が付けられており(後述)、2列目は再び従業員ID、3列目は従業員の名前であるenameです。

- 最初の文字が$(ドル記号)の結果セットの列は特別な扱いを受けます。それはURIに変換する必要のある列とみなされ、ハイパーリンク列と呼ばれます。このように、先頭に$を付けた列名はリソース内にハイパーリンクを生成するための方法です。
ハイパーリンク列が見つかると、列が取得されるリソースのURIが列の値の前に付加されて、新しいURIが生成されます。たとえば、このサービスのURIがhttps://server:port/ords/workspace/hr/employees/であることを思い出してください。このサービスの問合せによって生成される最初の列empnoの値が7369の場合、$uriの値はhttps://server:port/ords/workspace/hr/employees/7369となります。

- JSONにはURIのデータ型がないため、クライアントに対し、特定の値がURIを表していることを明確にするための規則が必要です。Oracle REST Data ServicesはJSON Reference提言を使用しており、その提言では$refという名前のメンバーを含み、その値が文字列である任意のJSONオブジェクトはURIであると述べられています。こうして、$uri列およびその値https://server:port/ords/workspace/hr/employees/7369は、次のJSONオブジェクトに変換されます。

{"uri":
{"$ref":
"https://server:port/ords/workspace/hr/employees/7369"
}
}

- 内部の問合せは、分析関数row_number()を使用して結果セット内の行数をカウントし、外側のWHERE句は、結果セットとして戻される行数を結果ページ内に収まるように制限します。Oracle REST Data Servicesには2つの暗黙のバインド・パラメータとして:row_offsetおよび:row_countが定義されており、そのパラメータには常に、指定されたページの結果として戻すべき、最初および最後の行のインデックスが含まれています。
たとえば、現在のページが最初のページで、ページ区切りサイズが7の場合は、:row_offsetの値は1に、:row_countの値は7になります。

ハイパーリンクおよび結果のページ分割の両方を行うための簡単な方法を確認するには、次の手順に進みます。

10. employeesfeed/リソース・テンプレートの「GET」ハンドラをクリックします。

このハンドラの「ソース・タイプ」が「フィード」で、「ページ区切りサイズ」が25であることに注意してください。

11. ページ区切りサイズを7に変更し、「変更を適用」をクリックします。

ハンドラのソースは、単に次のようになります。

select empno, ename from emp
order by deptno, ename

このように、問合せは前の例よりもはるかにシンプルですが、「テスト」をクリックすると前述の例によって生成される結果と非常によく似た結果が表示されます。

- 「フィード」ソース・タイプは「問合せ」ソース・タイプの拡張版で、$で始まる名前の別名の列が不要になり、自動的に結果セットの最初の列をハイパーリンクに変換するものとみなします。この例では、「フィード」ソース・タイプにより、empnoの列が自動的にハイパーリンクに変換されます。

- この例は、0より大きい「ページ区切りサイズ」が定義されていて、問合せが明示的にバインド・パラメータの:row_offsetまたは:row_countの参照を解除していない場合、自動的に結果セットのページを区切るOracle REST Data Servicesの機能を示しています。この例はこれら2つの条件の両方を満たすため、Oracle REST Data Servicesにより、戻す行の数とオフセットをカウントして制約する句でラップして問合せが拡張されます。自動的に結果をページに区切るこの機能は、「問合せ」ソース・タイプにも適用されることに注意してください。

関連項目:
JSONリファレンス

3.3 RESTfulサービスへのセキュアなアクセスの構成

この項では、RESTfulサービスへのセキュアなアクセスの構成方法について説明します。

RESTful APIは、それぞれのリソースが一意のURIを持つ複数のリソースから構成されています。リソースのセットは権限によって保護できます。権限はロールのセットを定義し、認証済のユーザーのうちの少なくとも1人は、権限によって保護されたリソースへのアクセス権を持っている必要があります。

特定の権限によって保護されるリソースを構成するには、権限のマッピングを作成する必要があります。権限のマッピングは、権限が保護するリソースを特定するパターンのセットを定義します。

トピック:

- 認証

- リソースにアクセスするための権限について

- リソースにアクセスするためのユーザーおよびロールについて

- ファイルベースのユーザー・リポジトリについて

- チュートリアル: リソースの保護およびアクセス

3.3.1 認証

ユーザーは、ファースト・パーティのCookieベースの認証またはサード・パーティのOAuth 2.0ベースの認証を使用して認証できます。

トピック:

- ファースト・パーティのCookieベースの認証

- サード・パーティのOAuth 2.0ベースの認証

3.3.1.1 ファースト・パーティのCookieベースの認証

ファースト・パーティは、RESTful APIの作成者です。ファースト・パーティのアプリケーションは、RESTful APIと同じWebオリジンにデプロイされたWebアプリケーションです。ファースト・パーティのアプリケーションは、Webアプリケーションが使用しているものと同じCookieセッションを使用し、RESTful APIに自身を認証し、権限を付与することが可能です。ファースト・パーティのアプリケーションにはRESTful APIへの完全なアクセス権があります。

3.3.1.2 サード・パーティのOAuth 2.0ベースの認証

サード・パーティは、RESTful APIの作成者以外のパーティです。サード・パーティのアプリケーションは、ファースト・パーティのアプリケーションと同じようには信頼できません。そのため、サード・パーティ製のアプリケーションに対し、選択的に制限付きのRESTful APIへのアクセス権を付与するための仲介手段が必要となります。

OAuth 2.0プロトコルは、RESTful APIへの条件付きおよび制限アクセスを提供するフローを定義します。簡単に言えば、サード・パーティのアプリケーションは、まずファースト・パーティに登録する必要があり、その後、ファースト・パーティ(またはファースト・パーティのRESTfulサービスのエンド・ユーザー)が、そのサード・パーティ・アプリケーションに対する期限の短いアクセス・トークンを発行することで、サード・パーティ・アプリケーションのRESTful APIへの制限付きアクセスを承認します。

関連項目:
https://tools.ietf.org/html/rfc6749

3.3.1.2.1 Two-LeggedおよびThree-LeggedのOAuthフロー

OAuth内の一部のフローはTwo-Leggedで、その他のフローはThree-Leggedで定義されています。

Two-Legged OAuthのフローには、RESTful APIを呼び出すパーティ(サード・パーティ・アプリケーション)、およびRESTful APIを提供するパーティの2つのパーティが関与します。Two-Leggedのフローは、エンド・ユーザーがRESTful APIへのアクセスを承認する必要はなく、サーバーとサーバー間の相互作用に使用されます。OAuth 2.0では、このフローはクライアント資格証明フローと呼ばれます。これは、最も典型的には、企業間取引(business to business)のシナリオで使用されます。

Three-Legged OAuthのフローには、RESTful APIを呼び出すパーティ、RESTful APIを提供するパーティ、およびRESTful APIによりアクセスを行うデータを所有または管理しているエンド・ユーザー・パーティの3つのパーティが関与します。Three-Leggedのフローは、エンド・ユーザーがRESTful APIへのアクセスを承認する必要のある、クライアントとサーバーの相互作用に使用されます。OAuth 2.0では、認可コードのフローおよび暗黙のフローはThree-Leggedフローです。これらのフローは、通常、企業と消費者間の取引(business to consumer)シナリオで使用されます。

Three-Leggedフローによって保護されたリソースでは、OAuthのクライアントがRESTful APIに登録されている場合、アクセスを必要とする保護されたリソースを安全に示すことができ、クライアントのアクセスを許可するかどうかの最終的な承認の決定権をエンド・ユーザーが持ちます。しかし、Two-Leggedフローによって保護されたリソースでは、各クライアントにどのリソースへのアクセスを認可するかをRESTful APIの所有者が承認する必要があります。

3.3.2 リソースにアクセスするための権限について

リソースにアクセスするための権限は、次のデータで構成されます。

- 名前: 権限の一意の識別子。この値は必須です。

- ラベル: OAuthを使用してユーザーが権限へのアクセスを承認するように求められるとき、エンド・ユーザーに提示される権限の名前。権限がThree-LeggedのOAuthフローで使用される場合、この値は必須です。

- 説明: 権限の目的の説明。これも、ユーザーが権限へのアクセスを承認するように求められるとき、エンド・ユーザーに提示されます。権限がThree-LeggedのOAuthフローで使用される場合、この値は必須です。

- ロール: 権限に関連付けられているロール名のセット。認証されたパーティは、権限で保護されたリソースへのアクセスを許可されるために、指定されたロールの少なくとも1つを持っている必要があります。値は必須ですが、空のセットとすることはでき、それはユーザーの認証は必要だが、権限にアクセスするための特定のロールは必要ないことを示します。

Two-LeggedのOAuthフローでは、サード・パーティのアプリケーション(OAuthの用語ではクライアントと呼ばれる)は、必要なロールの少なくとも1つを持つ必要があります。

Three-LeggedのOAuthフローでは、サード・パーティのアプリケーションからのアクセス・リクエストを承認するエンド・ユーザーは、必要なロールの少なくとも1つを持つ必要があります。

関連トピック

- Two-LeggedおよびThree-LeggedのOAuthフロー

3.3.3 リソースにアクセスするためのユーザーおよびロールについて

権限は一連のロールを列挙し、ユーザーはロールを持つことはできますが、これらのロールはどこに定義されるのでしょう。ロールを持っているユーザーについてはどうでしょう。彼らはどこに定義されているのでしょう。

権限は一連のロールを列挙し、ユーザーはロールを持つことができます。Oracle REST Data Servicesは、ユーザー管理のタスクをOracle REST Data Servicesがデプロイされているアプリケーション・サーバーに委任します。Oracle REST Data Servicesでは、アプリケーション・サーバーによって定義および管理されるユーザーを認証でき、認証されたユーザーが所属するロールおよびグループを識別できます。アプリケーション・サーバーのユーザー・リポジトリを構成することも、アプリケーション・サーバーにOracle REST Data Servicesをデプロイするパーティの責任です。

ユーザー・リポジトリを定義したり、既存のユーザー・リポジトリと統合したり、アプリケーション・サーバーはいろいろな方法で構成できるため、アプリケーション・サーバーのユーザー・リポジトリを構成する方法はこのドキュメントでは説明できません。詳細は、アプリケーション・サーバーのドキュメントを参照してください。

3.3.4 ファイルベースのユーザー・リポジトリについて

Oracle REST Data Servicesでは、簡易なファイルベースのユーザー・リポジトリ・メカニズムが提供されます。ただし、このユーザー・リポジトリはデモおよびテストのみを目的としており、本番使用はサポートされていません。

このリポジトリにユーザーを作成する方法の詳細は、次のように、ユーザー・コマンドのコマンドライン・ヘルプを参照してください。

java -jar ords.war help user

形式:

java -jar ords.war user <user> <roles>

引数:

- <user>はユーザーのユーザーIDです。

- <roles>はユーザーが持つロール(ゼロ以上)のリストです。

関連トピック

- チュートリアル: リソースの保護およびアクセス

3.3.5 チュートリアル: リソースの保護およびアクセス

このチュートリアルでは、次のOAuth機能を使用し、リソースのセットを保護するための権限を作成し、保護されたリソースにアクセスする方法を示します。

- クライアント資格証明

- 認可コード

- 暗黙のフロー

また、ファースト・パーティCookieベースの認証を使用してリソースにアクセスする方法を示します。

トピック:

- OAuthフローと各フローの用途

- このチュートリアルの前提

- このチュートリアルの手順

3.3.5.1 OAuthフローと各フローの用途

この項では、様々なOAuthフロー機能の用途を説明します。

ファースト・パーティCookieベースの認証は、RESTful APIと同じオリジンでホストされるWebアプリケーションからRESTful APIにアクセスするときに使用します。

認可コード・フローは、RESTful APIにアクセスするサード・パーティのWebアプリケーションを許可する必要があり、そのサード・パーティ・アプリケーションが、安全にクライアントの資格証明を保持できる独自のWebサーバーを持っている場合に使用します。これは、ほとんどのWebアプリケーションの標準的な状況で、サード・パーティのアプリケーションは、アプリケーションの再認証をユーザーに促すことなく、リフレッシュ・トークンを使用してユーザー・セッションの存続期間を延長でき、最高のセキュリティと最高のユーザー・エクスペリエンスを提供できます。

暗黙のフローは、サード・パーティのアプリケーションがその資格証明を安全に保持できるWebサーバーを持たない場合に使用します。このフローは、サード・パーティの単一ページ・ベースのアプリケーションで役立ちます。暗黙のフローではリフレッシュ・トークンを発行できないので、ユーザーはアプリケーションを認証するように頻繁に促されます。

ネイティブ・モバイルやデスクトップのアプリケーションは、認可コードまたは暗黙のフローを使用する必要があります。それらは、Webブラウザの画面にサイン・インおよび認可のプロンプトを表示し、認可処理の最後にWebブラウザの画面からアクセス・トークンを取得する必要があります。

クライアント資格証明フローは、RESTful APIによって管理されるデータへのアクセスを承認するようにユーザーに要求せず、サード・パーティのアプリケーションにRESTful APIへの直接アクセスを提供する必要がある場合に使用します。このサード・パーティのアプリケーションは、資格証明の機密を保持できるサーバー・ベースのアプリケーションである必要があります。クライアント資格証明はいつでもネイティブの実行可能ファイル内で検出できるため、クライアント資格証明フローはネイティブ・アプリケーションでは使用しないでください。

3.3.5.2 このチュートリアルの前提

このチュートリアルでは、次のことが前提となっています。

- Oracle REST Data Servicesは、次のURLにデプロイされています: https://example.com/ords/

- ORDSTESTという名前のデータベース・スキーマがOracle REST Data Servicesで使用するために有効になっており、そのRESTful APIが次の場所で公開されています: https://example.com/ords/ordstest/

- ORDSTESTスキーマには、次のように作成されたEMPという名前のデータベース表があります。

create table emp (
empno    number(4,0),
ename    varchar2(10 byte),
job      varchar2(9 byte),
mgr      number(4,0),
hiredate date,
sal      number(7,2),
comm     number(7,2),
deptno   number(2,0),
constraint pk_emp primary key (empno)
);

- 保護するリソースは次の場所にあります: https://example.com/ords/ordstest/examples/employees/

3.3.5.3 このチュートリアルの手順

リソースのセットを保護してアクセスするには、次の手順を実行します。

1. スキーマを有効にします。ORDSTESTスキーマに接続し、次のPL/SQL文を実行します。

begin
ords.enable_schema;
commit;
end;

2. リソースを作成します。ORDSTESTスキーマに接続し、次のPL/SQL文を実行します。

begin
ords.create_service(
p_module_name => 'examples.employees' ,
p_base_path  => '/examples/employees/',
p_pattern =>  '.' ,
p_items_per_page => 7,
p_source  =>  'select * from emp order by empno desc');
commit;
end;

このコードにより、この後の手順で権限で保護する/examples/employees/リソースが作成されます。

次のようにcURLコマンドを実行して、リソースを確認できます。

curl -i https://example.com/ords/ordstest/examples/employees/

結果は次のようになるはずです(読みやすくするために編集しています)。

Content-Type: application/json
Transfer-Encoding: chunked

{
"items":
[
{"empno":7934,"ename":"MILLER","job":"CLERK","mgr":7782,"hiredate":"1982-01-23T00:00:00Z","sal":1300,"comm":null,"deptno":10},
...
],
"hasMore":true,
"limit":7,
"offset":0,
"count":7,
"links":
[
{"rel":"self","href":"https://example.com/ords/ordstest/examples/employees/"},
{"rel":"describedby","href":"https://example.com/ords/ordstest/metadata-catalog/examples/employees/"},
{"rel":"first","href":"https://example.com/ords/ordstest/examples/employees/"},
{"rel":"next","href":"https://example.com/ords/ordstest/examples/employees/?offset=7"}
]
}

3. 権限を作成します。ORDSTESTスキーマに接続し、次のPL/SQL文を実行します。

begin
ords.create_role('HR Administrator');

ords.create_privilege(
p_name => 'example.employees',
p_role_name => 'HR Administrator',
p_label => 'Employee Data',
p_description => 'Provide access to employee HR data');
commit;
end;

このコードにより、ORDSTESTスキーマに属するロールと権限が作成されます。

- ロール名は一意である必要があり、印刷可能な文字のみを含める必要があります。

- 権限名は一意である必要があり、OAuth 2.0仕様の第3.3項のスコープ名で指定されている構文に準拠する必要があります。

- Three-Leggedの認可コードおよび暗黙のフローでこの権限を使用する場合は、ラベルおよび権限の説明を用意する必要があります。このラベルおよび説明は、Three-Leggedフローの承認フェーズでエンド・ユーザーに提示されます。

- 値は、その権限の名前と目的を識別するプレーン・テキストである必要があります。

USER_ORDS_PRIVILEGESビューの問合せで、権限が正しく作成されたことを確認できます。

select id,name from user_ords_privileges where name = 'example.employees';

結果は次のようになるはずです。

ID    NAME
----- -----------------
10260 example.employees

IDの値はデータベースによって異なりますが、NAMEの値はこのように表示されるはずです。

4. 権限をリソースと関連付けます。ORDSTESTスキーマに接続し、次のPL/SQL文を実行します。

begin
ords.create_privilege_mapping(
p_privilege_name => 'example.employees',
p_pattern => '/examples/employees/*');
commit;
end;

このコードは、example.employees権限を/examples/employees/というリソース・パターンと関連付けます。

USER_ORDS_PRIVILEGE_MAPPINGSビューの問合せで、権限が正しく作成されたことを確認できます。

select privilege_id, name, pattern from user_ords_privilege_mappings;

結果は次のようになるはずです。

PRIVILEGE_ID NAME                 PATTERN
------------ -------------------- ---------------------
10260        example.employees    /examples/employees/*

PRIVILEGE_IDの値はデータベースによって異なりますが、NAMEおよびPATTERNの値はこのように表示されるはずです。

次のcURLコマンドを実行し、/examples/employees/リソースがexample.employees権限で保護されていることを確認できます。

curl -i https://example.com/ords/ordstest/examples/employees/

結果は次のようになるはずです(読みやすくするために再フォーマットしています)。

HTTP/1.1 401 Unauthorized
Content-Type: text/html
Transfer-Encoding: chunked

<!DOCTYPE html>
<html>
...
</html>

保護されたリソースにファースト・パーティの認証を介してアクセスできることを、次の手順で確認できます。

a. エンド・ユーザーを作成します。ファイルベースのユーザー・リポジトリを使用して、examples.employees権限にアクセスするために必要なHR管理者のロールを持つテスト・ユーザーを作成します。コマンド・プロンプトで次のコマンドを実行します。

java -jar ords.war user "hr_admin" "HR Administrator"

パスワードの入力を求められたら、入力し、確認します。

b. エンド・ユーザーとしてサイン・インします。Webブラウザに次のURLを入力します。

https://example.com/ords/ordstest/examples/employees/

アクセスが拒否されたことを示すページで、サイン・インへのリンクをクリックします。

HR_ADMINユーザーのために登録した資格証明を入力し、「サインイン」をクリックします。

ページがhttps://example.com/ords/ordstest/examples/employees/にリダイレクトされること、およびJSONドキュメントが表示されることを確認します。

5. OAuthクライアントを登録します。ORDSTESTスキーマに接続し、次のPL/SQL文を実行します。

begin
oauth.create_client(
p_name => 'Client Credentials Example',
p_grant_type => 'client_credentials',
p_privilege_names => 'example.employees',
p_support_email => 'support@example.com');
commit;
end;

このコードは、クライアント資格証明のOAuthフローを使用してexamples.employees権限にアクセスする、Client Credentials Exampleという名前のクライアントを登録します。

次のSQL文を実行し、クライアントが登録されたこと、およびexamples.employees権限へのアクセスがリクエストされたことを確認できます。

select client_id,client_secret from user_ords_clients where name = 'Client Credentials Example';

結果は次のようになるはずです。

CLIENT_ID                        CLIENT_SECRET
-------------------------------- ------------------------
o_CZBVkEMN23tTB-IddQsQ..         4BJXceufbmTki-vruYNLIg..

CLIENT_IDおよびCLIENT_SECRETの値は、OAuthクライアントの機密の資格証明を表します。これらの値は、記録して安全に保管する必要があります。これは、クライアント・アプリケーションのユーザーIDおよびパスワードと考えることができます。

6. OAuthクライアントに必要な権限を付与します。ORDSTESTスキーマに接続し、次のPL/SQL文を実行します。

begin
oauth.grant_client_role(
'Client Credentials Example',
'HR Administrator');
commit;
end;

このコードは、クライアント資格証明のOAuthフローを使用してexamples.employees権限にアクセスする、Client Credentials Exampleという名前のクライアントを登録します。

次のSQL文を実行することで、クライアントにロールが付与されたことを確認できます。

select * from user_ords_client_roles where client_name = 'Client Credentials Example';

結果は次のようになるはずです。

CLIENT_ID CLIENT_NAME                 ROLE_ID   ROLE_NAME
---------- --------------------------- --------  ----------------------
10286 Client Credentials Example    10222   HR Administrator

7. クライアントの資格証明を使用してのOAuthのアクセス・トークンを取得します。
OAuthプロトコルでは、HTTPリクエストに、クライアント資格証明フローを使用して作成したアクセス・トークンを使用しなければならないと明記されています。[rfc6749-4.4.]。

リクエストは、トークン・エンドポイントと呼ばれる、周知のURLとして作成する必要があります。Oracle REST Data Servicesのトークン・エンドポイントのパスは常にoauth/tokenで、アクセスされるスキーマのルート・パスからの相対です。この例のトークン・エンドポイントは次のとおりです。

https://example.com/ords/ordstest/oauth/token

次のcURLコマンドを実行します。

curl -i --user clientId:clientSecret --data "grant_type=client_credentials" https://example.com/ords/ordstest/oauth/token

このコマンドで、clientIdをClient Credentials ExampleのUSER_ORDS_CLIENTS内のCLIENT_IDの値で置き換え、clientSecretをClient Credentials ExampleのUSER_ORDS_CLIENTS内のCLIENT_SECRETの値で置き換えます。出力は次のようになります。

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type":   "bearer",
"expires_in":3600
}

この出力では、アクセス・トークンはbearerタイプで、その値はaccess_tokenフィールドで指定されています。この値はリクエストごとに異なります。expires_inの値は、アクセス・トークンの有効期限が切れるまでの秒数を示し、この例のトークンは1時間(3600秒)で期限切れになります。

8. アクセス・トークンを使用して保護されたリソースにアクセスします。次のcURLコマンドを実行します。

curl -i -H"Authorization: Bearer accessToken" https://example.com/ords/ordstest/examples/employees/

このコマンドで、accessTokenが前の手順で示したaccess_tokenフォールドの値で置き換えられます。出力は次のようになります。

Content-Type: application/json
Transfer-Encoding: chunked

{
"items":
[
{"empno":7934,"ename":"MILLER","job":"CLERK","mgr":7782,"hiredate":"1982-01-23T00:00:00Z","sal":1300,"comm":null,"deptno":10},
...
],
"hasMore":true,
"limit":7,
"offset":0,
"count":7,
"links":
[
{"rel":"self","href":"https://example.com/ords/ordstest/examples/employees/"},
{"rel":"describedby","href":"https://example.com/ords/ordstest/metadata-catalog/examples/employees/"},
{"rel":"first","href":"https://example.com/ords/ordstest/examples/employees/"},
{"rel":"next","href":"https://example.com/ords/ordstest/examples/employees/?offset=7"}
]
}

9. 認可コード用のクライアントを登録します。ORDSTESTスキーマに接続し、次のPL/SQL文を実行します。

begin
oauth.create_client(
p_name => 'Authorization Code Example',
p_grant_type => 'authorization_code',
p_owner => 'Example Inc.',
p_description => 'Sample for demonstrating Authorization Code Flow',
p_redirect_uri => 'http://example.org/auth/code/example/',
p_support_email => 'support@example.org',
p_support_uri => 'http://example.org/support',
p_privilege_names => 'example.employees'
);
commit;
end;

このコードは、認可コードのOAuthフローを使用してexamples.employees権限にアクセスする、Authorization Code Exampleという名前のクライアントを登録します。実際のアプリケーションでは、認可コードをリダイレクトして戻すURIを用意する必要があり、有効なサポート電子メール・アドレスを指定する必要があります。この例では、架空のデータおよびサンプルのWebサービスexample.orgを使用しています。

次のSQL文を実行し、クライアントが登録されたこと、およびexamples.employees権限へのアクセスがリクエストされたことを確認できます。

select id, client_id, client_secret from user_ords_clients where name = 'Authorization Code Example';

結果は次のようになるはずです。

ID CLIENT_ID                        CLIENT_SECRET
---------- -------------------------------- --------------------------------
10060 IGHso4BRgrBC3Jwg0Vx_YQ.. GefAsWv8FJdMSB30Eg6lKw..

権限へのアクセス権を付与するには、エンド・ユーザーがアクセスを承認する必要があります。CLIENT_IDおよびCLIENT_SECRETの値は、OAuthクライアントの機密の資格証明を表します。これらの値は、記録して安全に保管する必要があります。これは、クライアント・アプリケーションのユーザーIDおよびパスワードと考えることができます。

10. 認可コードを使用してOAuthアクセス・トークンを取得します。この手順には、いくつかのサブ手順があります。(前の手順でHR_ADMINエンド・ユーザーを作成しておく必要があります。)

a. OAuth認可コードを取得します。
エンド・ユーザーには、サイン・インおよびサード・パーティ・アプリケーションへのアクセスを承認するためのプロンプトを表示する(Webページを介して)必要があります。サード・パーティ・アプリケーションは、OAuthの認可エンドポイントにユーザーを誘導することによってこのプロセスを開始します。Oracle REST Data Servicesの認可エンドポイントのパスは常にoauth/authで、アクセスされるスキーマのルート・パスからの相対です。この例のトークン・エンドポイントは次のとおりです。

https://example.com/ords/ordstest/oauth/auth

OAuth 2.0プロトコルでは、認可リクエストのURIに、問合せ文字列に特定のパラメータを含める必要があると明記されています。

response_typeパラメータには、codeの値が必要です。

client_idパラメータには、アプリケーションのクライアント識別子の値が含まれている必要があります。これは前の手順で決定したclient_idの値です。

stateパラメータには、一意の推測できない値が含まれている必要があります。この値には、2つの目的があります。それは、クライアント・アプリケーションが各認可リクエストを一意に識別する方法を提供すること(それにより、任意のアプリケーション固有の状態を値に関連付け、その値をアプリケーション自身のセッション識別子と考える)、およびクライアント・アプリケーションがクロス・サイト・リクエスト・フォージェリ(CSRF)攻撃から身を守る手段を提供することです。stateの値は、認可プロセスの最後にリダイレクトURIに戻されます。クライアントは、その値がアプリケーションによって開始された認可リクエストのものであることを確認する必要があります。クライアントが状態の値を検証できない場合は、認可リクエストが攻撃者によって開始されたものとみなし、リダイレクトを無視してください。

認可リクエストを開始するには、Webブラウザで次のURLを入力します。

https://example.com/ords/ordstest/oauth/auth?response_type=code&client_id=cliendId&state=uniqueRandomValue

このURIは、clientIdを以前に注目したCLIENT_ID列の値と置き換え、uniqueRandromValueを一意の推測できない値に置き換えます。クライアント・アプリケーションは、この値を記憶し、認可フローの最後にリダイレクトの一部として戻されるstateパラメータと照合する必要があります。

client_idが認識された場合、サイン・インのプロンプトが表示されます。エンド・ユーザーHR_ADMINの資格証明を入力して「サインイン」をクリックし、次のページで「承認」をクリックすると、クライアントが登録されたときに指定したリダイレクトURIへリダイレクトされます。リダイレクトURIは、URIの問合せ文字列部分に認可コードが含まれます。また、クライアントがフローの開始時に指定したものと同じstateパラメータの値が含まれます。リダイレクトURIは次のようになります。

http://example.org/auth/code/example/?code=D5doeTSIDgbxWiWkPl9UpA..&state=uniqueRandomValue

クライアント・アプリケーションは、stateパラメータの値を検証し、アクセス・トークンの取得に使用するcodeパラメータの値を記録する必要があります。

b. OAuthのアクセス・トークンを取得します。
サード・パーティ・アプリケーションは、認可コードを取得した後、それをアクセス・トークンと交換する必要があります。サード・パーティ・アプリケーションのサーバーは、トークン・エンドポイントにHTTPSリクエストを行う必要があります。次の例のようにcURLコマンドを使用して、このリクエストを行うサーバーを模倣できます。

curl --user clientId:clientSecret --data "grant_type=authorization_code&code=authorizationCode" https://example.com/ords/ordstest/oauth/token

このコマンドで、clientIdをAuthorization Code ExampleのUSER_ORDS_CLIENTSにあるCLIENT_IDの値と置き換え、clientSecretをAuthorization Code ExampleのUSER_ORDS_CLIENTSにあるCLIENT_SECRETの値と置き換え、authorizationCodeを前の手順で記録した認可コードの値(codeパラメータの値)と置き換えます。

結果は次のようになるはずです。

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token": "psIGSSEXSBQyib0hozNEdw..",
"token_type":   "bearer",
"expires_in":3600,
"refresh_token": "aRMg7AdWPuDvnieHucfV3g.."
}

この結果では、アクセス・トークンがaccess_tokenフィールドで指定され、リフレッシュ・トークンがrefresh_tokenフィールドで指定されています。このリフレッシュ・トークンの値は、ユーザーにサード・パーティ・アプリケーションの再認可を求めることなく、ユーザー・セッションを延長するために使用できます。

c. アクセス・トークンを使用して保護されたリソースにアクセスします。
サード・パーティ・アプリケーションでは、OAuthのアクセス・トークンを取得した後、そのアクセス・トークンを使用して保護された/examples/employees/リソースにアクセスできます。

curl -i -H"Authorization: Bearer accessToken" https://example.com/ords/ordstest/examples/employees/

このコマンドで、accessTokenが前の手順で示したaccess_tokenフォールドの値で置き換えられます。

結果は次のようになるはずです。

Content-Type: application/json
Transfer-Encoding: chunked

{
"items":
[
{"empno":7934,"ename":"MILLER","job":"CLERK","mgr":7782,"hiredate":"1982-01-23T00:00:00Z","sal":1300,"comm":null,"deptno":10},
...
],
"hasMore":true,
"limit":7,
"offset":0,
"count":7,
"links":
[
{"rel":"self","href":"https://example.com/ords/ordstest/examples/employees/"},
{"rel":"describedby","href":"https://example.com/ords/ordstest/metadata-catalog/examples/employees/"},
{"rel":"first","href":"https://example.com/ords/ordstest/examples/employees/"},
{"rel":"next","href":"https://example.com/ords/ordstest/examples/employees/?offset=7"}
]
}

d. リフレッシュ・トークンを使用してセッションを延長します。
サード・パーティ・アプリケーションは、いつでも、リフレッシュ・トークンの値を使用して新規の存続期間を持つ新規のアクセス・トークンを生成できます。これにより、サード・パーティ・アプリケーションは自由にユーザー・セッションを延長できます。このためには、サード・パーティ・アプリケーションのサーバーは、トークン・エンドポイントにHTTPSリクエストを行う必要があります。次の例のようにcURLコマンドを使用して、このリクエストを行うサーバーを模倣できます。

curl --user clientId:clientSecret --data “grant_type=refresh_token&refresh_token=refreshToken" https://example.com/ords/ordstest/oauth/token

このコマンドで、clientIdをClient Credentials ClientのUSER_ORDS_CLIENTSにあるCLIENT_IDの値と置き換え、clientSecretをClient Credentials ClientのUSER_ORDS_CLIENTSにあるCLIENT_SECRETの値と置き換え、refreshTokenを前の手順で取得したrefresh_tokenの値と置き換えます。

結果は次のようになるはずです。

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token":  "psIGSSEXSBQyib0hozNEdw..",
"token_type":    "bearer",
"refresh_token": "aRMg7AdWPuDvnieHucfV3g..",
"expires_in":    3600
}

この結果では、アクセス・トークンがaccess_tokenフィールドで指定され、新規リフレッシュ・トークンがrefresh_tokenフィールドで指定されています。このリフレッシュ・トークンの値は、ユーザーにサード・パーティ・アプリケーションの再認可を求めることなく、ユーザー・セッションを延長するために使用できます。(前のアクセス・トークンおよびリフレッシュ・トークンは無効となり、そのかわりに新規の値を使用する必要があることに注意してください。)

11. 暗黙のフローのクライアントを登録します。ORDSTESTスキーマに接続し、次のPL/SQL文を実行します。

begin
oauth.create_client(
p_name => 'Implicit Example',
p_grant_type => 'implicit',
p_owner => 'Example Inc.',
p_description => 'Sample for demonstrating Implicit Flow',
p_redirect_uri => 'http://example.org/implicit/example/',
p_support_email => 'support@example.org',
p_support_uri => 'http://example.org/support',
p_privilege_names => 'example.employees'
);
commit;
end;

このコードは、暗黙のOAuthフローを使用してexamples.employees権限にアクセスする、Implicit Exampleという名前のクライアントを登録します。実際のアプリケーションでは、認可コードをリダイレクトして戻すURIを用意する必要があり、有効なサポート電子メール・アドレスを指定する必要があります。この例では、架空のデータおよびサンプルのWebサービスexample.orgを使用しています。

次のSQL文を実行し、クライアントが登録されたこと、およびexamples.employees権限へのアクセスがリクエストされたことを確認できます。

select id, client_id, client_secret from user_ords_clients where name = 'Implicit Example';

結果は次のようになるはずです。

ID CLIENT_ID CLIENT_SECRET
---------- -------------------------------- --------------------------------
10062 7Qz--bNJpFpv8qsfNQpS1A..

権限へのアクセス権を付与するには、エンド・ユーザーがアクセスを承認する必要があります。

12. 暗黙のフローを使用してのOAuthのアクセス・トークンを取得します。(前の手順でHR_ADMINエンド・ユーザーを作成しておく必要があります。)
エンド・ユーザーには、サイン・インおよびサード・パーティ・アプリケーションへのアクセスを承認するためのプロンプトを表示する(Webページを介して)必要があります。サード・パーティ・アプリケーションは、OAuthの認可エンドポイントにユーザーを誘導することによってこのプロセスを開始します。Oracle REST Data Servicesの認可エンドポイントのパスは常にoauth/authで、アクセスされるスキーマのルート・パスからの相対です。この例のトークン・エンドポイントは次のとおりです。

https://example.com/ords/ordstest/oauth/auth

OAuth 2.0プロトコルでは、認可リクエストのURIに、問合せ文字列に特定のパラメータを含める必要があると明記されています。

response_typeパラメータには、tokenの値が必要です。

client_idパラメータには、アプリケーションのクライアント識別子の値が含まれている必要があります。これは前の手順で決定したclient_idの値です。

stateパラメータには、一意の推測できない値が含まれている必要があります。この値には、2つの目的があります。それは、クライアント・アプリケーションが各認可リクエストを一意に識別する方法を提供すること(それにより、任意のアプリケーション固有の状態を値に関連付け、その値をアプリケーション自身のセッション識別子と考える)、およびクライアント・アプリケーションがクロス・サイト・リクエスト・フォージェリ(CSRF)攻撃から身を守る手段を提供することです。stateの値は、認可プロセスの最後にリダイレクトURIに戻されます。クライアントは、その値がアプリケーションによって開始された認可リクエストのものであることを確認する必要があります。クライアントが状態の値を検証できない場合は、認可リクエストが攻撃者によって開始されたものとみなし、リダイレクトを無視してください。

認可リクエストを開始するには、Webブラウザで次のURLを入力します。

https://example.com/ords/ordstest/oauth/auth?response_type=token&client_id=cliendId&state=uniqueRandomValue

このURIは、clientIdを以前に注目したCLIENT_ID列の値と置き換え、uniqueRandromValueを一意の推測できない値に置き換えます。クライアント・アプリケーションは、この値を記憶し、認可フローの最後にリダイレクトの一部として戻されるstateパラメータと照合する必要があります。

client_idが認識された場合、サイン・インのプロンプトが表示されます。エンド・ユーザーHR_ADMINの資格証明を入力して「サインイン」をクリックし、次のページで「承認」をクリックすると、クライアントが登録されたときに指定したリダイレクトURIへリダイレクトされます。リダイレクトURIは、URIの問合せ文字列部分にアクセス・トークンが含まれます。また、クライアントがフローの開始時に指定したものと同じstateパラメータの値が含まれます。リダイレクトURIは次のようになります。

http://example.org/auth/code/example/#access_token=D5doeTSIDgbxWiWkPl9UpA..&type=bearer&expires_in=3600&state=uniqueRandomValue

クライアント・アプリケーションは、stateパラメータの値を検証し、そのアクセス・トークンの値をメモする必要があります。

13. アクセス・トークンを使用して保護されたリソースにアクセスします。次のcURLコマンドを実行します。

curl -i -H "Authorization: Bearer accessToken" https://example.com/ords/ordstest/examples/employees/

このコマンドで、accessTokenが前の手順で示したaccess_tokenフォールドの値で置き換えられます。出力は次のようになります。

Content-Type: application/json
Transfer-Encoding: chunked

{
"items":
[
{"empno":7934,"ename":"MILLER","job":"CLERK","mgr":7782,"hiredate":"1982-01-23T00:00:00Z","sal":1300,"comm":null,"deptno":10},
...
],
"hasMore":true,
"limit":7,
"offset":0,
"count":7,
"links":
[
{"rel":"self","href":"https://example.com/ords/ordstest/examples/employees/"},
{"rel":"describedby","href":"https://example.com/ords/ordstest/metadata-catalog/examples/employees/"},
{"rel":"first","href":"https://example.com/ords/ordstest/examples/employees/"},
{"rel":"next","href":"https://example.com/ords/ordstest/examples/employees/?offset=7"}
]
}

関連トピック

- Oracle REST Data Services PL/SQL APIの使用

3.4 Oracle REST Data Servicesのユーザー・ロールについて

Oracle REST Data Servicesでは、少数のユーザー・ロールが事前定義されています。

- RESTful Services - 保護されたRESTfulサービスに関連付けられたデフォルトのロールです。

- OAuth2 Client Developer - OAuth 2.0のアプリケーションを登録するユーザーはこのロールが必要です。

- SQL Developer - Oracle SQL Developerを使用してRESTfulサービスを開発するユーザーはこのロールが必要です。

- SODA Developer - これは、SODA REST APIにアクセスする必要があるデフォルト・ロールです。このロールの詳細は、『Oracle REST Data Services SODA for REST開発者ガイド』を参照してください。

- Listener Administrator - Oracle SQL Developerを介してOracle REST Data Servicesのインスタンスを管理するユーザーはこのロールが必要です。通常、java -jar ords.war userコマンドによって作成されたユーザーのみがこのロールを持ちます。
Listener AdministratorロールによりOracle REST Data Servicesのインスタンスを構成でき、その結果、そのインスタンスで処理されるすべてのApplication Expressのワークスペースに影響を与えることが可能となるため、Application ExpressユーザーはListener Administratorロールを取得することを許可されません。

トピック:

- Oracle Application ExpressのユーザーとOracle REST Data Servicesのロールについて

- ロールによるRESTfulサービスのアクセス制御

3.4.1 Oracle Application ExpressのユーザーとOracle REST Data Servicesのロールについて

デフォルトでは、Oracle Application ExpressのユーザーはOracle REST Data Servicesの事前定義済ユーザー・ロールを持っていません。これは、デフォルトでは、Application Expressのユーザーは次のことができないことを意味します。

- 保護されたRESTfulサービスの起動

- OAuth 2.0アプリケーションの登録

- Oracle SQL Developerを使用したRESTfulサービスの開発

これは、Application Expressの開発者および管理者を含め、すべてのApplication Expressユーザーに適用されます。そこで、Application Expressのユーザーを適切なユーザー・グループに追加して前述のアクションを実行できるようにするため、次の手順に従うことを覚えておくことが重要です。

トピック:

- Application ExpressユーザーにOracle REST Data Servicesロールを付与する

- Application Expressユーザーに自動的にOracle REST Data Servicesロールを付与する

3.4.1.1 Application ExpressユーザーにOracle REST Data Servicesロールを付与する

Application Expressユーザーに前述のロールのいずれかを付与するには、ユーザーをロールに対応するApplication Expressのユーザー・グループに追加する必要があります。たとえば、RESTEASY_ADMINユーザーにRESTful Servicesロールを付与するには、次の手順を実行します。

1. RESTEASY_ADMINでRESTEASYワークスペースにログインします。

2. 「管理」に移動し、「ユーザーとグループの管理」に移動します。

3. RESTEASY_ADMINユーザーの左にある編集アイコンをクリックします。

4. 「ユーザー・グループ」で、「RESTfulサービス」を選択します。

5. 「変更の適用」をクリックします。

3.4.1.2 Application Expressユーザーに自動的にOracle REST Data Servicesロールを付与する

Application Expressユーザーを適切なユーザー・グループに追加するのは、手順を見落としがちで、管理するユーザーが多い場合は反復的なタスクとなります。

この問題に対処するため、defaults.xml構成ファイルを変更し、Application Expressユーザーに自動的に事前定義済のRESTfulサービス・ロールのセットを付与するようにOracle REST Data Servicesを構成できます。

このファイルには、Oracle REST Data Servicesがロールを構成するための3つのプロパティ設定が定義されています。

- apex.security.user.roles - 開発者または管理者ではない通常のユーザーに付与するロールのカンマ区切りのリスト。

- apex.security.developer.roles - Developerアカウントの権限を持つユーザーに付与するロールのカンマ区切りのリスト。Developerは、apex.security.user.roles設定で定義されているロールも継承します。

- apex.security.administrator.roles - Administratorアカウントの権限を持つユーザーに付与するロールのカンマ区切りのリスト。Administratorは、apex.security.user.rolesおよびapex.security.developer.roles設定で定義されているロールも継承します。

たとえば、自動的に、すべてのユーザーにRESTful Services権限を付与し、すべての開発者および管理者にOAuth2 Client DeveloperおよびSQL Developerロールを付与するには、defaults.xml構成ファイルに次のように追加します。

<!-- Grant all Application Express Users the ability
to invoke protected RESTful Services -->
<entry key="apex.security.user.roles">RESTful Services</entry>
<!-- Grant Application Express Developers and Administrators the ability
to register OAuth 2.0 applications and use Oracle SQL Developer
to define RESTful Services -->
<entry key="apex.security.developer.roles">
OAuth2 Client Developer, SQL Developer</entry>

defaults.xml構成ファイルを変更したら、Oracle REST Data Servicesを再起動する必要があります。

3.4.2 ロールによるRESTfulサービスのアクセス制御

組込みのRESTful Serviceロールは、保護されたRESTfulサービスにアクセスすることを許可されたユーザーの識別に役立つデフォルトです。

しかし、特定のRESTfulサービスにアクセスできるユーザーのセットを制限するため、きめ細かいロール定義が必要になることもあります。

トピック:

- RESTfulサービスのロールの定義について

- ロールとRESTful権限の関連付け

3.4.2.1 RESTfulサービスのロールの定義について

RESTfulサービスのロールは、Application Expressのユーザー・グループです。ギャラリRESTfulサービスへのアクセスを制御するためにユーザー・グループを作成するには、次の手順に従います。 (

1. ワークスペース管理者としてRESTEASYワークスペースにログインします。

2. 「管理」に移動し、「ユーザーとグループの管理」に移動します。

3. 「グループ」タブをクリックします。

4. 「ユーザー・グループの作成」をクリックします。

5. 「名前」にGallery Usersと入力します。

6. 「グループの作成」をクリックします。

3.4.2.2 ロールとRESTful権限の関連付け

ユーザー・グループを作成したら、それをRESTful権限と関連付けることができます。ギャラリ・ユーザーのロールをexample.gallery権限に関連付けるには、次の手順に従います。

1. 「SQLワークショップ」に移動し、「RESTfulサービス」に移動します。

2. タスクのセクションで、RESTfulサービスの権限をクリックします。

3. 「ギャラリ・アクセス」をクリックします。

4. 「割当済グループ」で、ギャラリ・ユーザーを選択します。

5. 「変更の適用」をクリックします。

この変更で、ユーザーはギャラリRESTfulサービスにアクセスできるギャラリ・ユーザー・ロールを持ちます。

関連項目:
この手順では、例として「開発チュートリアル: イメージ・ギャラリの作成」のイメージ・ギャラリ・アプリケーションを使用します。

3.5 WebLogic ServerおよびGlassFishユーザー・リポジトリに対する認証

Oracle REST Data Servicesでは、WebLogic ServerおよびGlassFishによって提供されるAPIを使用し、資格証明(ユーザー名とパスワード)を検証し、ユーザーがメンバーであるグループおよびロールのセットを取得できます。

この項では、WebLogic ServerおよびGlassFishによって提供される組込みのユーザー・リポジトリでユーザーを作成し、そのユーザーに対して認証を行う機能を検証します。

このドキュメントではWebLogic ServerおよびGlassFishをLDAPリポジトリなどの多くの一般的なユーザー・リポジトリ・システムと統合する方法は説明しませんが、WebLogic ServerまたはGlassFishが正しく構成されていれば、Oracle REST Data Servicesでそのようなリポジトリに対して認証が可能です。アプリケーション・サーバーでどのようなユーザー・リポジトリがサポートされているか、およびそれらのリポジトリへのアクセスを構成する方法の詳細は、アプリケーション・サーバーのドキュメントを参照してください。

トピック:

- WebLogic Serverに対する認証

- GlassFishに対する認証

3.5.1 WebLogic Serverに対する認証

WebLogic Serverに対してのユーザー認証には、大きな手順として次のものがあります。

1. WebLogic Serverユーザーの作成

2. WebLogic Serverユーザーの検証

3.5.1.1 WebLogic Serverユーザーの作成

サンプルのWebLogic Serverユーザーを作成するには、次の手順を実行します。

1. WebLogic Serverがまだ実行されていなければ、起動します。

2. WebLogic Server管理コンソール(通常は、http://server:7001/console)にアクセスし、資格証明を入力します。

3. 左側のナビゲーション・ツリーで「セキュリティ・レルム」ノードをクリックします。

4. セキュリティ・レルムがすでに存在する場合は、次の手順に進みます。セキュリティ・レルムが存在しない場合は、次のようにして1つ作成します。

a. 「新規」をクリックします。

b. 「名前」にTest-Realmと入力し、「OK」をクリックします。

c. 「Test-Realm」をクリックします。

d. 「プロバイダ」タブをクリックします。

e. 「新規」をクリックし、次の情報を入力します。
名前: test-authenticator

タイプ: DefaultAuthenticator

f. 再起動が必要であると警告される場合は、WebLogic Serverを再起動します。

g. 「Test-Realm」をクリックします。

5. 「ユーザーとグループ」タブをクリックします。

6. 「新規」をクリックし、次の情報を入力します。

- 名前: 3rdparty_dev2

- 「パスワード」: ユーザーの希望するパスワードを入力し、確認します。

7. 「OK」をクリックします。

8. 「グループ」タブをクリックします。

9. 「新規」をクリックし、次の情報を入力します。

- 名前: OAuth2 Client Developer(大文字/小文字を区別)

10. 「OK」をクリックします。

11. 「ユーザー」タブをクリックします。

12. 「3rdparty_dev2」ユーザーをクリックします。

13. 「グループ」タブをクリックします。

14. 「選択済み」リストにOAuth2 Client Developerを追加します。

15. 「保存」をクリックします。

3rdparty_dev2という名前のユーザーが作成され、OAuth2 Client Developerという名前のグループのメンバーになります。これは、このユーザーがOAuth2 Client Developerロールを取得することを意味し、それによりOAuth 2.0アプリケーションの登録が許可されます。

では、ユーザーを正常に認証できることを検証します。

3.5.1.2 WebLogic Serverユーザーの検証

作成したWebLogic Serverユーザーが正常に認証されることを検証するには、次の手順を実行します。

1. ブラウザで、次の形式でURIにアクセスします。

https://server:port/ords/resteasy/ui/oauth2/clients/

2. 3rdparty_dev2ユーザーの資格証明を入力し、「サインイン」をクリックします。

アプリケーションが1つもリストされていない状態でOAuth 2.0クライアントの登録ページが表示されるはずです。このページが表示された場合は、WebLogic Serverのユーザー・リポジトリに対する認証が機能していることを検証できたことになります。

「ユーザーには、リソースにアクセスする権限がありません。」というメッセージとともにサインオンのプロンプトが再表示される場合は、誤りを犯しています(おそらく、グループ・リストの値のスペルミス)。

3.5.2 GlassFishに対する認証

GlassFishに対してのユーザー認証には、大きな手順として次のものがあります。

1. GlassFishユーザーの作成

2. GlassFishユーザーの検証

3.5.2.1 GlassFishユーザーの作成

サンプルのGlassFishユーザーを作成するには、次の手順を実行します。

1. GlassFishがまだ実行されていなければ、起動します。

2. GlassFishの管理コンソール(通常は、http://server:4848)にアクセスし、パスワードを設定している場合は資格証明を入力します。

3. セキュリティ構成ページに移動します。

4. 左のナビゲーション・ツリーで「構成」ノードを展開し、さらに次のノードを展開します: 「サーバー構成」、「セキュリティ」、「レルム」、および「ファイル」。

5. 「ユーザーの管理」をクリックします。

6. 「新規」をクリックし、次の情報を入力します。

- 名前: 3rdparty_dev2

- グループ・リスト: OAuth2 Client Developer(大文字/小文字を区別)

- 「パスワード」: ユーザーの希望するパスワードを入力し、確認します。

7. 「OK」をクリックします。

3rdparty_dev2という名前のユーザーが作成され、OAuth2 Client Developerという名前のグループのメンバーになります。これは、このユーザーがOAuth2 Client Developerロールを取得することを意味し、それによりOAuth 2.0アプリケーションの登録が許可されます。

では、ユーザーを正常に認証できることを検証します。

3.5.2.2 GlassFishユーザーの検証

「GlassFishユーザーの作成」で作成したWebLogic Serverユーザーが正常に認証されることを検証するには、次の手順を実行します。

1. ブラウザで、次の形式でURIにアクセスします。

https://server:port/ords/resteasy/ui/oauth2/clients/

2. 3rdparty_dev2ユーザーの資格証明を入力し、「サインイン」をクリックします。

アプリケーションが1つもリストされていない状態でOAuth 2.0クライアントの登録ページが表示されるはずです。このページが表示された場合は、WebLogic Serverのユーザー・リポジトリに対する認証が機能していることを検証できたことになります。

「ユーザーには、リソースにアクセスする権限がありません。」というメッセージとともにサインオンのプロンプトが再表示される場合は、誤りを犯しています(おそらく、グループ・リストの値のスペルミス)。

3.6 既存のグループ/ロール・モデルとの統合

他の項の例で、WebLogic ServerおよびGlassFishの組込みのユーザー・リポジトリの構成方法を説明しています。そのような状況では、ユーザー・グループの名前の付け方を完全に制御できます。ユーザーがロールとまったく同じ(大文字/小文字を区別)名前を持つグループのメンバーである場合、そのユーザーはそのロールを持っていると考えられます。

しかし、既存のユーザー・リポジトリと統合する場合は、RESTfulサービスの開発者がユーザー・リポジトリ内のユーザー・グループの命名や編成を制御できないことがあります。このような状況では、ユーザー・リポジトリに定義された既存の「物理」ユーザーグループをOracle REST Data ServicesまたはRESTfulサービス(あるいはその両方)で定義された「論理」ロールにマッピングするメカニズムが必要とされます。

このグループからロールへのマッピングは、Oracle REST Data Servicesではrole-mapping.xmlという名前の構成ファイルを構成することで実現されます。

トピック:

- role-mapping.xmlについて

3.6.1 role-mapping.xmlについて

role-mapping.xmlは、各プロパティ・キーにユーザー・グループのセットに一致するパターンを定義し、そのプロパティ値で一致したユーザー・グループにマッピングされるロールを示すJava XMLプロパティ・ファイルです。これは、defaults.xml構成ファイルと同じフォルダに配置する必要があります。ファイルは手動で作成して編集する必要があります。

次の例を考えてみます。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="webdevs">RESTful Services</entry>
</properties>

このロール・マッピングは単純で、webdevsグループのメンバーであるすべてのユーザーにRESTful Servicesロールが付与され、それはwebdevsグループのすべてのメンバーがRESTful Servicesを起動できることを意味します。

1つのマッピングで、グループに複数のロールを適用できます。次に例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="webdevs">RESTful Services, SQL Developer</entry>
</properties>

この規則は、webdevsグループにRESTful ServicesおよびSQL Developerロールの両方を付与します。

トピック:

- マッピング・ルールのパラメータ化

- パラメータの間接参照

- 間接マッピング

3.6.1.1 マッピング・ルールのパラメータ化

グループまたはロールの数が多い場合には、各グループから各ロールに明示的にマッピングするのは拡張性がよくありません。この問題に対処するため、ルールをパラメータ化できます。次の例を考えてみます。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="{prefix}.webdevs">RESTful Services</entry>
</properties>

この例では、グループ名が.webdevsで終わる任意のグループにRESTful Servicesロールがマッピングされます。たとえば、HQ.webdevsという名前のグループは、EAST.webdevsという名前のグループと同じようにこのルールに一致します。

ルールのパラメータを指定する構文はURIテンプレートに使用するものと同じで、パラメータ名が中カッコ({})で区切られます。

3.6.1.2 パラメータの間接参照

グループのルールで定義された任意のパラメータは、ロールのルールでも間接参照できます。次の例を考えてみます。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="cn={userid},ou={group},dc=MyDomain,dc=com">{group}</entry>
</properties>

この例では、LDAP識別名の組織単位コンポーネントをロールにマップします。つまり、組織単位の名前が同じ名前のロールに直接マッピングされるということです。{userid}パラメータを参照しますが、実際にはそれが使用されていないことに注意してください。{userid}は、ワイルドカードのフラグとして使用されています。

たとえば、識別名cn=jsmith,ou=Developers,dc=MyDomain,dc=comは、Developersという名前の論理ロールにマッピングされます。

3.6.1.3 間接マッピング

必要なロール・マッピングを実現するため、複数の中間的なルールの適用を必要とする場合もあります。次の例を考えてみます。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="cn={userid},ou={group},dc=example,dc=com">{group}</entry>
<entry key="{prefix},ou={group},dc=acquired,dc=com">{group}</entry>
<entry key="Developers">RESTful Services, SQL Developer</entry>
</properties>

この例では、LDAP識別名の組織単位コンポーネントをいくつかのロールにマップします。問題を複雑にしているのは、ユーザーは2つの異なる組織に属することがあり、その結果として識別名のパターンが異なるという事実です。

- example.comのユーザーは、必ず、彼らのユーザーIDを識別する単一の共通名(CN)を持ち、それに組織単位(OU)とドメイン名(DC)が続きます。たとえば、cn=jsmith,ou=Developers,dc=example,dc=comです。

- acquired.comのユーザーの共通名(CN)接頭辞は様々ですが、ここで重要なのは組織単位のフィールドです。たとえば、cn=ProductDev,cn=abell,ou=Engineering,dc=acquired,dc=comです。

- どちらの組織もソフトウェア・エンジニアをou=Developersで識別します。

ここでは、両方の組織のエンジニアをRESTful ServicesおよびSQL Developerロールにマッピングする必要があります。

- 最初のルールにより、組織example.comのエンジニアが中間のDevelopersロールにマッピングされます。

- 2つ目のルールにより、組織acquired.comのエンジニアが中間のDevelopersロールにマッピングされます。

- 最後のルールにより、中間のDevelopersロールからRESTful ServicesおよびSQL Developerロールにマッピングされます。

3.7 Oracle REST Data Services PL/SQL APIの使用

Oracle REST Data Servicesには、多くの操作でSQL Developerのグラフィカル・インタフェースのかわりに使用できるPL/SQL API (アプリケーション・プログラミング・インタフェース)があります。使用可能なサブプログラムは次のPL/SQLパッケージに含まれています。

- ORDS: 「ORDS PL/SQLパッケージのリファレンス」を参照

- OAUTH: 「OAUTH PL/SQLパッケージのリファレンス」を参照

Oracle REST Data Services PL/SQL APIを使用するには、まず次の手順を実行する必要があります。

- RESTfulサービスを開発するために使用するデータベースに、Oracle REST Data Servicesをインストールします。

- RESTアクセス用に1つ以上のデータベース・スキーマを有効化します。

トピック:

- PL/SQL APIを使用したRESTfulサービスの作成

- RESTfulサービスのテスト

関連トピック

- RESTアクセスのためのスキーマ・オブジェクトの自動的な有効化(AutoREST)

3.7.1 PL/SQL APIを使用したRESTfulサービスの作成

REST対応スキーマに接続してORDS.CREATE_SERVICEプロシージャを使用することで、RESTfulサービスを作成できます。

次の例では、簡単な「Hello-World」タイプのサービスを作成します。

begin
ords.create_service(
p_module_name => 'examples.routes' ,
p_base_path   => '/examples/routes/',
p_pattern     => 'greeting/:name',
p_source => 'select ''Hello '' || :name || '' from '' || nvl(:whom,sys_context(''USERENV'',''CURRENT_USER'')) "greeting" from dual');
commit;
end;
/

この例では、次の手順が実行されます。

- examples.routesという名前のリソース・モジュールを作成します。

- モジュールのベース・パス(URI接頭辞としても知られている)を/examples/routes/に設定します。

- モジュールに、ルート・パターンがgreeting/:nameのリソース・テンプレートを作成します。

- GETハンドラを作成し、そのソースを短い挨拶を作成するSQL問合せとして次の手順で設定します。

- GETはp_methodパラメータのデフォルト値で、そのパラメータが省略されているため、ここではそのデフォルト値が使用されます。

- COLLECTION_FEEDはp_methodパラメータのデフォルト値で、そのパラメータが省略されているため、ここではそのデフォルト値が使用されます

- whomという名前のオプションのパラメータが指定されます。

関連トピック

- ORDS.CREATE_SERVICE

3.7.2 RESTfulサービスのテスト

作成したRESTfulサービスをテストするために、まだ開始されていなければOracle REST Data Servicesを開始します。

java -jar ords.war

ブラウザでサービスのURIを入力します。次の例ではwhomパラメータが指定されていないため、デフォルトでは現行ユーザーからJoeに対して「Hello」の挨拶を表示します。

http://localhost:8080/ords/ordstest/examples/routes/greeting/Joe

この例の説明は、次のとおりです。

- Oracle REST Data Servicesは、localhostで実行されていて、ポート8080でリスニングしています。

- Oracle REST Data Servicesは、コンテキスト・パス/ordsでデプロイされています。

- RESTfulサービスは、ordstestと呼ばれるデータベース・スキーマで作成されました。

- URLにはオプションのwhomパラメータが含まれていないため、:whomバインド・パラメータはnull値にバインドされ、その結果、問合せは現行データベース・ユーザー(sys_context(''USERENV'',''CURRENT_USER''))の値をかわりに使用することになります。

ブラウザにJSON表示拡張機能がある場合、次のような結果が表示されます。

{
"items": [
{
"greeting": "Hello Joe from ORDSTEST"
}
],
"hasMore": false,
"limit": 25,
"offset": 0,
"count": 1,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/examples/routes/greeting/"
},
{
"rel": "describedby",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/examples/routes/greeting/"
},
{
"rel": "first",
"href": "http://localhost:8080/ords/ordstest/examples/routes/greeting/Joe"
}
]
}

次の例は、前述の例と類似していますが、オプションのパラメータwhomが指定されていて、挨拶がJaneからであることを示しています。

http://localhost:8080/ords/ordstest/examples/routes/greeting/Joe?whom=Jane

今回は、次のような結果になります。

{
"items": [
{
"greeting": "Hello Joe from Jane"
}
],
"hasMore": false,
"limit": 25,
"offset": 0,
"count": 1,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/ords/ordstest/examples/routes/greeting/"
},
{
"rel": "describedby",
"href": "http://localhost:8080/ords/ordstest/metadata-catalog/examples/routes/greeting/"
},
{
"rel": "first",
"href": "http://localhost:8080/ords/ordstest/examples/routes/greeting/Joe"
}
]
}

この結果では、:whomバインド・パラメータがJane値にバインドされているため、"from"の後にはORDSTESTではなくJaneが続くことに注意してください。

4 NoSQLおよびOracle REST Data Services

この章では、Oracle NoSQL Database(ここでは、単にNoSQLとも呼ぶ)のデータおよびメタデータへのHTTPベースのRESTアクセスを提供するためのOracle REST Data Servicesの使用方法を説明します。

Oracle REST Data Servicesインストールに含まれるNoSQLのサンプル・ファイルも参照してください。NoSQLストアへのアクセスを開始する方法についての簡潔なドキュメントは、Oracle REST Data Servicesをインストールした場所にあるexamples/getting-started-nosql/index.htmlファイルをダブルクリックして参照してください。

トピック:

- NoSQLおよびOracle REST Data Servicesについて

- NoSQLストアのインストールおよび登録

- Oracle REST Data Servicesで使用するNoSQLストアの追加および削除

- NoSQL RESTサービス

4.1 NoSQLおよびOracle REST Data Servicesについて

Oracle REST Data Servicesでは、NoSQLデータおよびメタデータの操作を通じて、Oracle NoSQL DatabaseにアクセスするHTTPベースのRESTサービスを提供できます。データ・アクセスは、NoSQL表へのCRUD(作成、読取り、更新、削除)操作から構成されます。

- 作成: HTTPのPOSTおよびPUTにより、行データを作成するサービスが提供されます。

- 読取り: HTTPのGETにより、一貫性および順序についてのディレクティブとともに、行データのキー、部分キーおよびフィールドの範囲参照が提供されます。

- 更新: HTTPのPUTにより、行データを更新するサービスが提供されます。

- 削除: HTTPのDELETEにより、行データを削除するサービスが提供されます。

メタデータ・アクセスはHTTPのGETで構成され、NoSQLのメタデータを読み取るサービスが提供されます。

トピック:

- テクノロジ環境

- 標準的なOracle REST Data Servicesの入力および出力

4.1.1 テクノロジ環境

NoSQLでOracle REST Data Servicesを使用するためのテクノロジ環境における重要な要素は次のものです。

- RESTサービス
Webサービスの呼出しをOracle NoSQL Databaseに向け、マーシャル・データがJSON形式で戻されます。

Oracle WebLogic Server、GlassFishまたはApache Tomcatを使用してデプロイできます。

- Oracle NoSQL Database(リリース3.2.5以上)
単一およびマスター/レプリケート・ノードにアクセスする完全なCRUD(作成、読取り、更新、削除)操作が提供されます。

Oracle NoSQL Databaseドライバ(.jarファイル)を介したアクセスが提供されます。

この環境の必須コンポーネントは次のものです。

- Java、JavaScript、C++などのクライアント

- スタンドアローン(Jetty)、Oracle WebLogic Server、GlassFish、Apache TomcatなどのWebアプリケーション・サーバー

- Oracle REST Data Services: HTTPベースのRESTサービス・プロバイダ

- NoSQLサーブレット: NoSQLデータベースのCRUD操作を提供するOracle REST Data Servicesコンポーネント

- Oracle NoSQL Database: NoSQLサーブレットのターゲットとなる分散型のマスター/レプリカのNoSQLデータベース

図4-1に、NoSQLを使用したOracle REST Data Servicesの標準的な環境の概要を示します。

図4-1 標準的な環境の概要

図4-1の詳細は次のとおりです。

- Oracle REST Data Servicesは、Webサーバー内にデプロイされます。

- クライアントは、Webサーバー内のOracle REST Data ServicesにHTTPリクエストを送信し、レスポンスを受信します。この場合、HTTPリクエストはNoSQLストアのDB1およびDB2をターゲットにしています。

- Oracle REST Data Servicesのユーザーおよびロールは、Oracle REST Data Servicesによって使用されます。

- 2つのNoSQLストア(DB1およびDB2という名前)は、Webサーバー内のOracle REST Data Servicesと通信します。

- 2のNoSQLストアの構成情報は、Oracle REST Data Servicesによって使用されます。DB1ストアはセキュアであり(NoSQLユーザー、ロールおよびSSL詳細が含まれる)、DB2ストアは非セキュアです。構成情報には、ストアがOracle REST Data Servicesに登録されていることが指定済です。

4.1.2 標準的なOracle REST Data Servicesの入力および出力

例4-1は、NoSQLデータベースから表についてのメタデータを取得するRESTサービスのリクエスト(入力)です。

例4-1 NoSQLデータベースからのメタデータの取得

http://localhost:8080/ords/sales/metadata-catalog/

例4-1の詳細は次のとおりです。

- http://localhost:8080/ordsは、localhostで実行中のWebサーバーからOracle REST Data ServicesのWebアプリケーションにポート8080でアクセスするためのURLです。

- /salesは、NoSQLデータベースの識別子です。この識別子は、NoSQL構成にマッピングされます。

- metadata-catalog/は、メタデータ・リクエストを処理するコンポーネントです。

例4-1では、レスポンスとして次のような出力が生成されます。

{
"items": [
{
"name": "complexUsers",
"links": [
{
"rel": "canonical",
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/complexUsers/",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "http://localhost:8080/ords/sales/tables/complexUsers/"
}
]
},
{
"name": "evolveUsers",
"links": [

{

"rel": "canonical",

"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/evolveUsers/",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "http://localhost:8080/ords/sales/tables/evolveUsers/"
.
.
.

4.2 NoSQLストアのインストールおよび登録

NoSQLストアのインストールおよび登録には、NoSQLのクライアントとしてのOracle REST Data Servicesインストールのホストが含まれます。そのため、NoSQLストアがセキュアである場合には、セキュリティ・プロパティ・ファイル(client.security)およびSSL情報ファイル(client.trust)をOracle REST Data Servicesのホストのネットワークにコピーする必要があります。これらのファイルは、NoSQLストアが最初に確立されたときに生成されます。NoSQLのドキュメントを参照してください。

NoSQLストアがセキュアな場合、NoSQLのユーザーでアクセスする必要があります。NoSQLでは、パスワード情報を保持するためのウォレット(エンタープライズ・エディション)およびパスワード・ファイル(コミュニティ・エディション)が提供されます。パスワード・ファイルはプレーン・テキストであり、セキュアではないため、Oracle REST Data Servicesではパスワード用に別の記憶域が提供されます。ウォレットの作成もまたNoSQLのドキュメントで説明されており、ウォレットを使用する場合は、それもOracle REST Data Servicesのホストのネットワークにコピーする必要があります。

各Oracle REST Data Servicesインストールには構成ディレクトリがあり、そこにはNoSQLストア構成用のnosqlディレクトリがあります。nosqlディレクトリには、各NoSQLストア用のディレクトリが1つずつあり、各ストア固有のディレクトリには次のファイルが含まれています。

client.security  (for Secure noSQL stores)
client.trust (for Secure NoSQL stores)
Wallet directory (Optional for NoSQL secure stores)
nosql.properties

nosql.propertiesファイルには次のものが含まれます。

oracle.dbtools.kv.store.name=<storename>
oracle.dbtools.kv.store.hosts=<comma separated set of HOSTS:PORTS>
[And optionally the following:]
oracle.dbtools.kv.store.pagelimit=<maximum number of items per page>
oracle.dbtools.kv.store.security.properties=client.security  (the name of the NoSQL client.security file)
oracle.dbtools.kv.store.requiredRoles=<list of comma separated roles>

nosql.propertiesファイルにoracle.dbtools.kv.store.requiredRolesプロパティがない場合、RESTサービスは匿名ユーザーに対して許可されており、そうでない場合は、定義されているロールのいずれかを持つユーザーにアクセス権が付与されます。

client.securityファイルにはSSLのプロパティが含まれており、次のプロパティも含まれています。

oracle.kv.auth.username=<NoSQL user used for ORDS to access the store>

client.securityファイルにはまた、次のプロパティが必要になることがあります。

- oracle.kv.auth.wallet.dir=<wallet directory>には、ウォレットを使用する場合にウォレットのディレクトリを指定します。

- oracle.dbtools.kv.store.auth.pwd=<encrypted pwd>には、パスワード・オプションを使用する場合にNoSQLユーザーのパスワードを指定します。

client.securityファイル内のすべてのパス名はフル・パスで指定する必要があることに注意してください。

後述の例は、次のソートを示しています。

- Oracle REST Data Servicesの匿名ユーザーがlocalhostのポート5000でkvstoreという名前でアクセスするストア(標準的なKVLiteストア)は次のようになります。

ords/nosql/sales
nosql.properties
oracle.dbtools.kv.store.name=kvstore
oracle.dbtools.kv.store.hosts=localhost:5000

- Oracle REST Data ServicesのSALESロールを持つユーザーがlocalhostのポート5000でkvstoreという名前でアクセスするストア(標準的なKVLiteストア)は次のようになります。

ords/nosql/sales
nosql.properties
oracle.dbtools.kv.store.name=kvstore
oracle.dbtools.kv.store.hosts=localhost:5000
oracle.dbtools.kv.store.requiredRoles=SALES

- xyz6160769のポート5000で、パスワードがウォレットに保存されているNOSQL_PUBLIC_USERユーザーがアクセスするセキュア・ストアは、次のようになります。匿名のOracle REST Data Servicesユーザーはアクセスできます。

ords/nosql/sales
nosql.properties
oracle.dbtools.kv.store.name=mystore
oracle.dbtools.kv.store.hosts=xyz6160769.example.com:5000
oracle.dbtools.kv.store.security.properties=client.security
client.security
oracle.kv.ssl.trustStore=d:/nosqlconfs/ords/nosql/salesecure/client.trust
oracle.kv.transport=ssl
oracle.kv.ssl.protocols=TLSv1.2,TLSv1.1,TLSv1
oracle.kv.ssl.hostnameVerifier=dnmatch(CN\=NoSQL)
oracle.kv.auth.username=NOSQL_PUBLIC_USER
oracle.kv.auth.wallet.dir=d:/nosqlconfs/ords/nosql/salesecure/wallet
client.trust
wallet (directory)

- xyz6160769のポート5000で、パスワードがプロパティ・ファイル(エンコード形式)に保存されているNOSQL_PUBLIC_USERユーザーがアクセスするセキュア・ストアは、次のようになります。匿名のOracle REST Data Servicesユーザーはアクセスできます。

ords/nosql/sales
nosql.properties
oracle.dbtools.kv.store.name=mystore
oracle.dbtools.kv.store.hosts=xyz6160769.example.com:5000
oracle.dbtools.kv.store.security.properties=client.security
client.security
oracle.kv.ssl.trustStore=d:/nosqlconfs/ords/nosql/salesecure/client.trust
oracle.kv.transport=ssl
oracle.kv.ssl.protocols=TLSv1.2,TLSv1.1,TLSv1
oracle.kv.ssl.hostnameVerifier=dnmatch(CN\=NoSQL)
oracle.kv.auth.username=NOSQL_PUBLIC_USER
oracle.dbtools.kv.store.auth.pwd=0571B5B831C9945D167D2510B5E6BB021B
client.trust

関連トピック

- Oracle NoSQL Database管理者ガイド

- Oracle REST Data Servicesのインストール

4.3 Oracle REST Data Servicesで使用するNoSQLストアの追加および削除

NoSQLストアを追加するには、nosqladdキーワードとともにjavaコマンドを使用します。

使用方法:

java -jar ords.war nosqladd [--secure] [--clientTrustFile] [--clientSecurityFile] [--walletDir] [--password] [--user] [--pagelimit] <storeAlias> <storeName> <hostPorts> <roles>

オプション:

- [--secure] ストアがセキュアであることを示すフラグ。

- [--clientTrustFile] client.trustファイルの場所(このファイルは、ここからNoSQLの構成領域にコピーされます)。

- [--clientSecurityFile] client.securityファイルの場所(このファイルは、将来のアップデートでここからNoSQLの構成領域にコピーされます)。

- [--walletDir] ウォレットのディレクトリ(フォルダ)の場所(このディレクトリは、ここからNoSQLの構成領域にコピーされます)。

- [--password] 接続のためのパスワード。

- [--user] 接続のためのユーザー名。

- [-- pagelimit] このストアのページごとの項目の最大数。

引数:

- <storeAlias> ストアの別名。

- <storeName> ストア名。

- <hostPorts> ホスト:ポートの値(カンマ区切りのリスト)。

- <roles> ロール(カンマ区切りのリスト)。

NoSQLストアを削除(delete)するには、nosqldelキーワードとともにjavaコマンドを使用します。

使用方法:

java -jar ords.war nosqldel <storeAlias>

引数:

- <storeAlias> ストアの別名。

4.4 NoSQL RESTサービス

NoSQLリクエストのフォーマットは、次のようになります。

host:port/ords/<nosqlalias>/<nosqlservice>

説明:

- <nosqlalias>は、NoSQLストアの別名です。

- <nosqlservice>は、呼び出されるメタデータ、データ、またはDDLサービスに適した文字列です。

トピック:

- メタデータ・サービス

- データ・サービス

- DDLサービス

- 共通パラメータ

4.4.1 メタデータ・サービス

NoSQLサービスで利用できるのはGET(メタデータ読取り)のみです。

トピック:

- メタデータ読取り(GET)

4.4.1.1 メタデータ読取り(GET)

GET(メタデータ読取り)サービスには、そのリクエストがすべての表のメタデータに対するものか、または指定した表のメタデータに対するものであるかに応じて、異なる<nosqlservice>フォーマットおよび出力があります。

- すべての表の場合: <nosqlservice> = metadata-catalog/
JSON出力は、各表のメタデータおよびデータの最初のページへのリンクがある次のような形式です。次に例を示します。

{

"items": [
{
"name": "complexUsers",
"links": [
{
"rel": "canonical",
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/complexUsers/",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "http://localhost:8080/ords/sales/tables/complexUsers/"
}
]
},
{
"name": "shardUsers",
"links": [
{
"rel": "canonical",
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/shardUsers/",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "http://localhost:8080/ords/sales/tables/shardUsers/"
}
]
},
{
"name": "simpleUsers",
"links": [
{
"rel": "canonical",
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/simpleUsers/",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/"
}
]
}
],
"hasMore": false,
"count": 3,
"limit": 25,
"offset": 0,
"links": [
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/",
"rel": "self"
}
]

}

- 表を指定する場合: <nosqlservice> = metadata-catalog/tables/<name>/(ここで、<name>は表の名前)
JSON出力は、プロパティ、キー、列の詳細、子表、リンクを持つ次のような形式です。次に例を示します。

{
"type": "TABLE",
"name": "simpleUsers",
"fullname": "simpleUsers",
"description": null,
"primarykey": [
"userID"
],
"shardkey": [
"userID"
],
"members": [
{
"name": "firstName",
"type": "STRING",
"description": null
},
{
"name": "lastName",
"type": "STRING",
"description": null
},
{
"name": "userID",
"type": "INTEGER",
"description": null
}
],
"indexes": [
{
"name": "compoundIndex",
"description": null,
"indexfields": [
"lastName",
"firstName"
]
},
{
"name": "simpleIndex",
"description": null,
"indexfields": [
"firstName"
]
}
],
"childtables": [ ],
"links": [
{               "rel": "collection",               "href": "http://localhost:8080/ords/sales/metadata-catalog/"              },
{
"rel": "canonical",
"href":        "http://localhost:8080/ords/sales/metadata-catalog/tables/simpleUsers/",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/"
}
]
}

- 表の項目を指定する場合: <nosqlservice> = metadata-catalog/tables/<name>/item(ここで、<name>は表の名前)
JSON出力は、プロパティ、キー、列の詳細、子表、リンクを持つ次のような形式です。次に例を示します。

{
"name": "simpleUsers",
"fullname": "simpleUsers",
"description": null,
"primarykey": [
"userID"
],
"members": [
{
"name": "firstName",
"type": "STRING",
"description": null
},
{
"name": "lastName",
"type": "STRING",
"description": null
},
{
"name": "userID",
"type": "INTEGER",
"description": null
}
],
"links": [
{
"rel": "collection",
"href": "http://localhost:8080/ords/sales/metadata-catalog/"
},
{
"rel": "canonical",
"href":        "http://localhost:8080/ords/sales/metadata-catalog/tables/simpleUsers/item",
"mediaType": "application/json"
}
]
}

4.4.2 データ・サービス

サービスは、NoSQLデータの読取り、書込みおよび削除が利用可能です。

トピック:

- データ読取り(GET)

- べき等書込み(PUT)

- 書込み(POST)

- 削除(DELETE)

4.4.2.1 データ読取り(GET)

GET(データ読取り)サービスには、そのリクエストが表のすべてのデータに対するものか、または表のデータのサブセットに対するものであるかに応じて、異なる<nosqlservice>フォーマットおよび出力があります。

- 表のすべてのデータの場合: <nosqlservice> = tables/<name>/
JSON出力は次の形式です。データは順不同で戻され、プロパティ・ペアの値、どこに属すのかを示すコレクションからのリンク(編集可能)が含まれています。次に例を示します。

{
"items": [
{
"$version": "rO0ABXcsAAQC5a2Fp3hHLajIZEw7k4elAAAAAAAAAQABAwAAAAEAAAABAAAAAAAEwTE.",
"firstName": "Bob",
"lastName": "Johnson",
"userID": 109,
"links": [
{
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/109",
"rel": "self"
},
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/simpleUsers/item",
"rel": "describedby"
}
]
},
{
"$version": "rO0ABXcsAAQC5a2Fp3hHLajIZEw7k4elAAAAAAAAAKYBAwAAAAEAAAABAAAAAAAEZNg.",
"firstName": "Alex",
"lastName": "Robertson",
"userID": 1,
"links": [
{
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/1",
"rel": "self"
},
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/simpleUsers/item",
"rel": "describedby"
}
]
},……..
"accepts": [
"application/json"
],
"hasMore": false,
"count": 6,
"limit": 25,
"offset": 0,
"links": [
{
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/",
"rel": "edit",
"targetSchema": "application/json"
},
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/simpleUsers/",
"rel": "describedby"
},
{
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/",
"rel": "self"
}
] }

- 表のデータのキーを指定する場合: <nosqlservice> = tables/<name>/<keys>
<name>は表の名前、<keys>はカンマ区切りの索引キー値のセットです。キー値はキー定義の順番である必要があります。キーのすべての部分が指定されない場合は、取得は部分的なキーに基づきます。完全なキーを指定した場合、出力は単一のアイテムです。

JSONの出力には、プロパティ・ペアの値、およびそれがどこに属するかを示すコレクションからのリンクが含まれています。次の例では、完全なキー(tables/shardUsers/Robertson,Alex)を指定した場合のJSON出力を示します。

{
"$version": "rO0ABXcsAAQC5a2Fp3hHLajIZEw7k4elAAAAAAAAAKYBAwAAAAEAAAABAAAAAAAEZNg.",
"firstName": "Alex",
"lastName": "Robertson",
"userID": 1,
"accepts": [
"application/json"
],
"links": [
{
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/1",
"rel": "self"
},
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/simpleUsers/item",
"rel": "describedby"
},
{
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/1",
"rel": "edit",
"targetSchema": "application/json"
},
{
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/",
"rel": "collection"
}
] }

次の例では、部分的なキー(tables/shardUsers/Robertson)を指定した場合のJSON出力を示します。

{
"items": [
{
"$version": "rO0ABXcsAAQC5a2Fp3hHLajIZEw7k4elAAAAAAAAAMIBAwAAAAEAAAABAAAAAAAEbLw.",
"firstName": "Alex",
"lastName": "Robertson",
"email": "alero@email.com",
"links": [
{
"href": "http://localhost:8080/ords/sales/tables/shardUsers/Robertson,Alex",
"rel": "self"
},
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/shardUsers/item",
"rel": "describedby"
}
]
},
{
"$version": "rO0ABXcsAAQC5a2Fp3hHLajIZEw7k4elAAAAAAAAAMQBAwAAAAEAAAABAAAAAAAEbSE.",
"firstName": "Beatrix",
"lastName": "Robertson",
"email": "bero@email.com",
"links": [
{
"href": "http://localhost:8080/ords/sales/tables/shardUsers/Robertson,Beatrix",
"rel": "self"
},
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/shardUsers/item",
"rel": "describedby"
}
]
}
],
"accepts": [
"application/json"
],
"hasMore": false,
"count": 2,
"limit": 25,
"offset": 0,
"links": [
{
"href": "http://localhost:8080/ords/sales/tables/shardUsers/",
"rel": "edit",
"targetSchema": "application/json"
},
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/shardUsers/",
"rel": "describedby"
},
{
"href": "http://localhost:8080/ords/sales/tables/shardUsers/",
"rel": "up"
},
{
"href": "http://localhost:8080/ords/sales/tables/shardUsers/Robertson",
"rel": "self"
}
] }

- 表のデータの索引およびキーを指定する場合: <nosqlservice> = tables/<name>/index/<indexname>/<keys>
<name>は表の名前、<indexname>は索引の名前、<keys>はカンマ区切りの索引キー値のセットです。キー値はキー定義の順番である必要があります。キーのすべての部分が指定されない場合は、取得は部分的なキーに基づきます。完全なキーを指定した場合、出力は単一のアイテムです。

JSONの出力には、プロパティ・ペアの値、およびそれがどこに属するかを示すコレクションからのリンク(編集可能)が含まれています。次に例を示します。

{
"items": [
{
"$version": "rO0ABXcsAAQC5a2Fp3hHLajIZEw7k4elAAAAAAAAALIBAwAAAAEAAAABAAAAAAAEaIk.",
"firstName": "Joel",
"lastName": "Robertson",
"userID": 3,
"links": [
{
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/3",
"rel": "self"
},
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/simpleUsers/item",
"rel": "describedby"
}
]
},
{
"$version": "rO0ABXcsAAQC5a2Fp3hHLajIZEw7k4elAAAAAAAAAL4BAwAAAAEAAAABAAAAAAAEa4k.",
"firstName": "Joel",
"lastName": "Jones",
"userID": 6,
"links": [
{
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/6",
"rel": "self"
},
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/simpleUsers/item",
"rel": "describedby"
}
]
}
],
"hasMore": false,
"count": 2,
"limit": 25,
"offset": 0,
"links": [
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/simpleUsers/",
"rel": "describedby"
},
{
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/index/simpleIndex/Joel",
"rel": "self"
},
{
"href": "http://localhost:8080/ords/sales/tables/simpleUsers/",
"rel": "collection"
}
] }

4.4.2.2 べき等書込み(PUT)

PUT(べき等書込み)サービスでは、その操作がアップサートであるか、存在によってPUTするのか、またはバージョンによってPUTするのかに応じて、異なる<nosqlservice>形式および出力があります。(「Put if version」は、NoSQLデータベースの最新バージョンが示されているバージョンのときのみPUT操作が成功することを意味します。これによって、クライアントが新しい値を古い値で上書きしてしまうことを防ぎます。)

- アップサート(存在すれば更新し、存在しなければ作成する)の場合: <nosqlservice> = tables/<name>/
リクエストのボディはJSON形式で、データ読取り(GET)操作によって戻される形式ですが、リンクは含まれません。次に例を示します。

{ "userID": 108, "firstName": "Bob", "lastName": "Johnson"}

- 存在すればPUTの場合: <nosqlservice> = tables/<name>/<key>
<name>は表の名前、<keys>は新規オブジェクトの主キー値です。

リクエストのボディはJSON形式で、データ読取り(GET)操作によって戻される形式ですが、リンクは含まれません。次に例を示します。

{ "userID": 108, "firstName": "Bob", "lastName": "Johnson"}

その行が存在しない場合、ステータス404(NOT_FOUND)が戻されます。

- 指定したバージョンが存在すればPUTの場合: <nosqlservice> = tables/<name>/<key>
<name>は表の名前、<keys>は新規オブジェクトの主キー値、ヘッダー・パラメータのIf-Matchはアイテムの$versionプロパティの値を指定します。指定されたバージョンと一致する場合、それが更新されます。

リクエストのボディはJSON形式で、データ読取り(GET)操作によって戻される形式ですが、リンクは含まれません。次に例を示します。

{ "userID": 108, "firstName": "Bob", "lastName": "Johnson"}
If-Match= rO0ABXcsAAQC5a2Fp3hHLajIZEw7k4elAAAAAAAAAL4BAwAAAAEAAAABAAAAAAAEa4k

その行が存在しない場合、ステータス404(NOT_FOUND)が戻されます。行が指定されたバージョンと一致しない場合は、ステータス412(PRECONDITION_FAILED)が戻されます。

関連トピック

- データ読取り(GET)

4.4.2.3 書込み(POST)

POST(存在しなければPUT)サービスの<nosqlservice>の形式: <nosqlservice> = tables/<name>/

<name>は、表の名前です。

リクエストのボディはJSON形式で、データ読取り(GET)操作によって戻される形式ですが、リンクは含まれません。次に例を示します。

{ "userID": 108, "firstName": "Bob", "lastName": "Johnson"}

行が存在している場合は、ステータス400((BAD_REQUEST)この行はすでに存在します)が戻されます。行が存在しない場合は、ステータス201(CREATED)が戻されます。

関連トピック

- データ読取り(GET)

4.4.2.4 削除(DELETE)

DELETE(削除)サービスは、オプションでバージョン識別子を指定できます。

- バージョンを指定しないDELETE: <nosqlservice> = tables/<name>/<keys>
<name>は表の名前、<keys>は削除する行の主キー値またはカンマ区切りの主キー値のセットです。キーのすべての部分が指定されない場合は、削除は部分的なキーに基づきます。

指定された行が存在する場合、ステータス204(NO_CONTENT)が戻されます。指定された行が存在しない場合は、ステータス404(NOT_FOUND)が戻されます。

- バージョンとキーにより1つのオブジェクトのみが戻される(つまり、オブジェクトを完全に指定する)場合のDELETE: <nosqlservice> = tables/<name>/<keys>
<name>は表の名前、<keys>は削除する行の主キー値またはカンマ区切りの主キー値のセット、ヘッダー・パラメータのIf-Matchはアイテムの$versionプロパティの値を指定します。指定されたバージョンと一致する場合、それが削除されます。次に例を示します。

If-Match= rO0ABXcsAAQC5a2Fp3hHLajIZEw7k4elAAAAAAAAAL4BAwAAAAEAAAABAAAAAAAEa4k

指定された行バージョンの組合せが存在している場合は、ステータス204(NO_CONTENT)が戻されます。指定された行は存在しますが、指定されたバージョンでない場合には、ステータス412(PRECONDITION_FAILED)が戻されます。指定された行が存在しない場合は、ステータス404(NOT_FOUND)が戻されます。

4.4.3 DDLサービス

NoSQLの表と索引を操作するためのサービスが利用できます。

表リクエストの場合、リクエストのボディは、『Oracle NoSQL Database表スタート・ガイド』の付録A (表データ定義言語概要)で指定されているものに対応するテキスト形式です。

トピック:

- 作成/更新(POST)

- ドロップ(POST)

- ポーリング(GET)

関連トピック

- 『Oracle NoSQL Databaseスタート・ガイド』の表

4.4.3.1 作成/更新(POST)

DDLの作成および更新操作のサービスの<nosqlservice>の形式: <nosqlservice> = ddl/

例:

http://localhost:8080/ords/sales/ddl/

リクエストのボディには、NoSQLストア上で実行されるDDLを含めます。リクエストのボディの例:

CREATE TABLE IF NOT EXISTS myUsers (firstName STRING,lastName STRING,userID INTEGER,PRIMARY KEY (userID))

CREATE INDEX IF NOT EXISTS myUser_index ON myUsers(lastName, firstName)

ALTER TABLE myUsers(ADD newcolumn STRING)

操作が成功した場合、新規リソースの場所を示すLocationヘッダー変数とともに「OK」のステータスが戻されます。たとえば(索引の作成):

Status: 200: OK
Headers:
Location: http://localhost:8080/ords/sales/metadata-catalog/tables/myUsers/index/myUser_index

操作が失敗した場合、エラー・コードが戻されます。

操作が1秒以内に完了しない場合、完了を確認するためのリクエストを送信できるように、タスクIDとともにACCEPTEDのステータスが戻されます。たとえば(索引の作成):

Status: 202: Accepted
Headers:
Location: http://localhost:8080/ords/sales/ddl/tasks/16

4.4.3.2 ドロップ(POST)

DDLのドロップ操作のサービス<nosqlservice>形式: <nosqlservice> = ddl/

例:

http://localhost:8080/ords/sales/ddl/

リクエストのボディには、NoSQLストア上で実行されるDDLを含めます。リクエストのボディの例:

DROP INDEX IF EXISTS myUser_index ON myUsers

DROP TABLE IF EXISTS myUsers

操作が成功した場合、NO_CONTENTのステータスが戻されます。

操作が失敗した場合、エラー・コードが戻されます。

操作が1秒以内に完了しない場合、完了を確認するためのリクエストを送信できるように、タスクIDとともにACCEPTEDのステータスが戻されます。例(表のドロップ):

Status: 202: Accepted
Headers:
Location: http://localhost:8080/ords/sales/ddl/tasks/17

4.4.3.3 ポーリング(GET)

ポーリング・サービスの<nosqlservice>形式: <nosqlservice> = ddl/tasks/<id>

例:

http://localhost:8080/ords/sales/ddl/tasks/17

操作が成功した場合、「OK」のステータスが戻され、Locationヘッダーが追加情報を提供できます。

LocationヘッダーがURLリクエストと同じである場合(たとえば、http://localhost:8080/ords/sales/ddl/tasks/17)、タスクはまだ進行中です。

Locationヘッダーが空白またはnullの場合、タスクは完了しており、このタスクはドロップ操作なので新規の場所はありません。

Locationヘッダーが空白ではなく、URLリクエストと同じではない場合は、これは新規または更新されたリソースの場所です。

4.4.4 共通パラメータ

複数の操作および特定の結果を得るために、いくつかのパラメータのグループを使用できます。

トピック:

- 結果をスキップおよび結果の数を制限するパラメータ

- 問合せ条件を指定するパラメータ

- 方向(順序)、一貫性および永続性保証を指定するパラメータ

4.4.4.1 結果をスキップおよび結果の数を制限するパラメータ

GET操作では、?limit={limit}&offset={offset}を使用して制限およびオフセットを指定できます。次に例を示します。

<nosqlservice> = metadata-catalog/?limit=2&offset=1

この例では、2つ目のオブジェクトから(つまり、最初の1つをスキップ)、ページ当たり2つのオブジェクトを戻します。JSON出力は次のようになります。

{
"items": [
{
"name": "evolveUsers",
"links": [
{
"rel": "canonical",
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/evolveUsers/",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "http://localhost:8080/ords/sales/tables/evolveUsers/"
}
]
},
{
"name": "shardUsers",
"links": [
{
"rel": "canonical",
"href": "http://localhost:8080/ords/sales/metadata-catalog/tables/shardUsers/",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "http://localhost:8080/ords/sales/tables/shardUsers/"
}
]
}
],
"hasMore": false,
"count": 2,
"limit": 2,
"offset": 1,
"links": [
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/",
"rel": "self"
},
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/?limit=2",
"rel": "prev"
},
{
"href": "http://localhost:8080/ords/sales/metadata-catalog/?limit=2",
"rel": "first"
}
]

4.4.4.2 問合せ条件を指定するパラメータ

フィールド範囲を使用して取得する行を制限でき、取得する順序を指定できます。このための問合せ構造は、AND条件となるペアのシンプルなリストです。次に例を示します。

?q={"firstName":{"$between":["A","C"]},"$direction":"reverse"}

特殊文字は、URLエンコーディングを使用してエスケープする必要があります。次に例を示します。

http://localhost:8080/ords/sales/tables/simpleUsers/index/simpleIndex/?q={"firstName":{"$between":%5B"A","C"%5D}}

4.4.4.3 方向(順序)、一貫性および永続性保証を指定するパラメータ

ストア内の関連するデフォルト値を上書きし、方向(順序)、一貫性の保証、および永続性を保証するための値を指定できます。

- 方向(順序)の場合は、$directionプロパティとして次の値のうちの1つを指定します。

$direction = "forward" | "reverse" | "unordered"

方向(順序)のデフォルトは"forward"です。

キーの一部または空のキーを使用した主キーの取得では、"unordered"のみが許可され、他の値は無視されます。

- 一貫性の保証は、$consistencyプロパティに次の適切な値を指定します(<LONG>は長い桁の数値を意味することに注意)。

$consistency = <Absolute> | <None> | <Replica> | <Time> | <Version>
<Absolute> = "absolute"
<None> = "none"
<Replica>  =  "replica"
<Time> = <Lag> "," <Timeout>
<Lag> = <LONG> "," <Units>
<Timeout> = <LONG> "," <Units>
<Units> = "nanoseconds" | "microseconds" | "milliseconds" | "seconds" | "minutes" | "hours" | "days"
<version> = <version_id> "," <LONG> "," <Units>
<version_id> = <version id of item as returned in GET>

次に例を示します。

http://localhost:8080/ords/sales/tables/shardUsers/Robertson,Beatrix?q={"$consistency":"time(3,seconds,2,minutes)"}

- 永続性の保証は、NoSQL-Write-Optionと呼ばれるヘッダーに次の形式の値を指定します(<LONG>は長い桁の数値を意味することに注意)。

<WriteOption> =  (<DurabilityPolicy> | <DurabilityGuarantees>)  ";" <WriteTimeOut>
<DurabilityPolicy> = "Durability" "=" <DurabilityValue>
<DurabilityValue> =  "COMMIT_NO_SYNC" | "COMMIT_SYNC" | "COMMIT_WRITE_NO_SYNC"
<DurabilityGuarantees> =  <MasterSyncPolicy> ";"  <ReplcaSyncPolicy> ";" <ReplicaAckPolicy>
<MasterSyncPolicy> = "MasterSync" "=" "NO_SYNC" | "SYNC" | "WRITE_NO_SYNC"
<ReplicaSyncPolicy> = "ReplicaSync" "=" "NO_SYNC" | "SYNC" | "WRITE_NO_SYNC"
<ReplicaAckPolicy> = "ReplicaAck" "=" "ALL" | "NONE" | "SIMPLE_MAJORITY"
<WriteTimeOut> = "TimeOut" "=" <LONG> [ ;  "Units" "=" <Units>]

たとえば、次のような値でNoSQL-Write-Optionヘッダーを作成します。

Durability = COMMIT_NO_SYNC; TimeOut = 3; Units = seconds

5 ORDS PL/SQLパッケージのリファレンス

ORDS PL/SQLパッケージには、Oracle REST Data Servicesを使用してRESTfulサービスを開発するサブプログラム(プロシージャおよび関数)が含まれています。

関連トピック

- Oracle REST Data Services PL/SQL APIの使用

5.1 ORDS.CREATE_ROLE

形式

ORDS.CREATE_ROLE(
p_role_name IN sec_roles.name%type);

説明

CREATE_ROLEは、指定された名前のOracle REST Data Servicesロールを作成します。

パラメータ

p_role_name

ロールの名前。

使用上の注意

ロールを作成した後で、Oracle REST Data Services権限にロールを関連付けることができます。

例

次の例では、ロールを作成します。

EXECUTE ORDS.CREATE_ROLE(p_role_name=>'Tickets User');

5.2 ORDS.CREATE_SERVICE

注意:

ORDS.CREATE_SERVICEは非推奨です。かわりにORDS.DEFINE_SERVICEを使用してください。

形式

ORDS.CREATE_SERVICE(
p_module_name        IN ords_modules.name%type,
p_base_path          IN ords_modules.uri_prefix%type,
p_pattern            IN ords_templates.uri_template%type,
p_method             IN ords_handlers.method%type DEFAULT 'GET',
p_source_type        IN ords_handlers.source_type%type
DEFAULT ords.source_type_collection_feed,
p_source             IN ords_handlers.source%type,
p_items_per_page     IN ords_modules.items_per_page%type DEFAULT 25,
p_status             IN ords_modules.status%type DEFAULT 'PUBLISHED',
p_etag_type          IN ords_templates.etag_type%type DEFAULT 'HASH',
p_etag_query         IN ords_templates.etag_query%type DEFAULT NULL,
p_mimes_allowed      IN ords_handlers.mimes_allowed%type DEFAULT NULL,
p_module_comments    IN ords_modules.comments%type DEFAULT NULL,
p_template_comments  IN ords_modules.comments%type DEFAULT NULL,
p_handler_comments   IN ords_modules.comments%type DEFAULT NULL);

説明

RESTfulサービスを作成します。

パラメータ

p_module_name

RESTfulサービス・モジュールの名前です。大/小文字が区別されます。一意である必要があります。

p_base_path

このRESTfulサービスにアクセスする場合に使用されるURIのベースです。例: hr/は、hr/で始まるすべてのURIがこのリソース・モジュールで処理されることを意味します。

p_pattern

リソース・テンプレートの一致パターンです。たとえば、/objects/:object/:id?のパターンは/objects/emp/101と一致(idが101のempリソースのアイテムに対するリクエストに一致)し、/objects/emp/とも一致(:idパラメータにidパラメータがオプションであることを示す? (疑問符)修飾子の注釈があるのでempリソースに対するリクエストに一致)します。

p_method

このハンドラの応答先のHTTPメソッドです。有効な値: GET (リソースの表現を取得します)、POST (新規リソースを作成またはコレクションにリソースを追加します)、PUT (既存のリソースを更新します)、DELETE (既存のリソースを削除します)。

p_source_type

このハンドラのHTTPリクエスト・メソッドです。有効な値は次のとおりです。

- source_type_collection_feed。SQL問合せを実行し、結果セットをORDS標準JSON表現に変換します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSON

- source_type_collection_item。1行分のデータをORDS標準JSON表現に返すSQL問合せを1回実行します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSON

- source_type_media。特定の書式に準拠したSQL問合せを実行し、結果セットを、表現のインターネット・メディア・タイプを識別する付随のHTTP Content-Typeヘッダーで、バイナリ表現に変換します。結果フォーマット: バイナリ

- source_type_plsql。匿名のPL/SQLブロックを実行し、OUTまたはIN/OUTパラメータをJSON表現に変換します。HTTPメソッドが、DELETE、PUT、POSTの場合のみ使用可能です。結果フォーマット: JSON

- source_type_query || source_type_csv_query。SQL問合せを実行し、結果セットを、選択したフォーマットに応じて、ORDSレガシーJavaScript Object Notation (JSON)表現またはCSV表現に変換します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSONまたはCSV

- source_type_query_one_row。1行分のデータをORDSレガシーJSON表現に返すSQL問合せを1回実行します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSON

- source_type_feed。SQL問合せを実行し、結果をJSONフィード表現に変換します。フィードの各アイテムには、リソースのサマリーと、リソースの完全形式へのハイパーリンクが含まれます。結果セットの各行の最初の列は、その行の一意の識別子である必要があり、path/to/feed/{id}という形式のハイパーリンクを生成するために使用されます(最初の列の値が{id}の値として使用されます)。その行の他の列は、リソースを要約するとみなされ、フィードに含まれます。リソースの完全形式のリソース・テンプレートも、別途定義する必要があります。結果フォーマット: JSON

p_source

選択したHTTPメソッドのソース実装です。

p_items_per_page

リソース・ハンドラHTTP操作GETメソッドのデフォルトのページ区切り、つまり、データベース問合せに基づくJSON書式結果セットのページごとに戻される行の数です。デフォルト: NULL (リソース・モジュール設定に従います)。

p_status

公開ステータスです。有効な値: 'PUBLISHED' (デフォルト)または'NOT_PUBLISHED'。

p_etag_type

リソース・テンプレートによって使用されるエンティティ・タグのタイプです。エンティティ・タグとは、リソースのバージョン識別子として動作するHTTPヘッダーです。エンティティ・タグを使用して、以前取得したリソースの取得を避け、リソースを更新する際にコミット時のロックを実行します。有効な値: 'HASH'、'QUERY'または'NONE'。

- HASH - Secure HASHとも呼ばれる: 戻されたリソース表現の内容は、特定のリソース・バージョンの一意のフィンガープリントを提供するためのセキュア・ダイジェスト・ファンクションを使用してハッシュ化されています。

- QUERY - リソース・バージョンを一意に識別する問合せを手動で定義します。手動で定義した問合せによって、リソース表現全体をハッシュ化するより効率的にエンティティ・タグが生成されることが多いです。

- NONE - エンティティ・タグを生成しません。

p_etag_query

エンティティ・タグの生成に使用される問合せです。

p_mimes_allowed

ハンドラが受け入れるMIMEタイプのカンマ区切りリストです。PUTおよびPOSTにのみ適用されます。

p_module_comments

コメント・テキストです。

p_template_comments

コメント・テキストです。

p_handler_comments

コメント・テキストです。

使用上の注意

リソース・モジュール、リソース・テンプレートおよびリソース・ハンドラを1つの呼出しで作成します。

このプロシージャの使用は推奨されていません。かわりにORDS.DEFINE_SERVICEを使用してください。

例

次の例では、簡単なサービスを作成します。

BEGIN
ORDS.CREATE_SERVICE(
p_module_name => 'my.tickets',
p_base_path => '/my/tickets/',
p_pattern => '.',
p_source => 'select t.id "$.id", t.id, t.title from tickets t' ||
' where t.owner = :current_user order by t.updated_on desc'
);
END;
/

5.3 ORDS.DEFINE_HANDLER

形式

ORDS.DEFINE_HANDLER(
p_module_name   IN ords_modules.name%type,
p_pattern       IN ords_templates.uri_template%type,
p_priority      IN ords_templates.priority%type DEFAULT 0,
p_etag_type     IN ords_templates.etag_type%type DEFAULT 'HASH',
p_etag_query    IN ords_templates.etag_query%type DEFAULT NULL,
p_comments      IN ords_templates.comments%type DEFAULT NULL);

説明

DEFINE_HANDLERはモジュール・ハンドラを定義します。ハンドラがすでに存在する場合、そのハンドラと既存のすべてのハンドラはこの定義によって置き換えられます。それ以外の場合、新しいハンドラが作成されます。

パラメータ

p_module_name

所有RESTfulサービス・モジュールの名前です。大/小文字が区別されます。

p_pattern

所有リソース・テンプレートの一致パターンです。

p_method

このハンドラの応答先のHTTPメソッドです。有効な値: GET (リソースの表現を取得します)、POST (新規リソースを作成またはコレクションにリソースを追加します)、PUT (既存のリソースを更新します)、DELETE (既存のリソースを削除します)。

p_source_type

このハンドラのHTTPリクエスト・メソッドです。有効な値は次のとおりです。

- source_type_collection_feed。SQL問合せを実行し、結果セットをORDS標準JSON表現に変換します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSON

- source_type_collection_item。1行分のデータをORDS標準JSON表現に返すSQL問合せを1回実行します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSON

- source_type_media。特定の書式に準拠したSQL問合せを実行し、結果セットを、表現のインターネット・メディア・タイプを識別する付随のHTTP Content-Typeヘッダーで、バイナリ表現に変換します。結果フォーマット: バイナリ

- source_type_plsql。匿名のPL/SQLブロックを実行し、OUTまたはIN/OUTパラメータをJSON表現に変換します。HTTPメソッドが、DELETE、PUT、POSTの場合のみ使用可能です。結果フォーマット: JSON

- source_type_query || source_type_csv_query。SQL問合せを実行し、結果セットを、選択したフォーマットに応じて、ORDSレガシーJavaScript Object Notation (JSON)表現またはCSV表現に変換します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSONまたはCSV

- source_type_query_one_row。1行分のデータをORDSレガシーJSON表現に返すSQL問合せを1回実行します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSON

- source_type_feed。SQL問合せを実行し、結果をJSONフィード表現に変換します。フィードの各アイテムには、リソースのサマリーと、リソースの完全形式へのハイパーリンクが含まれます。結果セットの各行の最初の列は、その行の一意の識別子である必要があり、path/to/feed/{id}という形式のハイパーリンクを生成するために使用されます(最初の列の値が{id}の値として使用されます)。その行の他の列は、リソースを要約するとみなされ、フィードに含まれます。リソースの完全形式のリソース・テンプレートも、別途定義する必要があります。結果フォーマット: JSON

p_source

選択したHTTPメソッドのソース実装です。

p_items_per_page

リソース・ハンドラHTTP操作GETメソッドのデフォルトのページ区切り、つまり、データベース問合せに基づくJSON書式結果セットのページごとに戻される行の数です。デフォルト: NULL (リソース・モジュール設定に従います)。

p_mimes_allowed

ハンドラが受け入れるMIMEタイプのカンマ区切りリストです。PUTおよびPOSTにのみ適用されます。

p_comments

コメント・テキストです。

使用上の注意

各HTTPメソッド(ソース・タイプ)に許可されるハンドラは1つのみです。

例

次の例では、新しいチケットを受け入れる/my/tickets/リソースに対するPOSTハンドラを定義します。

BEGIN
ORDS.DEFINE_HANDLER(
p_module_name => 'my.tickets',
p_pattern => '.',
p_method  => 'POST',
p_mimes_allowed => 'application/json',
p_source_type => ords.source_type_plsql,
p_source => '
declare
l_owner varchar2(255);
l_payload blob;
l_id number;
begin
l_payload := :body;
l_owner := :owner;
if ( l_owner is null ) then
l_owner := :current_user;
end if;
l_id := ticket_api.create_ticket(
p_json_entity => l_payload,
p_author => l_owner
);
:location := ''./'' || l_id;
:status := 201;
end;
'
);
END;
/

5.4 ORDS.DEFINE_MODULE

形式

ORDS.DEFINE_MODULE(
p_module_name     IN ords_modules.name%type,
p_base_path       IN ords_modules.uri_prefix%type,
p_items_per_page  IN ords_modules.items_per_page%type DEFAULT 25,
p_status          IN ords_modules.status%type DEFAULT 'PUBLISHED',
p_comments        IN ords_modules.comments%type DEFAULT NULL);

説明

DEFINE_MODULEはリソース・モジュールを定義します。モジュールがすでに存在する場合、そのモジュールと既存のすべてのテンプレートはこの定義によって置き換えられます。それ以外の場合、新しいモジュールが作成されます。

パラメータ

p_module_name

所有RESTfulサービス・モジュールの名前です。大/小文字が区別されます。

p_base_path

このRESTfulサービスにアクセスする場合に使用されるURIのベースです。例: hr/は、hr/で始まるすべてのURIがこのリソース・モジュールで処理されることを意味します。

p_items_per_page

リソース・ハンドラHTTP操作GETメソッドのデフォルトのページ区切り、つまり、データベース問合せに基づくJSON書式結果セットのページごとに戻される行の数です。デフォルト: 25。

p_status

公開ステータスです。有効な値: PUBLISHED (デフォルト)またはNOT_PUBLISHED。

p_comments

コメント・テキストです。

使用上の注意

(なし。)

例

次の例では、簡単なモジュールを作成します。

BEGIN
ORDS.DEFINE_MODULE(
p_module_name => 'my.tickets',
p_base_path => '/my/tickets/'
);
END;
/

5.5 ORDS.DEFINE_PARAMETER

形式

ORDS.DEFINE_PARAMETER(
p_module_name        IN ords_modules.name%type,
p_pattern            IN ords_templates.uri_template%type,
p_method             IN ords_handlers.method%type,
p_name               IN ords_parameters.name%type ,
p_bind_variable_name IN ords_parameters.bind_variable_name%type
DEFAULT NULL,
p_source_type        IN ords_parameters.source_type%type DEFAULT 'HEADER',
p_param_type         IN ords_parameters.param_type%type DEFAULT 'STRING',
p_access_method      IN ords_parameters.access_method%type DEFAULT 'IN',
p_comments           IN ords_parameters.comments%type DEFAULT NULL);

説明

DEFINE_PARAMETERはモジュール・ハンドラ・パラメータを定義します。パラメータがすでに存在する場合、そのパラメータはこの定義によって置き換えられます。それ以外の場合、新しいパラメータが作成されます。

パラメータ

p_module_name

所有RESTfulサービス・モジュールの名前です。大/小文字が区別されます。

p_pattern

所有リソース・テンプレートの一致パターンです。

p_method

所有ハンドラHTTPメソッドです。有効な値: GET (リソースの表現を取得します)、POST (新規リソースを作成またはコレクションにリソースを追加します)、PUT (既存のリソースを更新します)、DELETE (既存のリソースを削除します)。

p_name

URIテンプレートまたはHTTPヘッダーで呼ばれるパラメータの名前です。有効なSQLパラメータ名ではない名前のマップに使用されます。

p_bind_variable_name

SQLで呼ばれるパラメータの名前です。NULLが指定された場合、パラメータはバインドされません。

p_source_type

パラメータがURIテンプレートまたはHTTPヘッダーで発生するかどうかが識別されるタイプです。有効な値: HEADER、RESPONSE、URI。

p_param_type

パラメータのネイティブ・タイプです。有効な値: STRING、INT、DOUBLE、BOOLEAN、LONG、TIMESTAMP。

p_access_method

パラメータ・アクセス・メソッドです。パラメータが入力値か、出力値か、またはその両方かどうかを示します。有効な値: IN、OUT、INOUT。

p_comments

コメント・テキストです。

使用上の注意

すべてのパラメータに同じハンドラの一意の名前および変数名を指定する必要があります。

例

次の例では、作成されたチケットの場所を格納するPOSTハンドラのアウトバウンド・パラメータを定義します。

BEGIN
ORDS.DEFINE_PARAMETER(
p_module_name => 'my.tickets',
p_pattern => '.',
p_method => 'POST',
p_name => 'X-APEX-FORWARD',
p_bind_variable_name => 'location',
p_source_type => 'HEADER',
p_access_method => 'OUT'
);
END;
/

次の例では、操作のHTTPステータスを格納するPOSTハンドラのアウトバウンド・パラメータを定義します。

BEGIN
ORDS.DEFINE_PARAMETER(
p_module_name => 'my.tickets',
p_pattern => '.',
p_method => 'POST',
p_name => 'X-APEX-STATUS-CODE',
p_bind_variable_name => 'status',
p_source_type => 'HEADER',
p_access_method => 'OUT'
);
END;
/

5.6 ORDS.DEFINE_PRIVILEGE

形式

ORDS.DEFINE_PRIVILEGE(
p_privilege_name    IN sec_privileges.name%type,
p_roles             IN owa.vc_arr,
p_patterns          IN owa.vc_arr,
p_modules           IN owa.vc_arr,
p_label             IN sec_privileges.label%type DEFAULT NULL,
p_description       IN sec_privileges.description%type DEFAULT NULL,
p_comments          IN sec_privileges.comments%type DEFAULT NULL);
or
ORDS.DEFINE_PRIVILEGE(
p_privilege_name    IN sec_privileges.name%type,
p_roles             IN owa.vc_arr,
p_patterns          IN owa.vc_arr,
p_label             IN sec_privileges.label%type DEFAULT NULL,
p_description       IN sec_privileges.description%type DEFAULT NULL,
p_comments          IN sec_privileges.comments%type DEFAULT NULL);
or
ORDS.DEFINE_PRIVILEGE(
p_privilege_name    IN sec_privileges.name%type,
p_roles             IN owa.vc_arr,
p_label             IN sec_privileges.label%type DEFAULT NULL,
p_description       IN sec_privileges.description%type DEFAULT NULL,
p_comments          IN sec_privileges.comments%type DEFAULT NULL);

説明

DEFINE_PRIVILEGEはOracle REST Data Services権限を定義します。権限がすでに存在する場合、その権限、既存のすべてのパターン、モジュールおよびロールとのすべての関連付けは、この定義によって置き換えられます。それ以外の場合、新しい権限が作成されます。

パラメータ

p_privilege_name

権限名空白は使用できません。

p_roles

ロールの名前です。このうち少なくとも1つが権限に必要になります。空にできます。この場合、ユーザーの認証は必要ですが、特定のロールは必要ありません。ただし、nullにはできません。認証されていないユーザーはアクセスを拒否されます。

p_patterns

パターンのリストです。

p_modules

現在のスキーマに作成されたモジュールを参照しているモジュール名のリストです。

p_label

エンド・ユーザーに表示されるこのセキュリティ制約の名前です。nullも指定できます。

p_description

この制約によって保護されるリソースの目的の簡単な説明です。

p_comments

コメント・テキストです。

使用上の注意

p_roles、p_patternsおよびp_modulesにはnull値を指定できません。値を渡さない場合は、適切なプロシージャ仕様を選択するか、空のowa.vc_arr値を渡します。

例

次の例では、ロール、パターンおよびモジュールに結合された権限を作成します。

DECLARE
l_priv_roles owa.vc_arr;
l_priv_patterns owa.vc_arr;
l_priv_modules owa.vc_arr;
BEGIN
l_priv_roles(1) := 'Tickets User';
l_priv_patterns(1) := '/my/*';
l_priv_patterns(2) := '/comments/*';
l_priv_patterns(3) := '/tickets_feed/*';
l_priv_patterns(4) := '/tickets/*';
l_priv_patterns(5) := '/categories/*';
l_priv_patterns(6) := '/stats/*';

l_priv_modules(1) := 'my.tickets';

ords.create_role('Tickets User');

ords.define_privilege(
p_privilege_name     => 'tickets.privilege',
p_roles              => l_priv_roles,
p_patterns           => l_priv_patterns,
P_modules            => l_priv_modules,
p_label              => 'Task Ticketing Access',
p_description        => 'Provides the ability to create, ' ||
'update and delete tickets ' ||
'and post comments on tickets'
);
END;
/

次の例では、ロールおよびパターンに結合された権限を作成します。

DECLARE
l_priv_roles owa.vc_arr;
l_priv_patterns owa.vc_arr;
BEGIN
l_priv_roles(1) := 'Tickets User';
l_priv_patterns(1) := '/my/*';
l_priv_patterns(2) := '/comments/*';
l_priv_patterns(3) := '/tickets_feed/*';
l_priv_patterns(4) := '/tickets/*';
l_priv_patterns(5) := '/categories/*';
l_priv_patterns(6) := '/stats/*';

ords.create_role('Tickets User');

ords.define_privilege(
p_privilege_name     => 'tickets.privilege',
p_roles              => l_priv_roles,
p_patterns           => l_priv_patterns,
p_label              => 'Task Ticketing Access',
p_description        => 'Provides the ability to create, ' ||
'update and delete tickets ' ||
'and post comments on tickets'
);
END;
/

次の例では、ロールに結合された権限を作成します。

DECLARE
l_priv_roles owa.vc_arr;
BEGIN
l_priv_roles(1) := 'Tickets User';

ords.create_role('Tickets User');

ords.define_privilege(
p_privilege_name     => 'tickets.privilege',
p_roles              => l_priv_roles,
p_label              => 'Task Ticketing Access',
p_description        => 'Provides the ability to create, ' ||
'update and delete tickets ' ||
'and post comments on tickets'
);
END;
/

5.7 ORDS.DEFINE_SERVICE

形式

ORDS.DEFINE_SERVICE(
p_module_name        IN ords_modules.name%type,
p_base_path          IN ords_modules.uri_prefix%type,
p_pattern            IN ords_templates.uri_template%type,
p_method             IN ords_handlers.method%type DEFAULT 'GET',
p_source_type        IN ords_handlers.source_type%type
DEFAULT ords.source_type_collection_feed,
p_source             IN ords_handlers.source%type,
p_items_per_page     IN ords_modules.items_per_page%type DEFAULT 25,
p_status             IN ords_modules.status%type DEFAULT 'PUBLISHED',
p_etag_type          IN ords_templates.etag_type%type DEFAULT 'HASH',
p_etag_query         IN ords_templates.etag_query%type DEFAULT NULL,
p_mimes_allowed      IN ords_handlers.mimes_allowed%type DEFAULT NULL,
p_module_comments    IN ords_modules.comments%type DEFAULT NULL,
p_template_comments  IN ords_modules.comments%type DEFAULT NULL,
p_handler_comments   IN ords_modules.comments%type DEFAULT NULL);

説明

DEFINE_SERVICEは、リソース・モジュール、リソース・テンプレートおよびリソース・ハンドラを1つの呼出しで定義します。モジュールがすでに存在する場合、そのモジュールと既存のすべてのテンプレートはこの定義によって置き換えられます。それ以外の場合、新しいモジュールが作成されます。

パラメータ

p_module_name

RESTfulサービス・モジュールの名前です。大/小文字が区別されます。一意である必要があります。

p_base_path

このRESTfulサービスにアクセスする場合に使用されるURIのベースです。例: hr/は、hr/で始まるすべてのURIがこのリソース・モジュールで処理されることを意味します。

p_pattern

リソース・テンプレートの一致パターンです。たとえば、/objects/:object/:id?のパターンは/objects/emp/101と一致し(101のidで empリソースにあるアイテムのリクエストと一致)、/objects/emp/とも一致します。(:idパラメータには?修飾子の注釈が付き、これはidパラメータがオプションであることを示すため、empリソースのリクエストとも一致します。)

p_method

このハンドラの応答先のHTTPメソッドです。有効な値: GET (リソースの表現を取得します)、POST (新規リソースを作成またはコレクションにリソースを追加します)、PUT (既存のリソースを更新します)、DELETE (既存のリソースを削除します)。

p_source_type

このハンドラのHTTPリクエスト・メソッドです。有効な値は次のとおりです。

- source_type_collection_feed。SQL問合せを実行し、結果セットをORDS標準JSON表現に変換します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSON

- source_type_collection_item。1行分のデータをORDS標準JSON表現に返すSQL問合せを1回実行します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSON

- source_type_media。特定の書式に準拠したSQL問合せを実行し、結果セットを、表現のインターネット・メディア・タイプを識別する付随のHTTP Content-Typeヘッダーで、バイナリ表現に変換します。結果フォーマット: バイナリ

- source_type_plsql。匿名のPL/SQLブロックを実行し、OUTまたはIN/OUTパラメータをJSON表現に変換します。HTTPメソッドが、DELETE、PUT、POSTの場合のみ使用可能です。結果フォーマット: JSON

- source_type_query || source_type_csv_query。SQL問合せを実行し、結果セットを、選択したフォーマットに応じて、ORDSレガシーJavaScript Object Notation (JSON)表現またはCSV表現に変換します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSONまたはCSV

- source_type_query_one_row。1行分のデータをORDSレガシーJSON表現に返すSQL問合せを1回実行します。HTTPメソッドがGETの場合に使用可能です。結果フォーマット: JSON

- source_type_feed。SQL問合せを実行し、結果をJSONフィード表現に変換します。フィードの各アイテムには、リソースのサマリーと、リソースの完全形式へのハイパーリンクが含まれます。結果セットの各行の最初の列は、その行の一意の識別子である必要があり、path/to/feed/{id}という形式のハイパーリンクを生成するために使用されます(最初の列の値が{id}の値として使用されます)。その行の他の列は、リソースを要約するとみなされ、フィードに含まれます。リソースの完全形式のリソース・テンプレートも、別途定義する必要があります。結果フォーマット: JSON

p_source

選択したHTTPメソッドのソース実装です。

p_items_per_page

リソース・ハンドラHTTP操作GETメソッドのデフォルトのページ区切り、つまり、データベース問合せに基づくJSON書式結果セットのページごとに戻される行の数です。デフォルト: NULL (リソース・モジュール設定に従います)。

p_status

公開ステータスです。有効な値: PUBLISHED (デフォルト)またはNOT_PUBLISHED。

p_etag_type

リソース・テンプレートによって使用されるエンティティ・タグのタイプです。エンティティ・タグとは、リソースのバージョン識別子として動作するHTTPヘッダーです。エンティティ・タグを使用して、以前取得したリソースの取得を避け、リソースを更新する際にコミット時のロックを実行します。有効な値は、HASH、QUERY、NONEです。

- HASH (Secure HASHとも呼ばれる): 戻されたリソース表現の内容は、特定のリソース・バージョンの一意のフィンガープリントを提供するためのセキュア・ダイジェスト・ファンクションを使用してハッシュ化されています。

- QUERY: リソース・バージョンを一意に識別する問合せを手動で定義します。手動で定義した問合せによって、リソース表現全体をハッシュ化するより効率的にエンティティ・タグが生成されることが多いです。

- NONE: エンティティ・タグを生成しません。

p_etag_query

エンティティ・タグの生成に使用される問合せです。

p_mimes_allowed

ハンドラが受け入れるMIMEタイプのカンマ区切りリストです。PUTおよびPOSTにのみ適用されます。

p_module_comments

コメント・テキストです。

p_template_comments

コメント・テキストです。

p_handler_comments

コメント・テキストです。

使用上の注意

リソース・モジュール、リソース・テンプレートおよびリソース・ハンドラを1つの呼出しで作成します。

非推奨のORDS.CREATE_SERVICEプロシージャのかわりに、このプロシージャを使用してください。

例

次の例では、現在のユーザーのチケットを取得するRESTサービスを定義します。

BEGIN
ORDS.DEFINE_SERVICE(
p_module_name => 'my.tickets',
p_base_path => '/my/tickets/',
p_pattern => '.',
p_source => 'select t.id "$.id", t.id, t.title from tickets t' ||
' where t.owner = :current_user order by t.updated_on desc'
);
END;
/

次の例では、カテゴリによってフィルタされたチケットを取得するRESTサービスを定義します。

BEGIN
ORDS.DEFINE_SERVICE(
p_module_name => 'by.category',
p_base_path => '/by/category/',
p_pattern => ':category_id',
p_source => 'select ''../../my/tickets/'' ||
t.id "$.id", t.id, t.title' ||
' from tickets t, categories c, ticket_categories tc' ||
' where c.id = :category_id and c.id = tc.category_id and' ||
' tc.ticket_id = t.id order by t.updated_on desc'
);
END;
/

5.8 ORDS.DEFINE_TEMPLATE

形式

ORDS.DEFINE_TEMPLATE(
p_module_name  IN ords_modules.name%type,
p_pattern      IN ords_templates.uri_template%type,
p_priority     IN ords_templates.priority%type DEFAULT 0,
p_etag_type    IN ords_templates.etag_type%type DEFAULT 'HASH',
p_etag_query   IN ords_templates.etag_query%type DEFAULT NULL,
p_comments     IN ords_templates.comments%type DEFAULT NULL);

説明

DEFINE_TEMPLATEはリソース・テンプレートを定義します。テンプレートがすでに存在する場合、そのテンプレートと既存のすべてのハンドラはこの定義によって置き換えられます。それ以外の場合、新しいテンプレートが作成されます。

パラメータ

p_module_name

所有RESTfulサービス・モジュールの名前です。大/小文字が区別されます。

p_pattern

リソース・テンプレートの一致パターンです。たとえば、/objects/:object/:id?のパターンは/objects/emp/101と一致し(101のidで empリソースにあるアイテムのリクエストと一致)、/objects/emp/とも一致します。(:idパラメータには?修飾子の注釈が付き、これはidパラメータがオプションであることを示すため、empリソースのリクエストとも一致します。)

p_priority

リソース・テンプレートを評価する優先順位: 0 (低優先度。デフォルト)から9 (高優先度)です。

p_etag_type

リソース・テンプレートによって使用されるエンティティ・タグのタイプです。エンティティ・タグとは、リソースのバージョン識別子として動作するHTTPヘッダーです。エンティティ・タグを使用して、以前取得したリソースの取得を避け、リソースを更新する際にコミット時のロックを実行します。有効な値は、HASH、QUERY、NONEです。

- HASH (Secure HASHとも呼ばれる): 戻されたリソース表現の内容は、特定のリソース・バージョンの一意のフィンガープリントを提供するためのセキュア・ダイジェスト・ファンクションを使用してハッシュ化されています。

- QUERY: リソース・バージョンを一意に識別する問合せを手動で定義します。手動で定義した問合せによって、リソース表現全体をハッシュ化するより効率的にエンティティ・タグが生成されることが多いです。

- NONE: エンティティ・タグを生成しません。

p_etag_query

エンティティ・タグの生成に使用される問合せです。

p_comments

コメント・テキストです。

使用上の注意

リソース・テンプレートのパターンは、リソース・モジュールで一意である必要があります。

例

次の例では、チケットのアイテムを表示するためのリソースを定義します。

BEGIN
ORDS.DEFINE_TEMPLATE(
p_module_name => 'my.tickets',
p_pattern => '/:id'
);
END;
/

5.9 ORDS.DELETE_MODULE

形式

ORDS.DELETE_MODULE(
p_module_name  IN ords_modules.name%type);

説明

DELETE_MODULEはリソース・モジュールを削除します。

パラメータ

p_module_name

所有RESTfulサービス・モジュールの名前です。大/小文字が区別されます。

使用上の注意

モジュールがまだ存在しないか、現在のユーザーがモジュールにアクセス可能な場合、例外は発生しません。

例

次の例では、リソース・モジュールを削除します。

EXECUTE ORDS.DELETE_MODULE(p_module_name=>'my.tickets');

5.10 ORDS.DELETE_PRIVILEGE

形式

ORDS.DELETE_PRIVILEGE(
p_name  IN sec_privileges.name%type);

説明

DELETE_PRIVILEGEは権限を削除します。

パラメータ

p_name

権限名

使用上の注意

権限がまだ存在しないか、現在のユーザーがモジュールにアクセス可能な場合、例外は発生しません。

例

次の例では、権限を削除します。

EXECUTE ORDS.DELETE_PRIVILEGE(p_name=>'tickets.privilege');

5.11 ORDS.DELETE_ROLE

形式

ORDS.DELETE_ROLE(
p_role_name IN sec_roles.name%type);

説明

DELETE_ROLEは指定されたロールを削除します。

パラメータ

p_name

ロールの名前。

使用上の注意

これは、ロールとそのロールを参照するすべての権限との間の関連付けも削除します。

ロールがまだ存在しない場合、例外は発生しません。

例

次の例では、ロールを削除します。

EXECUTE ORDS.DELETE_ROLE(p_role_name=>'Tickets User');

5.12 ORDS.DROP_REST_FOR_SCHEMA

形式

ORDS.DROP_REST_FOR_SCHEMA(
p_schema ords_schemas.parsing_schema%type DEFAULT NULL);

説明

DROP_REST_FOR_SCHEMAは、関連付けられたスキーマのすべての自動REST Oracle REST Data Servicesメタデータを削除します。

パラメータ

p_schema

スキーマの名前です。

使用上の注意

このプロシージャは、事実上、ORDS.Enable_Schemaプロシージャによって実行されたアクションを元に戻します。

例

次の例では、TICKETSスキーマのすべての自動REST Oracle REST Data Servicesメタデータを削除します。

EXECUTE ORDS.DROP_REST_FOR_SCHEMA('tickets');

関連トピック

- ORDS.ENABLE_SCHEMA

5.13 ORDS.ENABLE_OBJECT

形式

ORDS.ENABLE_OBJECT(
p_enabled         IN boolean DEFAULT TRUE,
p_schema          IN ords_schemas.parsing_schema%type DEFAULT NULL,
p_object          IN ords_objects.parsing_object%type,
p_object_type     IN ords_objects.type%type DEFAULT 'TABLE',
p_object_alias    IN ords_objects.object_alias%type DEFAULT NULL,
p_auto_rest_auth  IN boolean DEFAULT NULL);

説明

ENABLE_OBJECTは、スキーマで、指定した表またはビューへのOracle REST Data Servicesアクセスを有効にします。

パラメータ

p_enabled

アクセスを有効にするには、TRUE、アクセスを無効にするには、FALSEです。

p_schema

表またはビューのスキーマの名前です。

p_object

表またはビューの名前。

p_object_type

オブジェクトのタイプ: TABLE (デフォルト)またはVIEWです。

p_object_alias

オブジェクトの別名です。

p_auto_rest_auth

Oracle REST Data Servicesメタデータへのアクセスをこのオブジェクトに許可する前に、ユーザーの認可を必要とするかどうかを制御します。

使用上の注意

DBAロールを持つデータベース・ユーザーのみが、現在自分で所有しているオブジェクトを有効化およびアクセスできます。

例

次の例では、CATEGORIESという名前の表を有効化します。

EXECUTE ORDS.ENABLE_OBJECT(p_object=>'CATEGORIES');

次の例では、TICKETS_FEEDという名前のビューを有効化します。

BEGIN
ORDS.ENABLE_OBJECT(
p_object => 'TICKETS_FEED',
p_object_type => 'VIEW'
);
END;
/

5.14 ORDS.ENABLE_SCHEMA

形式

ORDS.ENABLE_SCHEMA
p_enabled             IN boolean DEFAULT TRUE,
p_schema              IN ords_schemas.parsing_schema%type DEFAULT NULL,
p_url_mapping_type    IN ords_url_mappings.type%type DEFAULT 'BASE_PATH',
p_url_mapping_pattern IN ords_url_mappings.pattern%type DEFAULT NULL,
p_auto_rest_auth      IN boolean DEFAULT NULL);

説明

ENABLE_SCHEMAにより、Oracle REST Data Servicesは指定されたスキーマにアクセスできます。

パラメータ

p_enabled

Oracle REST Data Servicesアクセスを有効にするには、TRUE、Oracle REST Data Servicesアクセスを無効にするには、FALSEです。

p_schema

スキーマの名前です。p_schemaパラメータが省略された場合、現在のスキーマが有効化されます。

p_url_mapping_type

URLマッピング・タイプ: BASE_PATHまたはBASE_URL。

p_url_mapping_pattern

URLマッピング・パターンです。

p_auto_rest_auth

スキーマの場合、このスキーマのOracle REST Data Servicesメタデータ・カタログへのアクセスを許可する前に、Oracle REST Data Servicesがユーザーの認可を必要とするかどうかを制御します。

使用上の注意

DBAロールを持つデータベース・ユーザーのみが、自分で所有しているスキーマ以外を有効化または無効化できます。

例

次の例では、現在のスキーマを有効化します。

EXECUTE ORDS.ENABLE_SCHEMA;

5.15 ORDS.PUBLISH_MODULE

形式

ORDS.PUBLISH_MODULE(
p_module_name  IN ords_modules.name%type,
p_status       IN ords_modules.status%type DEFAULT 'PUBLISHED');

説明

PUBLISH_MODULEは、Oracle REST Data Servicesリソース・モジュールの公開ステータスを変更します。

パラメータ

p_module_name

RESTfulサービス・モジュールの現在の名前です。大/小文字が区別されます。

p_status

公開ステータスです。有効な値: PUBLISHED (デフォルト)またはNOT_PUBLISHED。

使用上の注意

(なし。)

例

次の例では、以前に定義したmy.ticketsという名前のモジュールを公開します。

EXECUTE ORDS.PUBLISH_MODULE(p_module_name=>'my.tickets');

5.16 ORDS.RENAME_MODULE

形式

ORDS.RENAME_MODULE(
p_module_name    IN ords_modules.name%type,
p_new_name       IN ords_modules.name%type DEFAULT NULL,
p_new_base_path  IN ords_modules.uri_prefix%type DEFAULT NULL);

説明

RENAME_MODULEによって、Oracle REST Data Servicesリソース・モジュールの名前またはベース・パス、あるいはその両方を変更できます。

パラメータ

p_module_name

RESTfulサービス・モジュールの現在の名前です。大/小文字が区別されます。

p_new_name

RESTfulサービス・モジュールに割り当てられる新しい名前です。大/小文字が区別されます。このパラメータがnullの場合、名前は変更されません。

p_new_base_path

このRESTfulサービスにアクセスする場合に使用されるURIのベースです。例: hr/は、hr/で始まるすべてのURIがこのリソース・モジュールで処理されることを意味します。このパラメータがnullの場合、ベース・パスは変更されません。

使用上の注意

新しいリソース・モジュールの名前とベース・パスの両方が、有効化されたスキーマ内で一意である必要があります。

例

次の例では、リソース・モジュールmy.ticketsの名前をold.ticketsに変更します。

BEGIN
ORDS.RENAME_MODULE(
p_module_name =>'my.tickets',
p_new_name=>'old.tickets',
p_new_base_path=>'/old/tickets/');
END;
/

5.17 ORDS.RENAME_PRIVILEGE

形式

ORDS.RENAME_PRIVILEGE(
p_name      IN sec_privileges.name%type,
p_new_name  IN sec_privileges.name%type);

説明

RENAME_PRIVILEGEは権限の名前を変更します。

パラメータ

p_name

権限の現在の名前です。

p_new_name

権限に割り当てられる新しい名前です。

使用上の注意

(なし。)

例

次の例では、権限tickets.privilegeの名前をold.tickets.privilegeに変更します。

BEGIN
ORDS.RENAME_PRIVILEGE(
p_name =>'tickets.privilege',
p_new_name=>'old.tickets.privilege');
END;
/

5.18 ORDS.RENAME_ROLE

形式

ORDS.RENAME_ROLE(
p_role_name  IN sec_roles.name%type,
p_new_name   IN sec_roles.name%type);

説明

RENAME_ROLEはロールの名前を変更します。

パラメータ

p_role_name

ロールの現在の名前です。

p_new_name

ロールに割り当てられる新しい名前です。

使用上の注意

p_role_nameが存在する必要があります。

例

次の例では、既存のロールの名前を変更します。

BEGIN
ORDS.RENAME_ROLE(
p_role_name=>'Tickets User',
p_new_name=>'Legacy Tickets User');
END;
/

5.19 ORDS.SET_MODULE_ORIGINS_ALLOWED

形式

ORDS.SET_MODULE_ORIGINS_ALLOWED
p_module_name     IN ords_modules.name%type,
p_origins_allowed IN sec_origins_allowed_modules.origins_allowed%type);

説明

SET_MODULE_ORIGINS_ALLOWEDは、リソース・モジュールの許可されたオリジンを構成します。既存のすべての許可されたオリジンは置き換えられます。

パラメータ

p_module_name

リソース・モジュールの名前です。

p_origins_allowed

URLの接頭辞のカンマ区切りリスト。リストが空の場合、既存のオリジンは削除されます。

使用上の注意

リソース・モジュールの許可されていないオリジンを示す(さらに既存のすべての許可されたオリジンを削除する)には、空のp_origins_allowed値を指定します。

例

次では、リソース・モジュールmy.ticketsを指定した2つのオリジンに制限します。

BEGIN
ORDS.SET_MODULE_ORIGINS_ALLOWED(
p_module_name     => 'my.tickets',
p_origins_allowed => 'http://example.com,https://example.com');
END;
/

5.20 ORDS.SET_URL_MAPPING

形式

ORDS.SET_URL_MAPPING
p_schema              IN ords_schemas.parsing_schema%type DEFAULT NULL,
p_url_mapping_type    IN ords_url_mappings.type%type,
p_url_mapping_pattern IN ords_url_mappings.pattern%type);

説明

SET_URL_MAPPINGは、指定したスキーマがリクエストURLにマップされる方法を構成します。

パラメータ

p_schema

マップするスキーマの名前です。デフォルトは現在のユーザーのスキーマです。

p_url_mapping_type

URLマッピング・タイプ: BASE_PATHまたはBASE_URL。

p_url_mapping_pattern

URLマッピング・パターンです。

使用上の注意

DBAユーザーのみが自身で所有していないスキーマのマッピングを更新できます。

例

次の例では、現在のユーザーのBASE_PATHマッピングを作成します。

BEGIN
ORDS.SET_URL_MAPPING(
p_url_mapping_type    => 'BASE_PATH',
p_url_mapping_pattern => 'https://example.com/ords/ticketing'
);
END;
/

6 OAUTH PL/SQLパッケージのリファレンス

OAUTH PL/SQLパッケージには、Oracle REST Data Servicesを使用してOAuth認証を実装するプロシージャが含まれています。

関連トピック

- Oracle REST Data Services PL/SQL APIの使用

6.1 OAUTH.CREATE_CLIENT

形式

OAUTH.CREATE_CLIENT(
p_name            VARCHAR2 IN,
p_grant_type      VARCHAR2 IN,
p_owner           VARCHAR2 IN DEFAULT NULL,
p_description     VARCHAR2 IN DEFAULT NULL,
p_allowed_origins VARCHAR2 IN DEFAULT NULL,
p_redirect_uri    VARCHAR2 IN DEFAULT NULL,
p_support_email   VARCHAR2 IN DEFAULT NULL,
p_support_uri     VARCHAR2 IN DEFAULT NULL,
p_privilege_names VARCHAR2 IN)

説明

OAuthクライアントの登録を作成します。

パラメータ

p_name

クライアントの名前で、Three-Legged OAuthの承認フェーズでエンド・ユーザーに表示されます。一意である必要があります。

p_grant_type

authorization_code、implicitまたはclient_credentialsのいずれかである必要があります。

p_owner

クライアント・アプリケーションを所有するパーティの名前です。

p_description

クライアントの目的の説明で、Three-Legged OAuthの承認フェーズでエンド・ユーザーに表示されます。p_grant_typeがclient_credentialsの場合はnullにもできます。それ以外の場合はnullにはできません。

p_allowed_origins

URLの接頭辞のカンマ区切りリスト。リストが空の場合、既存のオリジンは削除されます。

p_redirect_uri

OAuthアクセス・トークンまたはエラーが含まれるリダイレクトが送信されるクライアント制御URIです。p_grant_typeがclient_credentialsの場合はnullにもできます。それ以外の場合はnullにはできません。

p_support_email

エンド・ユーザーがサポートを得るためにクライアントに連絡できる電子メールです。

p_support_uri

エンド・ユーザーがサポートを得るためにクライアントに連絡できるURIです。例: http://www.myclientdomain.com/support/

p_privilege_names

クライアントがアクセスするカンマ区切りの権限のリストです。

使用上の注意

操作を有効にするには、このプロシージャを呼び出した後でCOMMIT文を使用します。

例

次の例では、OAuthクライアント登録を作成します。

BEGIN
OAUTH.create_client(
'CLIENT_TEST',
'authorization_code',
'test_user',
'This is a test description.',
'',
'https://example.org/my_redirect/#/',
'test@example.org',
'https://example.org/help/#/',
'MyPrivilege'
);
COMMIT;
END;
/

6.2 OAUTH.DELETE_CLIENT

形式

OAUTH.DELETE_CLIENT(
p_name VARCHAR2 IN);

説明

OAuthクライアント登録を削除します。

パラメータ

p_name

削除されるクライアント登録の名前です。

使用上の注意

操作を有効にするには、このプロシージャを呼び出した後でCOMMIT文を使用します。

例

次の例では、OAuthクライアント登録を削除します。

BEGIN
OAUTH.delete_client(
'CLIENT_TEST'
);
COMMIT;
END;
/

6.3 OAUTH.GRANT_CLIENT_ROLE

形式

OAUTH.GRANT_CLIENT_ROLE(
p_client_name VARCHAR2 IN,
p_role_name   VARCHAR2 IN);

説明

OAuthクライアントに指定したロールを付与し、クライアントがTwo-Legged OAuthを実行して、ロールを要求する権限にアクセスできるようにします。

パラメータ

p_client_name

OAuthクライアントの名前です。

p_role_name

付与されるロールの名前です。

使用上の注意

操作を有効にするには、このプロシージャを呼び出した後でCOMMIT文を使用します。

例

次の例では、ロールを作成し、OAuthクライアントにそのロールを付与します。

BEGIN
ORDS.create_role(p_role_name => 'CLIENT_TEST_ROLE');

OAUTH.grant_client_role(
'CLIENT_TEST',
'CLIENT_TEST_ROLE'
);
COMMIT;
END;
/

6.4 OAUTH.RENAME_CLIENT

形式

OAUTH.RENAME_CLIENT(
p_name     VARCHAR2 IN,
p_new_name VARCHAR2 IN);

説明

クライアントの名前を変更します。

パラメータ

p_name

クライアントの現在の名前です。

p_new_name

クライアントの新しい名前です。

使用上の注意

クライアントの名前はThree-Legged OAuthの承認フェーズでエンド・ユーザーに表示されます。

操作を有効にするには、このプロシージャを呼び出した後でCOMMIT文を使用します。

例

次の例では、クライアントの名前を変更します。

BEGIN
OAUTH.rename_client(
'CLIENT_TEST',
'CLIENT_TEST_RENAMED'
);
COMMIT;
END;
/

6.5 OAUTH.REVOKE_CLIENT_ROLE

形式

OAUTH.REVOKE_CLIENT_ROLE(
p_client_name  VARCHAR2 IN,
p_role_name    VARCHAR2 IN);

説明

OAuthクライアントから指定したロールを削除し、クライアントがTwo-Legged OAuthを通じてロールを要求する権限にアクセスすることを防ぎます。

パラメータ

p_client_name

OAuthクライアントの名前です。

p_role_name

削除されるロールの名前です

使用上の注意

操作を有効にするには、このプロシージャを呼び出した後でCOMMIT文を使用します。

例

次の例では、OAuthクライアントから指定したロールを削除します。

BEGIN
OAUTH.revoke_client_role(
'CLIENT_TEST_RENAMED',
'CLIENT_TEST_ROLE'
);
COMMIT;
END;
/

6.6 OAUTH.UPDATE_CLIENT

形式

OAUTH.UPDATE_CLIENT(
p_name             VARCHAR2 IN,
p_description      VARCHAR2 IN,
p_origins_allowed  VARCHAR2 IN,
p_redirect_uri     VARCHAR2 IN,
p_support_email    VARCHAR2 IN,
p_suppor_uri       VARCHAR2 IN,
p_privilege_names  t_ords_vchar_tab IN);

説明

クライアント情報を更新します(名前を除く)。null値を指定すると、既存のクライアント・プロパティは変更されません。

パラメータ

p_name

所有者、説明、使用可能な起点、サポート電子メール、サポートURIおよび権限変更を要求するクライアントの名前です。

p_description

クライアントの目的の説明で、Three-Legged OAuthの承認フェーズでエンド・ユーザーに表示されます。

p_redirect_uri

OAuthアクセス・トークンまたはエラーが含まれるリダイレクトが送信されるクライアント制御URI。このパラメータがnullの場合、既存のp_redirect_uri値(存在する場合)は変更されません。

p_support_email

エンド・ユーザーがサポートを得るためにクライアントに連絡できる電子メール・アドレスです。

p_support_uri

エンド・ユーザーがサポートを得るためにクライアントに連絡できるURIです。例: http://www.myclientdomain.com/support/

p_privilege_names

クライアントがアクセスする権限の名前のリストです。

使用上の注意

操作を有効にするには、このプロシージャを呼び出した後でCOMMIT文を使用します。

クライアントの名前を変更する場合は、 OAUTH.RENAME_CLIENTプロシージャを使用します。

指定のクライアントの説明を更新する例

次の例では、p_nameの値と一致する名前を持つクライアントの説明を更新します。

BEGIN
ORDS_METADATA.OAUTH.update_client(
p_name => 'CLIENT_TEST_RENAMED',
p_description => 'The description was altered',
p_origins_allowed => null,
p_redirect_uri => null,
p_support_email => null,
p_support_uri => null,
p_privilege_names => null);
COMMIT;
END;
/

例6-1 複数の権限を追加する例

次の例は、2つめの権限を追加します。

declare
my_privs t_ords_vchar_tab  := t_ords_vchar_tab ();
begin
my_privs.EXTEND (3);
my_privs(1):='tst.privilege1';
my_privs(2):='tst.privilege2';
.
oauth.update_client(
p_name => 'Test_Client',
p_owner => 'scott',
p_description => 'Description',
p_grant_type => 'client_credentials',
p_redirect_uri => '/abc/efg/',
p_privilege_names => my_privs);
commit;
end;

関連トピック

- OAUTH.RENAME_CLIENT

A ORDSデータベース・タイプ・マッピング

この付録では、構造化されたデータベース・タイプとともに、ORDSデータベース・タイプのマッピングを説明します。

A.1 Oracle組込み型

この項では、データベース・タイプ・マッピングについて説明します。

データ型

JSONデータ型

RESTバージョン

値の例

説明

NUMBER

数値

v1

"big" : 1234567890

"bigger" : 1.2345678901e10

すべての有効数字で表されます。数が10桁を超える場合、ベキ指数が使用されます。

RAW

文字列

カスタム

"code" : "SEVMTE8gV09STEQh"

Base64ビット・エンコーディングが使用されます

DATE

文字列

v1.2

"start" : "1995-06-02T04:29:11Z"

UTCタイムゾーンではISO 8601形式を使用して表されます

TIMESTAMP

文字列

v1.2

when : "1995-06-02T04:29:11.002Z"

UTCタイムゾーンではISO 8601形式を使用して表されます

TIMESTAMPWITHLOCALTIMEZONE

文字列

v1.2

"at" : "1995-06-02T04:29:11.002Z"

ISO 8601の形式を使用して表されます。ローカル・タイムゾーン仕様は転送エンコーディングには適用されないため、ローカル・タイムゾーンがUTCタイムゾーンに変換されます。

CHAR

文字列

v1

"message" : "Hello World! "

後続するスペースで表されます。これは、PUTまたはPOSTメソッド用の充填物として必要とされる場合があります。例, "abc ".

ROWID

文字列

カスタム

"id" : "AAAGq9AAEAAAA0bAAA"

ネイティブのOracleテキスト表現としての出力。たとえば、次の変換と同等: SELECT ROWIDTOCHAR(id) id FROM DUAL。

UROWID

文字列

カスタム

"uid" : "AAAGq9AAEAAAA0bAAA"

ネイティブのOracleテキスト表現としての出力。たとえば、次の変換と同等: SELECT CAST(uid as VARCHAR(4000)) id FROM DUAL。

FLOAT

数値

v1

*as NUMBER

NCHAR

文字列

v1

"message" : "Hello World! "

文字がボディ・キャラクタ・セットによってサポートされない場合にユニコード文字を使用して表されます。

NVARCHAR2

文字列

v1

"message" : "Hello World! "

文字がボディ・キャラクタ・セットによってサポートされない場合にユニコード文字を使用して表されます。

VARCHAR2

文字列

v1

"message" : "Hello World! "

BINARY_FLOAT

数値

v1

*as NUMBER

BINARY_DOUBLE

数値

v1

*as NUMBER

TIMESTAMPWITHTIMEZONE

オブジェクト

v1.2

"event" : "1995-06-02T04:29:11.002Z"
"when" : "1995-06-02T04:29:11.002Z"

UTCタイムゾーンではISO 8601形式を使用して表されます値は同じ時点を表しますが、元のタイムゾーンは失われます。

INTERVALYEARTOMONTH

オブジェクト

カスタム

"until" : "P-123Y3M"
"until" : "P3M"

ISO 8601の「期間」の形式を使用して表されます。期間が0のコンポーネントは、オプションとみなされます。

INTERVALDAYTOSECOND

オブジェクト

カスタム

"until" : "P-5DT3H55M"
"until" : "PT3H55M"

ISO 8601の「期間」の形式を使用して表されます。期間が0のコンポーネントは、オプションとみなされます

LONG

文字列

v1

*as VARCHAR

LONG RAW

文字列

カスタム

"long_code" : { "SEVMTE8gV09STEQh"

BLOB

文字列

カスタム

"bin" : {
"base64_value" : "bGVhc3VyZS4="
}

CLOB

文字列

カスタム

"text" : {
"value" : "Hello World!
"
}

BFILE

オブジェクト

カスタム

"file" : {
"locator" : "TARGET_DIR",
"filename" : "myfile"
}

BOOLEAN

true|false

v1

"right" : true"
wrong" : false

A.2 構造化されたデータベース・タイプの処理

この項では、構造化されたデータベース・タイプがどのように処理されるかを説明します。

オブジェクト・タイプ

これの例外は、ORDSがGeoJSONなど業界標準のタイプとして受け入れられているエンコーディングを採用した場合です。

サンプル・コード・スニペットを次に示します。

"address" : {

"number" : 42,

"street" : "Wallaby Way",

"city" : "Sydney"

}

継承

オブジェクト型の継承はサポートされません。マーシャリング目的で、オブジェクト型はすべて、残された具体的な型であるように扱われます。

PL/SQLレコード

PL/SQLレコードはサポートされていません。

VARRAYS

VARRAYSは、JSON配列型に直接マップされます。

サンプル・コード・スニペットを次に示します。

"addresses" : [

{

"__db_type" : "MY_SCHEMA.AUS_ADDRESS",

"number" : 42,

"street" : "Wallaby Way",

"city" : "Sydney"

},

{

"__db_type" : "MY_SCHEMA.UK_ADDRESS"

"number : 1,

"street" : "Oracle Parkway"

"city" : "Reading"

"postcode" : "RG6 1RA"

}

]

要素の継承

VARRAY要素インスタンスの型が定義された型のサブタイプである場合、オブジェクト型の項で説明されているように、__db_typeという名前の値を追加することが必須になります。

連想配列

連想配列(以前はPL/SQL表または索引付き表と呼ばれていました)は、次の2つのカテゴリに分けられます。

- 整数値による索引付け: 移入されたデータが少ない索引付けられた配列。この型の配列は、指定の索引に値を提供しない場合があります。この型の配列とJSONの間で変換が行われる場合、索引は無視され、索引付け可能な値ギャップは削除されます。これには、PL/SQLプロシージャを介してIN/OUTパラメータとして渡された、変更のない移入データの少ない索引付き配列が、索引付け可能な値ギャップが削除されたために、変更されたように見えるという副作用があります。
サンプル・コード・スニペットを次に示します。

"avg_values" : [

34,

57,

86,

3235

]
:

- 整数値によって索引付けられていない: たとえば、VARCHAR。このカテゴリは、Oracle JDBC APIではめったに使用されないため、サポートされません。

A.3 Oracle Geospacial Encoding

Oracle Geospacial型には、事前に定義されたOracleオブジェクト型より多くのものが含まれます。ただし、JSONエンコード・コールを認識すると、インスタンス・データのエンコードにはGeoJSONが使用されます。

関連トピック

- GeoJSON標準ドキュメント

A.4 データベース・マッピング・サポートの有効化

この項では、拡張データベース・マッピング・サポートを有効化する方法を示します。

拡張データベース・マッピング・サポートを有効化するには、次のコード・スニペットをORDS defaults.xmlファイル(ORDS構成ordsディレクトリにあります)に追加する必要があります。

<entry key="misc.datatypes.enable">true</entry>

B Oracle REST Data Servicesの構成ファイルについて

この項では、Oracle REST Data Servicesの構成ファイルについて説明します。

トピック:

- 構成ファイルの検索

- 構成ファイルの場所を設定する

- 構成フォルダの構造を理解する

- 構成ファイルの形式を理解する

- 構成可能なパラメータを理解する

B.1 構成ファイルの検索

構成ファイルの現在の場所を表示するには、次のようにconfigdirコマンドを使用します。

java -jar ords.war configdir

構成フォルダが構成されていない場合は、「config.dir設定が設定されていません」というメッセージが表示されます。設定されている場合は、現在の設定値が表示されます。

B.2 構成ファイルの場所を設定する

構成フォルダの場所を変更するには、次のようにconfigdirコマンドを使用します。

java -jar ords.war configdir </path/to/config>

説明:

- </path/to/config>は、構成ファイルが格納されている場所です。

B.3 構成フォルダの構造を理解する

構成フォルダの構造は次のとおりです。

./
|
+-defaults.xml
+-apex.properties*
+-url-mapping.xml
|
+conf/
|
+-apex.xml
+-apex_al.xml
+-apex_rt.xml
+-apex_pu.xml
|
...
+-(db-name).xml
+-(db-name)_al.xml
+-(db-name)_rt.xml
+-(db-name)_pu.xml

defaults.xmlには、すべてのデータベース接続に適用されるグローバル設定が格納されています。

conf/<db-name>.xmlには、特定のデータベース接続(たとえば、デフォルトのapex接続)に固有の設定が格納されています。<db-name>は、データベース接続の名前です。

データベース接続がOracle Application ExpressのRESTfulサービスを使用する場合、_al.xml、_rt.xmlおよび_pu.xmlなどの名前のファイルが、APEX_LISTENER、APEX_REST_PUBLIC_USERおよびORDS_PUBLIC_USERのデータベース・ユーザー用の構成をそれぞれ格納します。

データベース接続がOracle REST Data ServicesのRESTfulサービスを使用する場合、<db-name>_pu.xmlファイルがORDS_PUBLIC_USERデータベース・ユーザーの構成を格納します。

B.4 構成ファイルの形式を理解する

構成ファイルは、各構成設定がキーおよびそれに対応する値からなる標準のJava XMLプロパティ・ファイル形式を使用します。defaults.xmlファイルの例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>

<entry key="db.connectionType">basic</entry>
<entry key="db.hostname">localhost</entry>
<entry key="db.port">1521</entry>
<entry key="db.sid">orcl</entry>

<entry key="jdbc.DriverType">thin</entry>
<entry key="jdbc.InitialLimit">3</entry>
<entry key="jdbc.MinLimit">1</entry>
<entry key="jdbc.MaxLimit">10</entry>
<entry key="jdbc.MaxStatementsLimit">10</entry>
<entry key="jdbc.InactivityTimeout">1800</entry>
<entry key="jdbc.statementTimeout">900</entry>
<entry key="jdbc.MaxConnectionReuseCount">1000</entry>

</properties>

B.4.1 url-mapping.xmlファイルの形式を理解する

複数のデータベースが構成されている場合、url-mapping.xmlファイルにリクエストを適切なデータベースにルーティングするルールが格納されます。url-mapping.xmlファイルの例を次に示します。

<pool-config xmlns="http://xmlns.oracle.com/apex/pool-config">
<pool name="sales_db"
base-path="/sales"
workspace-id="sales_rest"/>
</pool-config>

B.5 構成可能なパラメータの理解

表B-1に、defaults.xmlおよび(db-name).xml構成ファイルの編集可能なパラメータを示します。

ヒント:

構成ファイルの編集には、Oracle REST Data Servicesのコマンドライン・インタフェースおよびOracle SQL DeveloperのOracle REST Data Services Administrationを使用することをお薦めします。

表B-1 Oracle REST Data Servicesの構成ファイルのパラメータ

キー

型

説明

例

apex.docTable

文字列

Application Expressによって使用されるドキュメント表の名前。

デフォルトは、FLOWS_FILES.WWV_FLOW_FILE_OBJECTS$です。

MYDOCTABLE

apex.excel2collection

ブール値

Oracle Application ExpressのコレクションにExcelファイルを配置するかどうかを指定します。

サポートされている値:

- true

- false (デフォルト)

trueの場合、apex.excel2collection.onecollectionまたはapex.excel2collection.useSheetNameのいずれかをtrueに設定する必要があります。

false

apex.excel2collection.name

文字列

apexコレクションの名前。apex.excel2collection.onecollectionがtrueの場合にこの名前が必要です。

mycollection

apex.excel2collection.onecollection

ブール値

すべてのExcelワークシートを単一のコレクションに配置するかどうかを指定します。

サポートされている値:

- true

- false (デフォルト)

false

apex.excel2collection.useSheetName

ブール値

各Excelワークシート用のコレクションを作成するかどうかを指定します(ワークシート名を対応するコレクション名に使用します)。

サポートされている値:

- true

- false (デフォルト)

false

cache.caching

ブール値

サポートされている値:

- true

- false (デフォルト)

キャッシングを有効にするにはtrueに設定する必要があり、procedureNameListにプロシージャが必要です。

true

cache.directory

文字列

キャッシュ・ファイルのディレクトリの場所。

C:\data\cachefiles

cache.duration

文字列

サポートされている値:

- days (デフォルト)

- minutes

- hours

期限切れキャッシュ・タイプの場合は必須。

days

cache.expiration

数値

期限切れキャッシュ・タイプの場合は必須。

デフォルトは7です。

7

cache.maxEntries

数値

LRUキャッシュ・タイプの場合は必須。

デフォルトは500です。

500

cache.monitorInterval

数値

期間を分単位で指定します。

キャッシュ・タイプが期限切れの場合、Oracle REST Data Servicesは、期限の切れたファイルのすべてのキャッシュをNN分間隔でチェックします。たとえば、monitorIntervalが60の場合、キャッシュは60分ごとにチェックされます。

デフォルトは60です。

60

cache.procedureNameList

文字列

ファイルのキャッシュを許可するプロシージャ名を指定します。

プロシージャ名には、ワイルドカード文字のアスタリスク(*)または疑問符(?)を含めることができます。0文字以上の文字の置換にアスタリスク(*)を、任意の1文字の置換に疑問符(?)を使用します。

各プロシージャ名は、カンマで区切る必要があります。

p, download_file

cache.type

文字列

サポートされている値:

- expire

- lru (デフォルト)

lru

db.connectionType

文字列

接続のタイプ。サポートされている値:

- basic

- tns

- customurl

basic

db.customURL

文字列

データベースに接続するためのJDBC URL接続。

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP) (HOST=myhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=ora111.example.com)))

db.hostname

文字列

Oracleデータベースのホスト・システム。

myhostname

db.password

文字列

指定されたデータベース・ユーザーのパスワード。暗号化して保存できるように、パスワードの先頭に感嘆符を含めます。

!password4user

db.port

数値

データベース・リスナー・ポート。

1521

db.servicename

文字列

データベースのネットワーク・サービス名。

ora111.example.com

db.serviceNameSuffix

文字列

プールがCDBを指すこと、およびそのCDBに接続しているPDBをOracle REST Data Servicesによってアドレス可能にする必要があることを示します(「Oracle REST Data Servicesによって、すべてのPDBをアドレス可能にする(プラガブル・マッピング)」を参照)。

apex_pu

db.sid

文字列

データベースの名前。

ora111

db.tnsAliasName

文字列

tnsnames.oraファイル内の名前と一致するTNSの別名。

MY_TNSALIAS

db.tnsDirectory

文字列

tnsnames.oraファイルのディレクトリの場所。

C:\ORACLE\NETWORK\ADMIN

db.username

文字列

接続のデータベース・ユーザーの名前。

APEX_PUBLIC_USER

debug.debugger

ブール値

アプリケーション・サーバーのコンソールにデバッグ・メッセージを表示するかどうかを指定します。

サポートされている値:

- true

- false (デフォルト)

false

debug.printDebugToScreen

ブール値

ブラウザ上でエラーメッセージを表示するかどうかを指定します。

サポートされている値:

- true

- false (デフォルト)

false

error.keepErrorMessages

ブール値

エラー・メッセージを保持するかどうかを指定します。

サポートされている値:

- true

- false (デフォルト)

true

error.maxEntries

数値

保持するエラー・メッセージの合計数を指定します。

デフォルトは50です。

50

icap.port

数値

ウイルス・スキャン・ファイルへのInternet Content Adaptation Protocol(ICAP)ポートを指定します。

icap.portの値は必須です。

5555

icap.server

文字列

ウイルス・スキャン・ファイルへのInternet Content Adaptation Protocol(ICAP)サーバーの名前を指定します。

icap.serverの値は必須です。

servername

jdbc.DriverType

文字列

JDBCドライバのタイプ。サポートされている値:

- thin

- oci8

thin

jdbc.InactivityTimeout

数値

閉じられる前に、利用可能な接続がアイドル状態を維持できる時間を指定します。非アクティブな接続のタイムアウトは秒単位です。

デフォルトは1800です。

1800

jdbc.InitialLimit

数値

作成される接続の数の初期サイズを指定します。

デフォルトは3です。(デフォルトは低いため、ほとんどの本番環境ではおそらくこれより高く設定すべきです。)

10

jdbc.MaxConnectionReuseCount

数値

破棄され、新規の接続と置き換わる前に、接続を再利用する最大回数を指定します。

デフォルトは1000です。

1000

jdbc.MaxLimit

数値

接続の最大数を指定します。

デフォルトは10です。(一部の本番環境では低すぎる可能性があります。)

20

jdbc.maxRows

数値

RESTfulサービスの処理で問合せから戻される、結果セットのネストしたカーソルから戻される行の最大数を指定します。リソースがページ分割されているかどうかにかかわらず、SQL問合せを使用して生成されるすべてのRESTfulサービスに影響します。

デフォルトは500です。

300

jdbc.MaxStatementsLimit

数値

接続ごとにキャッシュする文の最大数を指定します。

デフォルトは10です。

10

jdbc.MinLimit

数値

接続の最小数を指定します。

デフォルトは1です。

1

jdbc.statementTimeout

数値

流用した(使用中の)接続が、中止および再要求とみなされるまでの、未使用の時間を指定します。中止された接続のタイムアウトは秒単位です。

デフォルトは900です。

900

log.logging

ブール値

ログ・メッセージを保持するかどうかを指定します。

サポートされている値:

- true

- false (デフォルト)

true

log.maxEntries

数値

保持するログ・メッセージの合計数を指定します。

デフォルトは50です。

50

log.procedure

ブール値

プロシージャをログに記録するかどうかを指定します。

サポートされている値:

- true

- false (デフォルト)

false

misc.defaultPage

文字列

表示するデフォルトのページ。一般的には、Oracle REST Data Servicesのホームページのapexが使用されます。

apex

procedure.postProcess

文字列

URLで指定されたプロシージャを実行した後に実行するプロシージャ名(複数可)を指定します。複数のプロシージャ名はカンマで区切ります。

SCHEMA1.SUBMIT.REQUEST,FINISHTASK

procedure.preProcess

文字列

URLで指定されたプロシージャを実行する前に実行するプロシージャ名(複数可)を指定します。複数のプロシージャ名はカンマで区切ります。

SCOTT.PREPROC1, INITIALIZE, PKG1.PROC

security.disableDefaultExclusionList

ブール値

サポートされている値:

- true

- false (デフォルト)

false

security.exclusionList

文字列

ブラウザから直接実行することが禁じられているプロシージャ、パッケージまたはスキーマ名のパターンを指定します。

プロシージャ名には、ワイルドカード文字のアスタリスク(*)または疑問符(?)を含めることができます。0文字以上の文字の置換にアスタリスク(*)を、任意の1文字の置換に疑問符(?)を使用します。

注意: 複数のパターンはカンマで分割します。

customer_account,bank*, employe?

security.inclusionList

文字列

ブラウザから直接実行することが許可されているプロシージャ、パッケージまたはスキーマ名のパターンを指定します。

プロシージャ名には、ワイルドカード文字のアスタリスク(*)または疑問符(?)を含めることができます。0文字以上の文字の置換にアスタリスク(*)を、任意の1文字の置換に疑問符(?)を使用します。

注意: 複数のパターンはカンマで分割します。

apex, p, v, f, wwv_*, y*, c*

security.maxEntries

数値

最大キャッシュ・サイズを指定します。

デフォルトは2000です。

2000

security.requestValidationFunction

文字列

URLでリクエストされたプロシージャの処理を許可するかどうかを判断するための検証関数を指定します。この関数は、プロジェクトを許可する場合はtrueを戻し、そうでない場合はfalseを戻す必要があります。

CHECK_VALID_PROCEDURE

security.verifySSL

ブール値

その環境でHTTPSが利用可能かどうかを示します。

サポートされている値:

- true (デフォルト)

- false

この値をfalseに変更する場合は、「非HTTPS環境でOAuth2の使用」を参照してください。

true

soda.defaultLimit

文字列

SODA REST APIを使用しているときに、制限がURLで指定されていない場合、コレクションのGETリクエストに返されるデフォルトのドキュメント数を指定します。正の整数または、制限をなくす「無制限」である必要があります。

デフォルトは100です。

75

soda.maxLimit

文字列

SODA REST APIを使用しているときに、URLで指定された制限にかかわらず、コレクションURLでGETリクエストに返されるドキュメントの最大数を指定します。正の整数または、制限をなくす「無制限」である必要があります。

デフォルトは1000です。

700

関連項目:
詳細は、「Oracle REST Data Servicesの構成およびインストール」および『Oracle SQL Developerユーザーズ・ガイド』のOracle REST Data Servicesの管理に関する項を参照してください。

C Oracle REST Data Servicesのトラブルシューティング

この付録では、Oracle REST Data Servicesのトラブルシューティングについて説明します。

トピック:

- デバッグ・トレースの有効化

- 詳細なリクエスト・エラー・メッセージの有効化

- Oracle REST Data ServicesでのApplication Expressの静的リソースの構成

C.1 デバッグ・トレースの有効化

デバッグ・トレースを有効にするには、defaults.xmlという名前のOracle REST Data Servicesの構成ファイルに次の設定を追加します。

<entry key="debug.debugger">true</entry>

この設定がdefaults.xmlの中に存在すると、問題の診断に役立つ詳細なログ情報がOracle REST Data Servicesのログ出力に追加されます。ログへの大量のデータ出力によるパフォーマンスへの影響のため、本番システムではこのオプションを有効にしないでください。

C.2 詳細なリクエスト・エラー・メッセージの有効化

詳細なリクエスト・エラー・メッセージを有効にするには、defaults.xmlという名前のOracle REST Data Servicesの構成ファイルに次の設定を追加します。

<entry key="debug.printDebugToScreen">true</entry>

この設定がdefaults.xmlの中に存在すると、任意のリクエストの生成するエラー・レスポンスにスタック・トレースを含む詳細なメッセージが含まれます。機密情報が攻撃者に漏れるリスクがあるため、この設定は本番システムでは有効にしないでください。

C.3 Oracle REST Data ServicesでのApplication Expressの静的リソースの構成

Oracle REST Data Servicesを使用していて、Oracle Application Expressのページにアクセスしようとすると(たとえば、https://example/ords/を表示しようとすると)空白のページが表示されることがあります。この問題の原因はApplication Expressの静的リソースの不適切な構成にあり、そのためにApplication Expressで必要とするJavaScriptおよびCSSリソースが見つからず、Application Expressのページが正しくレンダリングされません。

具体的な原因として、次のいずれかが考えられます。

- Application Expressの静的イメージがOracle REST Data Servicesのインスタンスと同じサーバーに配置されていることを確認していない。

- WebLogic ServerまたはGlassFishにi.warをデプロイしていない。

- java -jar ords.war staticコマンドを使用してi.warを生成するときに、誤ったパスを指定した。

- 静的リソース(/i)にデフォルト以外のコンテキスト・パスを使用してApplication Expressを構成し、java -jar ords.war staticを使用するときに、それと同じコンテキスト・パスを指定していない(--context-pathオプションを使用する)。

- i.warをデプロイした後で、i.warから参照しているフォルダを移動、名前の変更、または削除した。

- スタンドアロン・モードで実行していて、スタンドアロン・モードの最初の実行時にメッセージが表示されたときに、誤ったパスを入力した(またはパスを指定しなかった)。

- スタンドアロン・モードで実行していて、--static-imagesオプションに誤ったパスを入力した。

- Application Expressを新規バージョンにアップグレードしたが、Application Expressの新規バージョンの静的リソースを指すように i.warを再構成および再デプロイしていないか、またはスタンドアロン・モードで--apex-imagesオプションを使用して場所を更新していない。

問題の診断に役立てるため、apex_version.txtファイルにアクセスしてみることができます。たとえば、Application Expressのデプロイがhttps://example.com/ords/にあり、静的リソースがhttps://example.com/i/にデプロイされている場合、ブラウザを使用して次のURLにアクセスします。

https://example.com/i/apex_version.txt

「404 見つかりません」というエラーになる場合は、i.warがデプロイされていない、Application Expressの静的リソースを含むフォルダを指していない、といった前述の具体的な原因のリストをチェックします。

プレーン・テキストのファイルが表示される場合は、次のようなテキストが含まれているはずです。

Application Express Version:  4.2.1

このバージョン番号がデータベースにデプロイされているApplication Expressのバージョンと一致していることを確認してください。番号が一致しない場合は、Oracle REST Data Servicesがデータベース内のApplication Expressのバージョンと一致するApplication Expressの静的リソースの正しいバージョンを使用するように構成されていないので、前述の具体的な原因リストの最後の項目で説明した誤りがないかを確認してください。

問題を解決する上でのヘルプを必要とする場合は、WebLogic ServerやGlassfishなどのご使用環境でのi.warの作成およびデプロイについて、本書内の情報をチェックしてください。

また、コマンド・プロンプトで次のように入力して、静的リスナー・コマンドの詳細なヘルプを表示できます。

java -jar ords.war help static

D 開発チュートリアル: イメージ・ギャラリの作成

この付録では、拡張的な例として、イメージを格納および取得するためのイメージ・ギャラリ・サービスの構築を説明します。このチュートリアルでは、Oracle Application Expressを使用します。

トピック:

- 作業を開始する前に

- ギャラリ・データベース表の作成

- ギャラリRESTfulサービス・モジュールの作成

- ギャラリRESTfulサービスの試用

- ギャラリ・アプリケーションの作成

- ギャラリ・アプリケーションの試用

- ギャラリRESTfulサービスの保護

- サード・パーティ・アプリケーションからのRESTfulサービスへのアクセス

関連項目:

このチュートリアルを行うには、「Oracle REST Data Servicesアプリケーションの開発」で取り上げた概念と技術をよく理解している必要があります。

D.1 はじめに

この項では、APIエントリ・ポイントに関するベスト・プラクティスに加え、この例で使用するいくつかの一般的な規則についても説明します。

トピック:

- URIについて

- ブラウザのサポートについて

- Application Expressワークスペースの作成

D.1.1 URIについて

この例全体にわたって、URIおよびURIテンプレートは、ホスト名、コンテキスト・ルートおよびワークスペースのパス接頭辞を省略した形で表記しています。次に例を示します。

gallery/images/

WebブラウザでこのURIにアクセスするには、次の形式でURIを使用します。

https://<host>:<port>/ords/<workspace>/gallery/images/

説明:

- <host>は、Oracle REST Data Servicesが実行されるホストです。

- <port>は、Oracle REST Data Servicesがリスニング中のポートです。

- /ordsは、Oracle REST Data Servicesがデプロイされるコンテキスト・ルートです。

- /<workspace>/は、RESTfulサービスが定義されるOracle Application Expressワークスペースのワークスペース・パス接頭辞です。

D.1.2 ブラウザのサポートについて

この例では、HTML5および関連する仕様で定義されている多くの最新機能を使用しています。Mozilla FirefoxおよびGoogle Chromeでのみテストされています。Microsoft Internet Explorerまたはスマートフォン/タブレットのWebブラウザではテストされていません。この例では、Mozilla FirefoxまたはGoogle Chromeのいずれかの最新バージョンを使用してください。

D.1.3 Application Expressワークスペースの作成

ギャラリの例のアプリケーションおよび関連オブジェクトの作成は、次の指示に従い、まずOracle Application Expressのワークスペースを作成します(完全開発モードで)。詳細は、Oracle Application Expressのドキュメントを参照してください。

ワークスペースresteasyを呼出し、このワークスペースの管理者ユーザーresteasy_adminを呼び出します。resteasy_adminユーザーがRESTful Servicesユーザー・グループのメンバーであることを確認します。

D.2 ギャラリ・データベース表の作成

ギャラリ・データベース表を作成するには、次の手順を実行します。

1. resteasyワークスペースにログインします。

2. 「SQLワークショップ」に移動して、「SQLコマンド」に移動します。

3. 次のSQLを入力するかコピーして貼り付けます。

CREATE SEQUENCE GALLERY_SEQ
/
CREATE TABLE GALLERY (
ID NUMBER NOT NULL ENABLE,
TITLE VARCHAR2(1000) NOT NULL ENABLE,
CONTENT_TYPE VARCHAR2(1000) NOT NULL ENABLE,
IMAGE BLOB NOT NULL ENABLE,
CONSTRAINT GALLERY_PK PRIMARY KEY (ID) ENABLE
)
/
CREATE OR REPLACE TRIGGER BI_GALLERY
before insert on GALLERY for each row
begin
if :NEW.ID is null then
select GALLERY_SEQ.nextval into :NEW.ID from sys.dual;
end if;
end;
/
ALTER TRIGGER BI_GALLERY ENABLE
/

D.3 ギャラリRESTfulサービス・モジュールの作成

ギャラリRESTfulサービス・モジュールを作成するには、次の手順を実行します。

1. 「SQLワークショップ」に移動し、「RESTfulサービス」に移動します。

2. 右側の「作成」をクリックし、次の情報を入力します。

- 名前: gallery.example

- URI接頭辞: gallery/

- URIテンプレート: images/

- メソッド: POST

- ソース: 次のように入力するかコピーして貼り付けます。

declare
image_id integer;
begin
insert into gallery (title,content_type,image)
values  (:title,:content_type,:body)
returning id into image_id;
:status := 201;
:location := image_id;
end;

3. 「モジュールの作成」をクリックします

4. images/の下のPOSTハンドラをクリックします。

5. 「セキュア・アクセスが必要」で、「いいえ」を選択します。

6. 「パラメータの作成」をクリックし、次にように入力します。

- 名前: Slug

- バインド変数名: title

7. 「作成」をクリックします。

8. 右下の「パラメータの作成」をクリックし、次の情報を入力します。

- 名前: X-APEX-FORWARD

- バインド変数名: location

- アクセス方法: OUT

9. 「作成」をクリックします。

10. 右下の「パラメータの作成」をクリックし、次の情報を入力します。

- 名前: X-APEX-STATUS-CODE

- バインド変数名: status

- アクセス方法: OUT

- パラメータ・タイプ: Integer

11. 「作成」をクリックします。

この時点で、新規イメージを格納できる単一のサービスを持つモジュールが作成できました。次に、格納されているイメージの一覧を表示するサービスを追加します。

1. 「SQLワークショップ」に移動し、「RESTfulサービス」に移動します。

2. gallery.exampleという名前のモジュールをクリックします。

3. images/の下の「ハンドラの作成」をクリックし、次の情報を入力します。

- メソッド: GET

- ソース・タイプ: Feed

- セキュア・アクセスが必要: No

- ソース: 次のように入力するかコピーして貼り付けます。

select id,title,content_type from gallery order by id desc

4. 「作成」をクリックします。

この時点で、イメージを格納およびリストするサービスが作成できました。次に、個別のイメージを表示するサービスを追加します。

1. 「SQLワークショップ」に移動し、「RESTfulサービス」に移動します。

2. gallery.exampleという名前のモジュールをクリックします。

3. gallery.exampleの下の「テンプレートの作成」をクリックし、次の情報を入力します。

- URIテンプレート: images/{id}

4. 「作成」をクリックします。

5. images/{id}の下の「ハンドラの作成」をクリックし、次の情報を入力します。

- メソッド: GET

- ソース・タイプ: Media Resource

- セキュア・アクセスが必要: No

- ソース: 次のように入力するかコピーして貼り付けます。

select content_type, image from gallery where id = :id

6. 「作成」をクリックします。

D.4 ギャラリRESTfulサービスの試用

ギャラリRESTfulサービスを試用するには、次の手順を実行します。

1. 「SQLワークショップ」に移動し、「RESTfulサービス」に移動します。

2. gallery.exampleという名前のモジュールをクリックします。

3. images/の下のGETハンドラをクリックします。

4. 「テスト」をクリックします。

次のURIがブラウザに表示されるはずです。

https://<host>:<port>/ords/resteasy/gallery/images/

次のような内容が表示されるはずです。

{"next":
{"$ref":
"http://localhost:8080/ords/resteasy/gallery/images/?page=1"
},
"items":[]
}

- 内容はギャラリ内の各イメージの場所を示すJSONドキュメントですが、まだイメージを追加していないのでリスト(items[]の要素)は空です。

- JSONはそのサイズを最小化するために余分な空白がなく、解読が困難なので、JSONの閲覧を容易にするため、ブラウザにJSON表示プラグインを追加することをお薦めします。

ユーザーがギャラリにイメージを追加および表示できるOracle Application Expressアプリケーションを作成するには、「ギャラリ・アプリケーションの作成」を参照してください。

D.5 ギャラリ・アプリケーションの作成

ギャラリRESTfulサービスを使用するOracle Application Expressアプリケーションを作成するには、次の手順を実行します。

1. Application Builderに移動します。

2. 「作成」をクリックします。

3. 「データベース」を選択し、「次へ」をクリックします。

4. 「名前」フィールドにImage Galleryと入力し、「次へ」をクリックします。

5. 「アプリケーションの作成」をクリックし、アプリケーションの作成を確認するため再び「アプリケーションの作成」をクリックします。

6. 「1ページ」、「ホーム」をクリックします。

7. 「リージョン」の下で、「+(プラス記号)」アイコンをクリックして新規リージョンを作成します。

8. 「リージョン・タイプ」で「HTML」を選択し、「次へ」をクリックし、次のページで「次へ」をクリックします。

9. リージョン・テンプレートで、「テンプレートなし」を選択します。

10. 「タイトル」にTasksと入力し、「次へ」をクリックします。

11. リージョン・ソースのHTMLテキストの入力で、次のように入力します。

<a class="button" id="upload-btn">Upload Image</a>

12. 「リージョンの作成」をクリックします。

13. 「リージョン」の下で、「+(プラス記号)」アイコンをクリックして新規リージョンを作成します。

14. 「リージョン・タイプ」で「HTML」を選択し、「次へ」をクリックし、再び「次へ」をクリックします。

15. リージョン・テンプレートで、DIVリージョンとIDを選択します。

16. 「タイトル」にImagesと入力します。

17. 「リージョンの作成」をクリックします。

18. 「Images」リージョンをクリックし、「属性」タブをクリックします。

19. 「静的ID」にimagesと入力し、「変更の適用」をクリックします。

20. 「ページ」の下で、編集アイコンをクリックし、「JavaScript」タブをクリックします。

21. 関数およびグローバル変数の宣言で、次のように入力するかコピーして貼り付けます。

var workspace_path_prefix = 'resteasy';
var gallery_url = './' + workspace_path_prefix + '/gallery/images/';
function uploadFiles(url, fileOrBlob, onload) {
var name = 'unspecified';
if ( fileOrBlob['name'] ) {
name = fileOrBlob.name;
}
var xhr = new XMLHttpRequest();
xhr.open('POST', url, true);
xhr.setRequestHeader('Slug',name);
xhr.onload = onload;
xhr.send(fileOrBlob);
}

function createUploader() {
var $upload = $('<div id="uploader" title="Image Upload"\
style="display:none">\
<form>\
<fieldset>\
<label for="file">File</label>\
<input type="file" name="file" id="file"\
class="text ui-widget-content ui-corner-all"/>\
</fieldset>\
</form>\
</div>');
$(document.body).append($upload);
$upload.dialog({
autoOpen:false,
modal: true,
buttons: {
"Upload": function() {
var file = document.querySelector('input[type="file"]');
uploadFiles(gallery_url,file.files[0],function() {
$('#uploader').dialog("close");
getImages();
});
},
"Cancel": function() {
$('#uploader').dialog("close");
}
}
});
$('#upload-btn').click(function() {
$('#uploader').dialog("open");
});
}

function getImages() {
var xhr = new XMLHttpRequest();
xhr.open('GET', gallery_url);
xhr.onload = function(e) {
var data = JSON.parse(this.response);
$('#image-list').remove();
var $images = $('<ol id="image-list"></ol>');
for ( i in data.items ) {
var item = data.items[i];
var uri = item.uri['$ref'];
var $image = $('<li></li>')
.append('<a href="' + uri + '" + title="' +
item.title + '"><img src="graphics/'+ uri +
'"></a>');
$images.append($image);
}
$('#images').append($images);
}
xhr.send();
}

22. 「ページ・ロード時に実行」では、次の中に入力するかコピーして貼り付けます。

createUploader();
getImages();

23. 「変更の適用」をクリックします。

24. 「ページ」の下で、編集アイコンをクリックし、「CSS」タブをクリックします。

25. 「インライン」で、次のように入力するかコピーして貼り付けます。

a img { border:none; }
#images ol { margin: 1em auto; width: 100%; }
#images li { display: inline; }
#images a { background: #fff; display: inline; float: left;
margin: 0 0 27px 30px; width: auto; padding: 10px 10px 15px;
textalign: center; text-decoration: none; color: #333;
font-size: 18px; -webkit-box-shadow: 0 3px 6px rgba(0,0,0,.25);
-moz-boxshadow: 0 3px 6px rgba(0,0,0,.25); }
#images img { display: block; width: 190px; margin-bottom: 12px; }
label {font-weight: bold; text-align: right;float: left;
width: 120px; margin-right: 0.625em; }
label :after {content(":")}
input, textarea { width: 250px; margin-bottom: 5px;textalign: left}
textarea {height: 150px;}
br { clear: left; }
#images a:after { content: attr(title); }
.button {
border-top: 1px solid #96d1f8;
background: #65a9d7;
background:
-webkit-gradient(linear,left top,left bottom,
from(#3e779d),to(#65a9d7));
background:
-webkit-linear-gradient(top, #3e779d, #65a9d7);
background:
-moz-linear-gradient(top, #3e779d, #65a9d7);
background: -ms-linear-gradient(top, #3e779d, #65a9d7);
background: -o-linear-gradient(top, #3e779d, #65a9d7);
padding: 5px 10px;
-webkit-border-radius: 8px;
-moz-border-radius: 8px;
border-radius: 8px;
-webkit-box-shadow: rgba(0,0,0,1) 0 1px 0;
-moz-box-shadow: rgba(0,0,0,1) 0 1px 0;
box-shadow: rgba(0,0,0,1) 0 1px 0;
text-shadow: rgba(0,0,0,.4) 0 1px 0;
color: white;
font-size: 14px;
text-decoration: none;
vertical-align: middle;
}

.button:hover {
border-top-color: #28597a;
background: #28597a;
color: #ccc;
cursor: pointer;
}

.button:active {
border-top-color: #1b435e;
background: #1b435e;
}

26. 「変更の適用」をクリックします。

D.6 ギャラリ・アプリケーションの試用

ギャラリ・アプリケーションを試用するには、次の手順を実行します。

1. Application Builderに移動します。

2. イメージ・ギャラリ・アプリケーションの横にある「実行」をクリックします。

3. resteasy_adminユーザーとしてログインします。

4. 「イメージのアップロード」をクリックします。

5. イメージ・ファイル(JPEGまたはPNGファイル)を選択して「アップロード」をクリックします。

アプリケーションにより、アップロードされたイメージが表示されます。

D.7 ギャラリRESTfulサービスの保護

イメージ・アップロード・サービスへのパブリック・アクセスを許可するのは賢明ではなく、ギャラリ内のイメージへのパブリック・アクセスを許可するのもまた理想的なことではありません。そのため、RESTfulサービスへのアクセスを保護する必要があります。

RESTfulサービスは、2種類の認証をサポートしています。

- ファースト・パーティ認証。Application Expressアプリケーションが簡単に保護されたRESTfulサービスを消費できるように、RESTfulサービスを作成したパーティによって使用されることを意図した認証です。アプリケーションはRESTfulサービスとともに配置する、つまり、同じOracle Application Expressワークスペースに配置する必要があります。アプリケーションは、標準のOracle Application Express認証を使用する必要があります。

- サード・パーティ認証。これは、RESTfulサービスを作成したパーティとは関連しない、サード・パーティ・アプリケーションによって使用されることを意図した認証です。サード・パーティ認証は、OAuth 2.0プロトコルを利用しています。

トピック:

- RESTfulサービスの保護

- ファースト・パーティ認証を使用するためのアプリケーションの変更

D.7.1 RESTfulサービスの保護

RESTfulサービスを保護するには、次の手順を実行します。

1. 「SQLワークショップ」に移動し、「RESTfulサービス」に移動します。

2. 「タスク」というラベルのセクションで、RESTfulサービスの権限をクリックします。

3. 「作成」をクリックし、次のように入力します。

- 名前: example.gallery

- ラベル: Gallery Access

- 割当済グループ: RESTful Services

- 説明: ギャラリ内イメージの表示およびポスト

- 保護されたモジュール: gallery.example

4. 「作成」をクリックします。

今制限したRESTfulサービスへのアクセスを確認するには、次の手順を実行します。

1. 「SQLワークショップ」に移動し、「RESTfulサービス」に移動します。

2. gallery.exampleという名前のモジュールをクリックします。

3. images/の下のGETハンドラをクリックします。

4. 「テスト」をクリックします。
次の形式のURIがブラウザに表示されるはずです。

https://<host>:<port>/ords/resteasy/gallery/images

エラー・メッセージとともにエラー・ページが表示されるはずです。

401 Unauthorized.

関連項目:

適切な資格証明が提供されないかぎり保護されたRESTfulサービスにはアクセスできないので、これは予想どおりの結果です。リクエストに必要な資格証明を追加するには、「ファースト・パーティ認証を使用するためのアプリケーションの変更」を参照してください。

D.7.2 ファースト・パーティ認証を使用するためのアプリケーションの変更

ファースト・パーティ認証はCookieおよびApplication Expressアプリケーションによって確立されたユーザー・セッションを利用しますが、Oracle REST Data Servicesでは、Cookieの検証を可能にするために追加の情報を必要とします。アプリケーションIDと現在のセッションIDを知る必要があります。この情報は、Application Expressアプリケーションが常に把握しているもので、RESTfulサービスに送信される各リクエストにカスタムのHTTPヘッダーApex-Sessionを追加することで、RESTfulサービスに対して行われるリクエストに含める必要があります。アプリケーションIDおよびセッションIDは、カンマによって各々が区切られ、ヘッダーの値として送信されます。次に例を示します。

GET /ords/resteasy/gallery/images/
Host: server.example.com
Apex-Session: 102,6028968452563

場合によって、HTTPリクエストにカスタム・ヘッダーを含められないことがあります。たとえば、<img>タグを使用したHTMLページ内でイメージを表示する場合などで、このような場合には別の方法を使用します。アプリケーションIDおよびセッションIDをカンマで区切り、_apex_sessionという名前の問合せパラメータとしてリクエストURIに追加します。次に例を示します。

<img src="graphics/101?_apex_session=102,6028968452563">

この方法は、カスタム・ヘッダーが使用できない場合にのみ使用することに注意してください。それ以外の場合は、セッションIDをURIに含めることで、誤って保存されたり公開されたりするリスクが増加するため、この方法はお薦めしません。

各リクエストにファースト・パーティの認証情報を追加するようにアプリケーションを変更するには、次の手順を実行します。

1. Application Builderに移動します。

2. イメージ・ギャラリ・アプリケーションの横にある「編集」ボタンをクリックします。

3. 「ホーム」という名前の最初のページをクリックします。

4. 「ページ」の下で、編集アイコンをクリックし、「JavaScript」タブをクリックします。

5. 関数およびグローバル変数の宣言フィールドの先頭に次を追加します。

function setApexSession(pathOrXhr) {
var appId = $v('pFlowId');
var sessionId = $v('pInstance');
var apexSession = appId + ',' + sessionId;
if ( typeof pathOrXhr === 'string' ) {
var path = pathOrXhr;
if ( path.indexOf('?') == -1 ) {
path = path + '?_apex_session=' + apexSession;
} else {
path = path + '&_apex_session=' + apexSession;
}
return path;
} else {
var xhr = pathOrXhr;
xhr.setRequestHeader('Apex-Session',apexSession);
return xhr;
}
}

6. これは、setApexSession()という名前のJavaScript関数を定義し、この関数はXMLHttpRequestオブジェクトまたはパスを含む文字列にファースト・パーティの認証情報を追加します。
次に、適切なときにこの関数を呼び出すように既存のJavaScriptコードを変更する必要があります。

7. xhr.open('POST',url,true);という行の後に、次の行を追加します。

setApexSession(xhr);

8. xhr.open('GET', gallery_url)という行の後に、次の行を追加します。

setApexSession(xhr);

9. var uri = item.uri['$ref'];という行を次のように変更します。

var uri = setApexSession(item.uri['$ref']);

10. 「変更の適用」をクリックします。

11. 前と同じようにアプリケーションを実行します。今度は、必要な認証情報をRESTfulサービスに提供しているので、動作するはずです。

D.8 サード・パーティ・アプリケーションからのRESTfulサービスへのアクセス

サード・パーティがギャラリRESTfulサービスを消費および使用する場合、サード・パーティ・アプリケーションを登録してOAuth 2.0の資格証明を取得する必要があり、その後、それをインタラクティブなプロセスを開始するために使用でき、ユーザーにかわってRESTfulサービスにアクセスするサード・パーティ・アプリケーションに権限を付与できます。

アプリケーションが登録されると、アクセス・トークンを取得できます。アクセス・トークンは、保護されたRESTfulサービスへの各リクエストに指定する必要があります。Oracle REST Data Servicesは、RESTfulサービスへのアクセスを許可する前に、そのアクセス・トークンを検証します。

OAuth 2.0では、アプリケーションがアクセス・トークンを取得するために使用できる、多数の異なるプロトコル・フローが定義されています。Oracle REST Data Servicesでは、これらのプロトコル・フローのうち次の2つがサポートされています。

- 認可コード。サード・パーティ・アプリケーションがそのクライアントの資格証明をセキュアに保持できる場合、たとえば、サード・パーティのWebサイトが適切に保護されている場合などにこのフローが使用されます。

- 暗黙の権限付与サード・パーティ・アプリケーションがその資格証明を機密にしておくことを保証できない場合、たとえば、JavaScriptベースのブラウザ・アプリケーションまたはネイティブのスマートフォン・アプリケーションなどでこのフローが使用されます。

最初の手順は、サード・パーティ・アプリケーションの登録です。このデモを行うため、サード・パーティの開発者を表すユーザーを作成し、このユーザーを使用してアプリケーションを登録します。

この後の手順では、RESTEASYワークスペースのユーザー・リポジトリにユーザーを作成し、関連する処理を実行します。

注意:

Oracle REST Data Servicesでは、ワークスペースのユーザー・リポジトリに定義されたユーザーの認証に加え、WebLogic ServerまたはGlassFishからアクセス可能な任意のユーザー・リポジトリに対する認証も可能です。詳細は、「WebLogic ServerおよびGlassFishユーザー・リポジトリに対する認証」を参照してください。

トピック:

- サード・パーティの開発者ユーザーの作成

- サード・パーティ・アプリケーションの登録

- アクセス・トークンの取得

- アクセス・トークンの使用

- ブラウザのオリジンについて

- クロス・オリジン・リソース共有のためのRESTfulサービスの構成

- 認可コード・プロトコル・フローを使用したトークンの取得

- アクセス・トークンの保護について

D.8.1 サード・パーティの開発者ユーザーの作成

サード・パーティの開発者ユーザー(RESTfulサービスにアクセスするアプリケーションを登録するサード・パーティの開発者のユーザー・アカウント)を作成するには、次の手順を実行します。

1. 「管理」に移動します。

2. 「ユーザーとグループの管理」をクリックします。

3. 「ユーザーの作成」をクリックし、次の情報を入力します。

- ユーザー名: 3rdparty_dev

- 電子メール・アドレス: この開発者ユーザーの電子メール・アドレス

- パスワード: このユーザーのパスワード。

- ユーザー・グループ: OAuth 2.0 Client Developer

4. 「ユーザーの作成」をクリックします。

D.8.2 サード・パーティ・アプリケーションの登録

暗黙の権限付与のOAuth 2.0プロトコル・フローを使用するサード・パーティ・アプリケーションを登録するには、次の手順を実行します。

1. ブラウザで次のURIに移動します。

https://server:port/ords/resteasy/ui/oauth2/clients/

2. 前に作成した3rdparty_devユーザーの資格証明を入力し、「サインイン」をクリックします。

3. クライアントの登録をクリックし、次の情報を入力します。

- 名前: 3rd Party Gallery

- 説明: ギャラリRESTfulサービスを消費するデモ

- レスポンス・タイプ: Token

- リダイレクトURI: https://server:port/i/oauthdemo/gallery.html

- サポート電子メール: 希望する電子メール・アドレス

- 必須のスコープ: Gallery Access

4. 「登録」をクリックします。

5. 次のページに表示されるリストの「3rd Party Gallery」をクリックします。

6. 「クライアント識別子」および認可URIフィールドの値に注意してください。

D.8.3 アクセス・トークンの取得

アクセス・トークンを取得するには、アクセス承認のプロンプトをユーザーに表示する必要があります。承認プロセスを開始するには、次のURIを使用してユーザーを承認ページに誘導します。

https://server:port/ords/resteasy/oauth2/auth?response_type=token&\
client_id=CLIENT_IDENTIFIER&\
state=STATE

説明:

- CLIENT_IDENTIFIERは、登録時にアプリケーションに割り当てられたクライアント識別子です。

- STATEは、クロス・サイト・リクエスト・フォージェリ(CSRF)攻撃を防止するために使用される、アプリケーションによって生成された固有の値です。

Oracle REST Data ServicesのOAuth 2.0実装では、次の点に注意してください。

- OAuth 2.0仕様では、前述のリクエストでは次の2つのオプション・パラメータが指定できます。

- redirect_uri: ユーザーがアクセスを承認/拒否した後で、認可サーバーをリダイレクトする場所を指定します。

- scope: クライアントがアクセスしようとするRESTfulサービスの権限を指定します。

Oracle REST Data Servicesでは、これらのパラメータのどちらもサポートしていません。どちらの値もクライアントの登録時に指定されるので、ここでそれを繰り返すのは冗長になるためです。これらのパラメータに指定された値は無視されます。

- OAuth 2.0仕様ではstateパラメータの使用を推奨していますが、Oracle REST Data Servicesでは、CSRF攻撃の防止に役立つという重要性から、このパラメータの使用を必須としています。

- レスポンス・タイプもアプリケーションの登録時に指定されるため、response_typeパラメータも冗長ですが、OAuth 2.0仕様でこのパラメータは常に必須と明言されているため、含める必要があります。response_typeの値が登録時のレスポンス・タイプと異なる場合はエラーになります。

ブラウザで前述のURIにアクセスすると、ユーザーはサインオンするように促され、その後、アプリケーションのアクセス・リクエストを確認し、アクセスを承認するか拒否するか選択するように求められます。

ユーザーがリクエストを承認した場合、ブラウザは登録されたリダイレクトURIにリダイレクトされ、アクセス・トークンはURIの一部分としてエンコードされます。

https://server:port/i/oauthdemo/gallery.html#token_type=bearer&\
access_token=ACCESS_TOKEN&\
expires_in=TOKEN_LIFETIME&\
state=STATE

説明:

- ACCESS_TOKENは、現在のユーザー・セッションに割り当てられた一意の推測できないアクセス・トークンで、RESTfulサービスに対する後続のリクエストでこれを指定する必要があります。

- TOKEN_LIFETIMEは、アクセス・トークンが有効である秒数です。

- STATEは、認可フローの開始時にアプリケーションによって提供される一意の値です。戻されたstateの値が初期のstateの値と一致しない場合、それはエラー状態であり、攻撃者がCSRF攻撃により認可プロセスを破壊しようとしている可能性があるため、アクセス・トークンは使用しないでください。

注意:
生成されたすべてのアクセス・トークンのデフォルトのOAuthアクセス・トークン期間(存続期間)を変更できます。これを実現するには、次のようにして、defaults.xml構成ファイルに、OAuthアクセス・トークン期間を秒単位で指定するsecurity.oauth.tokenLifetimeエントリを追加します。
<entry key="security.oauth.tokenLifetime”>600</entry>

ユーザーがリクエストを拒否するか、またはユーザーがRESTfulサービスへのアクセスを許可されていない場合、ブラウザは登録されたリダイレクトURIにリダイレクトされ、エラー・メッセージがURIの一部分にエンコードされます。

https://server:port/i/oauthdemo/gallery.html#error=access_denied&state=STATE

説明:

- error=access_deniedは、ユーザーがRESTfulサービスへのアクセスを許可されていない、またはアプリケーションのアクセスを承認しないことを選択したことをクライアントに通知します。

- STATEは、認可フローの開始時にアプリケーションによって提供される一意の値です。戻されたstateの値が初期のstateの値と一致しない場合、それはエラー状態であり、クライアントはそのレスポンスを無視してください。これは、攻撃者がCSRF攻撃により認可プロセスを破壊しようとしている可能性があります。

D.8.4 アクセス・トークンの使用

アプリケーションがアクセス・トークンを取得した後は、保護されたRESTfulサービスに対する各リクエストにそのアクセス・トークンを含める必要があります。これを行うには、Authorizationヘッダーを次の構文でHTTPリクエストに追加します。

Authorization: Bearer ACCESS_TOKEN

説明:

- ACCESS_TOKENは、アクセス・トークンの値です。

たとえば、JavaScriptベースのブラウザ・アプリケーションが次のようにギャラリ・サービスを呼び出すことがあります。

var accessToken = ... /* initialize with the value of the access token */
var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://server:port/ords/resteasy/gallery/images/',true);
/* Add the Access Token to the request */
xhr.setRequestHeader('Authorization', 'Bearer ' + accessToken);
xhr.onload = function(e) {
/* logic to process the returned JSON document */
...
};
xhr.send();

この例は、XMLHttpRequest.setRequestHeader(name,value)関数を使用し、AuthorizationヘッダーをHTTPリクエストに追加しています。アクセス・トークンが有効ならば、サーバーはギャラリ内のイメージのリストを表示するJSONドキュメントを戻します。

D.8.5 ブラウザのオリジンについて

Webブラウザの主要なセキュリティ概念の1つに同一生成元ポリシーがあり、これは、同じWebサイト(オリジン)から生成されるページ上で実行中のスクリプトには制限なしで互いのデータにアクセスすることを許可し、他のWebサイトから生成されるデータにはアクセスさせないというものです。

オリジンは、Webサイトのプロトコル、ホスト名およびポートによって定義されます。たとえば、https://example.comは1つのオリジンで、https://another.example.comはホスト名が異なるため異なるオリジンです。同様に、http://example.comはプロトコルが異なるためhttps://example.comとは異なるオリジンです。最後に、http://example.comはポートが異なるためhttp://example.com:8080とは異なるオリジンです。

たとえば、ギャラリRESTfulサービスの場合、サード・パーティのクライアントは次の場所にあります。

https://thirdparty.com/gallery.html

そして、ギャラリRESTfulサービスは次の場所にあります。

https://example.com/ords/resteasy/gallery/images/

そこで、同一生成元ポリシーにより、https://thirdparty.comオリジンのスクリプトは同じオリジンのデータにのみアクセス可能であり、https://example.comは明らかに異なるオリジンであることから、gallery.htmlの行うhttps://example.com/ords/resteasy/gallery/images/へのXMLHttpRequestは阻止されます。

https://example.comの作成者がhttps://thirdparty.comの作成者を信頼できない場合には、これは妥当なことです。しかし、作成者が互いに信頼するだけの理由がある場合には、同一生成元ポリシーは制限が大きすぎます。クロス・オリジン・リソース共有(CORS)と呼ばれるプロトコルにより、https://example.comからブラウザにhttps://thirdparty.comを信頼していることを通知する手段が提供されており、gallery.htmlの行うhttps://example.com/ords/resteasy/gallery/images/へのXMLHttpRequestを許可するようにブラウザに指示できます。

D.8.6 クロス・オリジン・リソース共有のためのRESTfulサービスの構成

クロス・オリジン・リソース共有のRESTfulサービスを構成するには、次の手順を実行します。

1. 「SQLワークショップ」に移動し、「RESTfulサービス」に移動します。

2. gallery.exampleという名前のモジュールをクリックします。

3. 許可済オリジンに、RESTfulサービスへのアクセスが許可されるオリジンを入力します(複数オリジンはカンマで区切ります)。

4. 「変更の適用」を押します。

D.8.7 認可コード・プロトコル・フローを使用したトークンの取得

他の項で、OAuth 2.0の暗黙のプロトコル・フローを使用したアクセス・トークンの取得方法を説明しました。この項では、認可コードのプロトコル・フローを使用して同じことをする方法を説明します。その手順は、認可コードとアクセス・トークンの交換を必要とするため、暗黙のプロトコル・フローよりも少しばかり複雑です。

この項では、cURLを使用してこの交換手順を模倣します。

トピック:

- クライアント・アプリケーションの登録

- 認可コードの取得

- 認可コードとアクセス・トークンの交換

- OAuth 2.0セッションの継続時間の延長

D.8.7.1 クライアント・アプリケーションの登録

クライアントを登録するには、次の手順に従います。

1. ブラウザで次のURIに移動します。

https://server:port/ords/resteasy/ui/oauth2/clients/

2. 3rdparty_devユーザーの資格証明を入力し、「サインイン」をクリックします。

3. クライアントの登録をクリックし、次の情報を入力します。

- 名前: Another Gallery

- 説明: 認可コードのOAuth 2.0プロトコル・フローを使用したデモ

- レスポンス・タイプ: Code

- リダイレクトURI : https://gallery.example.demo

- サポート電子メール: 希望する電子メール・アドレス

- 必須のスコープ: Gallery Access

4. 「登録」をクリックします。

5. 次のページに表示されるリストの「3rd Party Gallery」をクリックします。

6. 「クライアント識別子」、「クライアント・シークレット」および認可URIフィールドの値に注意してください。

D.8.7.2 認可コードの取得

認可コード・プロトコル・フローの最初の手順は、認可コードを取得することです。認可コードは、アプリケーションのクライアント識別子およびクライアント・シークレットと一緒に提示された場合、アクセス・トークンと交換できる有効期限の短いトークンです。

アクセス・トークンを取得するには、アクセス承認のプロンプトをユーザーに表示する必要があります。承認プロセスを開始するには、次の形式のURIを使用してユーザーを承認ページに誘導します。

https://server:port/ords/resteasy/oauth2/auth?response_type=code&\
client_id=CLIENT_IDENTIFIER&\
state=STATE

説明:

- CLIENT_IDENTIFIERは、登録時にアプリケーションに割り当てられたクライアント識別子です。

- STATEは、クロス・サイト・リクエスト・フォージェリ(CSRF)攻撃を防止するために使用される、アプリケーションによって生成された固有の値です。

ユーザーがリクエストを承認した場合、ブラウザは登録されたリダイレクトURIにリダイレクトされ、アクセス・トークンはURIの問合せ文字列の一部分としてエンコードされます。

https://gallery.example.demo?code=AUTHORIZATION_CODE&state=STATE

説明:

- AUTHORIZATION_CODEは、認可コードの値です。

- STATEは、認可フローの開始時にアプリケーションによって提供される一意の値です。戻されたstateの値が初期のstateの値と一致しない場合、それはエラー状態であり、認可コードは使用しないでください。これは、攻撃者がCSRF攻撃により認可プロセスを破壊しようとしている可能性があります。
登録されたリダイレクトURIhttps://gallery.example.demoが存在しないので、ブラウザはサーバーに「見つかりません」のエラーを報告しますが、URIにエンコードされた認可コードの値を見ることはできるので、この例の目的のためには問題ありません。「認可コードとアクセス・トークンの交換」で使用するため、codeパラメータの値をメモしておいてください。

D.8.7.3 認可コードとアクセス・トークンの交換

この項では、cURLを使用して認可コードとアクセス・トークンを交換します。認可コードを交換するため、アプリケーションでは、認可コードおよびそのクライアント識別子とクライアント・シークレットを提供し、Oracle REST Data ServicesのOAuth 2.0トークン・エンドへのHTTPリクエストを行う必要があります。資格証明が正しい場合は、Oracle REST Data Servicesによりアクセス・トークンを含むJSONドキュメントが戻されます。アプリケーションはサーバー側(クライアント識別子とクライアント・シークレットが安全に格納されている)から直接Oracle REST Data ServicesへのHTTPリクエストを行うことに注意してください。プロトコル・フローのこの手順ではWebブラウザはまったく関与していません。

認可コードとアクセス・トークンを交換するには、次の形式でcURLコマンドを使用します。

curl -i -d "grant_type=authorization_code&code=AUTHORIZATION_CODE" \
--user CLIENT_IDENTIFER:CLIENT_SECRET \
https://server:port/ords/resteasy/oauth2/token

説明:

- AUTHORIZATION_CODEは、認可コードの値です(前の項のリダイレクトURIの問合せ文字列のcodeパラメータにエンコードされたものです)。

- CLIENT_IDENTIFERは、クライアント識別子の値です。

- CLIENT_SECRETは、クライアント・シークレットの値です。

cURLにより、前述のコマンドが次のようなHTTPリクエストに変換されます。

POST /ords/resteasy/oauth2/token HTTP/1.1
Authorization: Basic Q0xJRU5UX0lERU5USUZJRVI6Q0xJRU5UX1NFQ1JFVA==
Host: server:port
Accept: */*
Content-Length: 59
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE

説明:

- このリクエストは、OAuth 2.0のトークン・エンドoauth2/tokenへのHTTPのPOSTです。

- Authorizationヘッダーは、HTTP BASIC認証プロトコルを使用し、アプリケーションのアイデンティティを示すためのクライアント識別子とクライアント・シークレットをエンコードします。

- リクエストのContent-Typeは、フォーム・データ(application/x-www-form-urlencoded)であり、リクエストのコンテンツはOAuth 2.0トークン権限タイプおよびOAuth 2.0認可コード値を示すフォーム・データです。

前述のHTTPリクエストに対し、次のようなレスポンスが生成されます。

HTTP/1.1 200 OK
ETag: "..."
Content-Type: application/json

{
"access_token":"04tss-gM35uOeQzR_2ve4Q..",
"token_type":"bearer",
"expires_in":3600,
"refresh_token":"UX4FVHhPFJl6GokvTXYw0A.."
}

レスポンスは、リフレッシュ・トークンとともにアクセス・トークンを含むJSONドキュメントです。アプリケーションがアクセス・トークンを取得した後は、保護されたRESTfulサービスに対する各リクエストにそのアクセス・トークンを含める必要があります。これを行うには、Authorizationヘッダーを次の構文でHTTPリクエストに追加します。

Authorization: Bearer ACCESS_TOKEN

関連トピック

- OAuth 2.0セッションの継続時間の延長

D.8.7.4 OAuth 2.0セッションの継続時間の延長

OAuth 2.0セッションの存続期間を延長するため、リフレッシュ・トークンを新規の有効期限を持つ新規のアクセス・トークンと交換できます。リフレッシュ・トークンは認可コードのプロトコル・フローでのみ発行されることに注意してください。

アプリケーションは、認可コードとアクセス・トークンの交換に使用したものと同様のリクエストを行います。アクセス・トークンのためのリフレッシュ・トークンを交換するには、次の形式でcURLコマンドを使用します。

curl -i -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN" \
--user CLIENT_IDENTIFER:CLIENT_SECRET \
https://server:port/ords/resteasy/oauth2/token

説明:

- REFRESH_TOKENは、アクセス・トークンが最初に発行されたときに戻されたリフレッシュ・トークンの値です。

- CLIENT_IDENTIFERは、クライアント識別子の値です。

- CLIENT_SECRETは、クライアント・シークレットの値です。

cURLにより、前述のコマンドが次のようなHTTPリクエストに変換されます。

POST /ords/resteasy/oauth2/token HTTP/1.1
Authorization: Basic Q0xJRU5UX0lERU5USUZJRVI6Q0xJRU5UX1NFQ1JFVA==
Host: server:port
Accept: */*
Content-Length: 53
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=REFRESH_TOKEN

説明:

- このリクエストは、OAuth 2.0のトークン・エンドoauth2/tokenへのHTTPのPOSTです。

- Authorizationヘッダーは、HTTP BASIC認証プロトコルを使用し、アプリケーションのアイデンティティを示すためのクライアント識別子とクライアント・シークレットをエンコードします。

- リクエストのContent-Typeは、フォーム・データ(application/x-www-form-urlencoded)であり、リクエストのコンテンツはOAuth 2.0トークン権限タイプおよびリフレッシュ・トークン値を示すフォーム・データです。

前述のHTTPリクエストに対し、次のようなレスポンスが生成されます。

HTTP/1.1 200 OK
ETag: "..."
Content-Type: application/json

{
"access_token":"hECH_Fc7os2KtXT4pDfkzw..",
"token_type":"bearer",
"expires_in":3600,
"refresh_token":"-7OBQKc_gUQG93ZHCi08Hg.."
}

レスポンスは、新規のリフレッシュ・トークンとともに新規のアクセス・トークンを含むJSONドキュメントです。既存のアクセス・トークンおよびリフレッシュ・トークンは無効になり、古いアクセス・トークンを使用してサービスにアクセスしようとすると失敗します。

D.8.8 アクセス・トークンの保護について

OAuth 2.0では、アクセス・トークンは保護されたサービスにアクセスするために提供する必要のある唯一の資格証明です。このため、アクセス・トークンをセキュアに保持することは重要です。トークンのセキュアな保持を促進するため、次のガイドラインに従ってください。

- すべての保護されたRESTfulサービスにHTTPSを使用することを強くお薦めします。これにより、安全でないチャネル上の盗聴により攻撃者がアクセス・トークンを盗むことができるスヌーピング攻撃を防ぎます。また、攻撃者によるリクエストのペイロードに存在する機密データの表示を防ぐことができます。

- クライアント・アプリケーションが、信頼できない他のアプリケーションまたはスクリプトとともにブラウザのオリジンに配置されていないことを確認してください。たとえば、アリスというユーザーが次の場所でホストされているクライアント・アプリケーションを持っているとします。

https://sharedhosting.com/alice/application

別のユーザー(たとえばフレッド)もまた、次のように同じオリジンに彼のアプリケーションをホストできる場合、

https://sharedhosting.com/fred/trouble

同じオリジンhttps://sharedhost.comを共有しているため、ブラウザではどちらのアプリケーションについても相手のデータにアクセスすることを防ぐことはできず、/alice/applicationが取得したアクセス・トークンを盗むことは、/fred/troubleには容易になります。

このようなシナリオを防ぐために、アリスのアプリケーションは、たとえば、自身のオリジンにデプロイする必要があります。

https://alice.sharedhosting.com/application

または

https://application.alice.sharedhosting.com

または

https://aliceapp.com

E Oracle REST Data Servicesでのマルチテナント・アーキテクチャの使用

この項では、Oracle Database 12cマルチテナント・アーキテクチャで導入されるプラガブル・データベースのコピーおよび移動に関連するインストールの選択項目と様々な使用例について、Oracle REST Data Servicesに関連付けて説明します。

- インストールの選択項目の理解

- Oracle REST Data ServicesのCDBへのインストール

- CDB環境でのOracle REST Data Servicesのアップグレード

- Oracle REST Data Servicesによって、すべてのPDBをアドレス可能にする(プラガブル・マッピング)

- CDB環境でのOracle REST Data Servicesのアンインストール

E.1 インストールの選択項目の理解

Oracle Database 12cリリース1 (12.1)では、マルチテナント・アーキテクチャが導入されています。このデータベース・アーキテクチャには、ルート・コンテナCDB$ROOT、シード・データベースPDB$SEEDおよび複数のプラガブル・データベース(PDB)を含むマルチテナント・コンテナ・データベース(CDB)が含まれます。PDBは、ユーザーおよびアプリケーションからは、非CDBであるかのように見えます。各PDBは、Oracle Databaseリリース11gの個別のデータベース・インスタンスに相当します。

ルート・コンテナCDB$ROOTは、メタデータ・リンクまたはオブジェクト・リンクを使用してすべてのPDBにアクセス可能な共通オブジェクトを保持します。シード・データベースPDB$SEEDは、新しいプラガブル・データベースをシードするために新しいPDBを作成する際に使用されます。Oracle Database 12cマルチテナント・アーキテクチャの主なメリットは、CPUやメモリーなどのデータベース・リソースをすべてのPDBで共有できることです。また、このアーキテクチャでは、アップグレード、パッチ、バックアップなどのタスクにおいて、複数のデータベースを1つのデータベースとして扱うことができます。

Oracle REST Data Servicesを、マルチテナント・データベースの1つ以上のプラガブル・データベースPDBまたはコンテナ・データベース(CDB)にインストールできます。インストールの選択項目を次に示します。

- すべてのPDBでOracle REST Data Servicesの同じバージョンを有効にする場合には、CDBにインストールします。この項の残りの説明はCDBへのインストールを示します。

- 一部のPDBのみがOracle REST Data Servicesを使用できるようにするには、または別々のPDBが別々のバージョンのOracle REST Data Servicesを使用するようにするには、目的のPDBにインストールします。(非CDBでも同じプロシージャを使用します。)

Oracle REST Data ServicesがCDBにインストールされている場合、ルート・コンテナ、シード・コンテナおよび任意の既存PDBにインストールされています。ルート・コンテナ(CDB$ROOT)には、Oracle REST Data Servicesパッケージ、ファンクション、プロシージャ、ビューなどの一般的なデータベース・オブジェクトを格納するORDS_METADATAスキーマが含まれます。Oracle REST Data Servicesのパブリック・ユーザー(ORDS_PUBLIC_USER)も含まれます。

シード・コンテナ(PDB$SEED)には、ORDS_METADATAスキーマおよびORDSパブリック・ユーザーが含まれます。新しいPDBを作成するには、PDB$SEEDをコピーし、CDB$ROOT内のORDS_METADATAスキーマの一般的なデータベース・オブジェクトにメタデータ・リンクを作成します。そのため、Oracle REST Data Services表の複数のコピーがあり、Oracle REST Data Servicesパッケージ、機能、プロシージャ、ビューの単一のコピーのみがあります。このように、各PDBにはORDS_METADATAスキーマとそれ自体のOracle REST Data Services表のコピーがあるため、Oracle REST Data ServicesアプリケーションのメタデータをそのPDB内に保持できます。各PDBにはそれ自体のORDSパブリック・ユーザーがあります。

『Oracle Database管理者ガイド』のシードを使用したPDBの作成に関する項も参照してください。

E.2 Oracle REST Data ServicesのCDBへのインストール

すべてのPDBを1つのマルチテナント環境に入れて、Oracle REST Data Servicesの同じリリースとパッチ・セットを使用するにはCDBにインストールします。(この選択をすると、別々のPDBでOracle REST Data Servicesの別々のリリースを使用することを許可しません。)

CDBにインストールする前に次を確認します。

- PDBが読取り/書込みモードでオープン(マウント済またはクローズ済ではない)であることを確認します(PDB$SEED以外。これは読取り専用モードのままです)。『Oracle Database管理者ガイド』のPDBのオープン・モードの変更に関する項を参照してください。

- デフォルトの表領域および一時表領域がORDS_METADATAによって使用され、ORDS_PUBLIC_USERユーザーが存在し、表領域名がわかっていることを確認します。インストール・プロシージャはそれらのユーザーを作成しますが、表領域は作成しません。
ORDS_METADATAおよびORDS_PUBLIC_USERもシード・コンテナにインストールされ、デフォルトの表および一時表がPDB$SEEDに存在する必要があります。これらの表領域がそこに存在しない場合には、PDB$SEEDに表領域を作成します。『Oracle Database管理者ガイド』のCDBでのオラクル社が提供するSQLスクリプトの実行に関する項を参照してください。

Oracle REST Data ServicesをCDBにインストールするには、次の手順を実行します。

1. Oracle REST Data Servicesのインストール・キットを解凍したフォルダに移動します。

2. 次のコマンドを入力します。

java -jar ords.war install advanced

注意:

プラガブル・マッピング機能を使用するには、「Oracle REST Data Servicesによって、すべてのPDBをアドレス可能にする(プラガブル・マッピング)」を参照してください。

3. プロンプトが表示されたら、CDBのデータベース接続情報を入力します。

Enter the name of the database server [localhost]:
Enter the database listen port [1521]:
Enter 1 to specify the database service name, or 2 to specify the database SID [1]:
Enter the database service name: (for example, cdb.example.com)

4. Oracle REST Data Servicesのインストールを検証します。

Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]:

受け入れるか、1 (デフォルト)を入力して、CDBとそのPDBすべてにOracle REST Data Servicesをインストールします。

5. ORDS_PUBLIC_USERのパスワードを入力して確認します。

Enter the database password for ORDS_PUBLIC_USER:
Confirm password:

6. 入力を求めるメッセージが表示されたら、必要に応じて追加情報を入力します。(「コマンドライン・プロンプトを使用した拡張インストール」を参照してください。)

関連トピック

- コマンドライン・プロンプトを使用した拡張インストール

E.3 CDB環境でのOracle REST Data Servicesのアップグレード

Oracle REST Data Servicesの新しいリリースを使用する場合、CDBおよびそのプラガブル・データベース(PDB)でのORDSスキーマのアップグレードは、簡易または詳細インストールを実行すると自動的に発生します。

次に例を示します。

java -jar ords.war

Oracle REST Data Servicesがすでにインストールまたはアップグレードされている場合は、メッセージにOracle REST Data Servicesスキーマ・バージョンが表示され、情報の入力を要求されません。

エラーが発生した場合には、ログファイルを確認します。

関連トピック

- パラメータ・ファイルを使用した簡易インストール

- コマンドライン・プロンプトを使用した拡張インストール

E.4 Oracle REST Data Servicesによって、すべてのPDBをアドレス可能にする(プラガブル・マッピング)

プラガブル・マッピングは、CDB内のすべてのPDBをOracle REST Data Servicesによってアドレス可能にする機能を示します。この機能を使用するには、この項の指示に従ってください。

Oracle REST Data Services構成ファイルにdb.serviceNameSuffixパラメータが含まれている場合、これはOracle REST Data ServicesプールがCDBを指し、そのCDBに接続されているPDBをOracle REST Data Servicesによってアドレス可能にすることを示しています。

db.serviceNameSuffixパラメータの値は、データベースのDB_DOMAINデータベース初期化パラメータの値と一致している必要があり、ピリオド(.)で始まる必要があります。db.serviceNameSuffixパラメータの値を設定するには、次の手順を実行します。

1. SQL*Plusで、SYSDBA権限を持つユーザーとしてルートに接続します。

2. DB_DOMAINデータベース初期化パラメータの値を確認します。

SQL> show parameter DB_DOMAIN

3. SQL*Plusを終了します。

SQL> exit

4. DB_DOMAIN値が空ではない場合、コマンドラインでdb.serviceNameSuffixパラメータのキーと値およびそのDB_DOMAINを作成するコマンドを入力します。これは、このエントリをORDS構成ファイルに追加するために使用されます。

echo db.serviceNameSuffix=.value-of-DB_DOMAIN > snsuffix.properties

たとえば、DB_DOMAINがexample.comに設定されている場合、次を入力します。

echo db.serviceNameSuffix=.example.com > snsuffix.properties

5. db.serviceNameSuffixパラメータ値が定義されていない場合、次の形式でコマンドを入力して構成ファイルにエントリを追加します。

java -jar ords.war set-properties --conf pool-name snsuffix.properties

ここで、pool-nameは次のいずれかになります。

- PL/SQLゲートウェイ構成のpoolName

- Oracle REST Data Services RESTful Services構成のpoolName_pu

- Application Express RESTfulサービス構成のpoolName_rt

例1: CDBのPDBをグローバルでアドレス可能にします。次のコマンドを入力してdefaultsを指定します。

java -jar ords.war set-properties --conf defaults snsuffix.properties

注意:

ほとんどのユース・ケースでは、例1で示した方法(すべてのプールのプロパティをdefaults.xmlファイルを使用して設定)が最も適しています。

例2: CDBのPDBをPL/SQLゲートウェイにアドレス可能にし、プール名をapexにします。次のコマンドを入力します。

java -jar ords.war set-properties --conf apex snsuffix.properties

たとえば、apexによって指定されているデータベースにexample.comのDB_DOMAIN値があり、2つのPDB(pdb1.example.comおよびpdb2.example.com)がある場合、最初のPDBはパスが/ords/pdb1/で始まるURLにマップされ、2番目のPDBはパスが/ords/pdb2/で始まるURLにマップされます。

例3: CDBのPDBをOracle REST Data Services RESTfulサービスにアドレス可能にし、プール名をapex_puにします。次のコマンドを入力します。

java -jar ords.war set-properties --conf apex_pu snsuffix.properties

例4: CDBのPDBをApplication Express RESTfulサービスにアドレス可能にし、プール名をapex_rtにします。次のコマンドを入力します。

java -jar ords.war set-properties --conf apex_rt snsuffix.properties

関連トピック

- Oracle REST Data Servicesの構成ファイルについて

E.5 CDB環境でのOracle REST Data Servicesのアンインストール

Oracle REST Data ServicesをCDBからアンインストールするには、uninstallコマンドを使用します。

次に例を示します。

java -jar ords.war uninstall

Oracle REST Data ServicesがCDBとそのプラガブル・データベース(PDB)から削除されます。

関連トピック

- Oracle REST Data Servicesを再インストールまたはアンインストール(削除)する場合

F RESTfulサービスのスタート・ガイド

このチュートリアルは、Oracle REST Data Servicesインストール・キットに含まれている<install-directory>\examples\getting-started\index.htmlのドキュメントに基づいていています。そのドキュメントは、生産性即時向上のために用意されているいくつかのリソースの一つです。

このチュートリアルの処理を実行する前に、次の前提条件と推奨事項を確認します。

- Oracle REST Data Servicesがインストールされていて、Oracleデータベースに接続するように構成されていることを確認します。

- RESTfulサービスが編集できるように、Oracle SQL Developer 4.1またはそれ以降がインストールされていることを確認します。

- WebブラウザでJSONを表示できるようにするブラウザ拡張機能をインストールすることを強くお薦めします。お薦めする拡張機能は次のとおりです。

- Google Chrome用: JSON Formatter (https://chrome.google.com/webstore/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa)

- Mozilla Firefox用: JSON View (https://addons.mozilla.org/en-US/firefox/addon/jsonview/)

このチュートリアルの例は、次の項目を前提としています。

- Oracle REST Data Servicesがインストールされ、構成されていて、次のサーバー、ポートおよびコンテキスト・パスで実行されていること。 localhost:8080/ords/

- Oracle REST Data Servicesが、localhost:1521のOracleデータベース・リスニングにデフォルト接続として接続するよう構成されていて、データベースはorclのサービス名を持つこと。

「スタート・ガイド」チュートリアルには、次の主要な手順が記述されています。

1. データベース表のREST対応

2. SQL問合せからのRESTfulサービスの作成

3. リソースの保護

4. OAuthクライアント・アプリケーションの登録

F.1 データベース表のREST対応

RESTアクセスの表を有効にするには、次の手順を実行します。

ヒント:

スキーマ・オブジェクトおよびデータベース・オブジェクトに指定した名前を使用することを含め、可能なかぎり正確に手順に従うことをお薦めします。この方法を使用してチュートリアルを正常に完了した後に、値を変更したい場合は自由に再度実行してみてください。

1. RESTfulサービスを試行するために、ordstestという名前のデータベース・スキーマを作成します。SQL Developerで、sysとしてデータベースに接続し、SQLワークシートに次を入力します。

CREATE USER ordstest IDENTIFIED BY <password>;
GRANT "CONNECT" TO ordstest;
GRANT "RESOURCE" TO ordstest;
GRANT UNLIMITED TABLESPACE TO ordstest

2. ordstestスキーマに接続します。SQL Developerで、ordstestスキーマに対する接続を作成し、接続してSQLワークシートを開きます。

3. データベース表を作成します。たとえば、EMPという名前のサンプル表を作成するには、SQLワークシートに次を入力します。

CREATE TABLE EMP (
EMPNO NUMBER(4,0),
ENAME VARCHAR2(10 BYTE),
JOB VARCHAR2(9 BYTE),
MGR NUMBER(4,0),
HIREDATE DATE,
SAL NUMBER(7,2),
COMM NUMBER(7,2),
DEPTNO NUMBER(2,0),
CONSTRAINT PK_EMP PRIMARY KEY (EMPNO)
);

4. 表にいくつかのサンプル・データを挿入します。次に例を示します。

Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7369,'SMITH','CLERK',7902,to_date('17-DEC-80','DD-MON-RR'),800,null,20);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7499,'ALLEN','SALESMAN',7698,to_date('20-FEB-81','DD-MON-RR'),1600,300,30);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7521,'WARD','SALESMAN',7698,to_date('22-FEB-81','DD-MON-RR'),1250,500,30);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7566,'JONES','MANAGER',7839,to_date('02-APR-81','DD-MON-RR'),2975,null,20);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7654,'MARTIN','SALESMAN',7698,to_date('28-SEP-81','DD-MON-RR'),1250,1400,30);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7698,'BLAKE','MANAGER',7839,to_date('01-MAY-81','DD-MON-RR'),2850,null,30);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7782,'CLARK','MANAGER',7839,to_date('09-JUN-81','DD-MON-RR'),2450,null,10);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7788,'SCOTT','ANALYST',7566,to_date('19-APR-87','DD-MON-RR'),3000,null,20);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7839,'KING','PRESIDENT',null,to_date('17-NOV-81','DD-MON-RR'),5000,null,10);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7844,'TURNER','SALESMAN',7698,to_date('08-SEP-81','DD-MON-RR'),1500,0,30);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7876,'ADAMS','CLERK',7788,to_date('23-MAY-87','DD-MON-RR'),1100,null,20);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7900,'JAMES','CLERK',7698,to_date('03-DEC-81','DD-MON-RR'),950,null,30);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7902,'FORD','ANALYST',7566,to_date('03-DEC-81','DD-MON-RR'),3000,null,20);
Insert into EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7934,'MILLER','CLERK',7782,to_date('23-JAN-82','DD-MON-RR'),1300,null,10);
commit;

5. RESTでEMP表のスキーマを有効化します。SQL Developerで、ordstest接続を右クリックし、「RESTサービス」 > 「RESTfulサービスを有効にする」の順に選択して、次のウィザード・ページを表示します。

図F-1 RESTでのEMP表のスキーマの有効化

スキーマの有効化: このオプションを有効にします。

スキーマ別名: スキーマ別名としてordstestを受け入れます。

承認が必要: 簡素化のために、このチュートリアルでは承認を要求しないため、このオプションは無効にします。

「次へ」をクリックします。

6. ウィザードのRESTfulサマリー・ページで「終了」をクリックします。

7. EMP表を有効化します。SQL Developerで、「接続」ナビゲータでEMP表を右クリックし、「RESTサービス」 > 「RESTfulサービスを有効にする」の順に選択して次のウィザード・ページを表示します。

図F-2 RESTでのEMP表の有効化

オブジェクトの有効化: このオプションを有効にします(つまり、EMP表のRESTアクセスを有効にします)。

オブジェクト別名: オブジェクト別名としてempを受け入れます。

承認が必要: 簡素化のために、このチュートリアルでは承認を要求しないため、このオプションは無効にします。

8. ウィザードのRESTfulサマリー・ページで「終了」をクリックします。
EMP表がREST HTTPエンドポイントとして公開されます。

9. RESTエンドポイントをテストします。Webブラウザで、次の図に示すように、URL http://localhost:8080/ords/ordstest/emp/を入力します。

- ORDSTESTスキーマが/ordstest/パスで公開されました。

- EMP表が/emp/パスで公開されました。

図F-3 RESTを有効化した表のテスト

F.2 SQL問合せからのRESTfulサービスの作成

Oracle REST Data Servicesは、Oracle SQL DeveloperがRESTfulサービス定義を作成および編集できるようにするREST API (リソース・モジュールAPIと呼ばれる)を提供します。リソース・モジュールAPIへのアクセスは保護されていて、適切なロールのユーザーがプロビジョニングされる必要があり、SQL DeveloperからAPIにアクセスするには、作成されたユーザーの資格証明を使用する必要があります。

SQL問合せからのRESTfulサービスを作成するには、次の手順を実行します。

1. Oracle REST Data Servicesがインストールされているフォルダで、コマンド・プロンプトで次のコマンドを入力します。

java -jar ords.war user test_developer "SQL Developer"

- パスワードの入力を求めるメッセージが表示されます。

- このコマンドはtest_developerという名前のユーザーを作成し、ユーザーにSQL Developerという名前のロールを付与します。SQL Developerロールのユーザーのみがリソース・モジュールのAPIにアクセスすることができます。

- ユーザー詳細は、ORDS構成フォルダのcredentialsという名前のファイルに格納されます。ただし、ユーザー資格証明を本番デプロイメントの資格証明ファイルに格納することはお薦めしません。そのかわりに、ユーザーをホスト・アプリケーション・サーバーにプロビジョニングしてください。

残りの手順では、RESTfulサービスを作成してテストします。

2. RESTful接続を作成します。SQL Developerで、「表示」 > 「RESTデータ・サービス」 > 「開発」の順に選択します。

3. 「REST開発」ペインで、「RESTデータ・サービス」 > 「接続」の順に右クリックします。

4. 「RESTfulサービス接続」ダイアログ・ボックスで、+ (プラス記号)アイコンをクリックし、選択可能なリストに接続を追加します。

5. 「新規RESTfulサービス接続」ダイアログ・ボックスで、次に示す必要な情報を入力します。

図F-4 新規RESTfulサービス接続の情報の入力

接続名: 接続用の任意の希望する名前。例: ordstest

ユーザー名: test_developer

httpまたはhttps: このチュートリアルでは、簡素化のため、httpを選択します。

ホスト名: localhost

ポート: 8080

サーバー・パス: /ords

ワークスペース: ordstest

「OK」をクリックし、プロンプトでtest_developerユーザーのパスワードを入力します。

6. モジュールを作成します。「REST開発」ビューでModulesノードを右クリックし、「新規モジュール」をクリックして、モジュールの指定ページで情報を入力します。

図F-5 モジュールの指定ページでの情報の入力

モジュール名: 接続用の任意の希望する名前。例: test

URI接頭辞: /test

公開 - このRESTfulサービスを使用可能にします: 有効化(チェック)。

ページ区切りサイズ: 7

7. 「次」をクリックし、テンプレートの指定ページで情報を入力します。

図F-6 「テンプレートの指定」ページでの情報の入力

URIテンプレート: /emp/

残りのオプションはデフォルトを受け入れます。

8. 「次」をクリックし、ハンドラの指定ページで情報を入力します。

図F-7 「ハンドラの指定」ページでの情報の入力

メソッド: GET

セキュア・アクセスが必要: このチュートリアルでは無効化(チェック解除)します。

ソース・タイプ: Collection Query

ページ区切りサイズ: 7

9. 「次」をクリックして、ウィザードのRESTfulサマリー・ページに移動し、「終了」をクリックします。
リソース・モジュールが作成され、次の手順ではGETリソース・ハンドラの問合せを定義します。

10. GETリソース・ハンドラの問合せを定義します。

a. 「REST開発」ビューでModulesノードの下にあるtestノードを展開します。

b. /emp/ノードを展開し、GETノードを右クリックして「開く」を選択します。

c. GET /emp/用に開いたSQLワークシートで、次のSQL問合せを入力します。

select * from emp

d. 「REST開発」ビューの「モジュール」ノードの下のテスト・ノードで右クリックします

e. 「アップロード」をクリックします。モジュールがアップロードされたことを確認する確認ダイアログが表示されます。

11. RESTfulサービスをテストします。Webブラウザで、次の図に示すように、URL http://localhost:8080/ords/ordstest/test/emp/を入力します。

- ORDSTESTスキーマが/ordstest/パスで公開されました。

- EMP表が/test/emp/パスで公開されました。

図F-8 SQL Queryから作成したRESTful Serviceのテスト

関連項目:
これで、ユーザーは接続ナビゲータからRESTfulサービスを作成することもできるようになりました。詳細は、「接続ナビゲータを介したRESTful Serviceの作成」を参照してください

F.3 リソースの保護

ここまで、チュートリアルでは、セキュリティなしでテストをした方が簡単なため、作成したRESTfulエンドポイントで意図的にセキュリティを無効化してきました。この項では/test/emp/サービスを保護するため、サービスにアクセスする前にユーザーは認証が必要となります。

保護されたリソースへのアクセスの制御は権限を定義することで行われます。「権限」はアクセスを、指定したロールを少なくとも1セットは持つユーザーに制限します。次に権限を1つ以上のリソース・モジュールに関連付けます。必要なロールの1つを確実に持つように、ユーザーは認証されてから権限が付与され、その後リソース・モジュールにアクセスできるようになります。

リソースを保護するには、次の手順を実行します。

1. 権限を作成します。SQL Developerで、「REST開発」ビューのPrivilegesノードを右クリックし、「新規権限」を選択して次に示す「権限の編集」ダイアログ・ボックスを表示します。

図F-9 権限の編集ダイアログ・ボックス

名前: test

タイトル: Example Privilege

説明: Demonstrate controlling access with privileges

保護されたモジュール: リストにtestモジュールが入っていることを確認します。必要に応じて、矢印ボタンを使用します。

「適用」をクリックします。

2. test権限を右クリックし、「アップロード」をクリックします。

ダイアログ・ボックスが、権限がアップロードされたことを確認します。

テスト・モジュールを保護する権限が作成されました。ただし、権限を特定のロールに制限していません。これはテスト・モジュールにアクセスする前にユーザーの認証を必要とすること意味します(次の手順)。

3. RESTfulサービスをテストします。Webブラウザで次のURLを入力します。

http://localhost:8080/ords/ordstest/test/emp/

4. リンクをクリックしてサイン・インし、test_developerの資格証明を入力します。

JSONドキュメントのコンテンツが表示されます。

F.4 接続ナビゲータを介したRESTful Serviceの作成

この項では、接続ナビゲータの「RESTデータ・サービス」ノードを使用してRESTful Serviceを作成する方法を説明します。Oracle REST Data Servicesには、接続ナビゲータを介してRESTfulサービス定義を作成および編集できるようにするオプションが用意されています。

接続ナビゲータの「RESTデータ・サービス」ノードを使用してRESTfulサービスを作成するには、次の手順に従います。

1. ordstestスキーマで、「RESTデータ・サービス」を選択します。

図F-10 接続ナビゲータ配下の「RESTデータ・サービス」オプション

次の手順では、RESTfulサービスを作成してテストします。

2. 「RESTデータ・サービス」ノードで「モジュール」ノードを右クリックし、「新規モジュール」をクリックして、「モジュールの指定」ページで情報を入力します。

図F-11 モジュールの指定ページでの情報の入力

モジュール名: 接続用の任意の希望する名前。たとえば、demo

URI接頭辞: /demo/

公開 - このRESTfulサービスを使用可能にします: 有効化(チェック)。

ページ区切りサイズ: 25

3. 「次」をクリックし、テンプレートの指定ページで情報を入力します。

図F-12 「テンプレートの指定」ページでの情報の入力

URIパターン: emp/

残りのオプションはデフォルトを受け入れます。

4. 「次」をクリックして、ウィザードのRESTfulサマリー・ページに移動し、「終了」をクリックします。「モジュール」ノードを展開して、作成したリソース・モジュールを表示します。

5. モジュールDemoを展開し、emp/ノードを右クリックして、「追加」ハンドラを選択し、続いてGETメソッドを選択します。

6. リソース・ハンドラの作成ページに関する情報を入力します。

図F-13 リソース・ハンドラの作成ページへの情報入力

ソース・タイプ: Collection Query

ページ区切りサイズ: 7

「適用」をクリックします。

次の手順は、GETリソース・ハンドラの問合せを定義することです。

7. SQLワークシートで、次の問合せを入力します。

select * from emp

8. 「RESTハンドラの保存」アイコンをクリックします。「メッセージ - ログ」ペインに、ハンドラがデータベースに保存されることを確認するメッセージが表示されます。

注意:
「メッセージ - ログ」ペインが表示されない場合は、「ビュー」メニューに移動し、「メッセージ」を選択します。

9. RESTfulサービスをテストします。Webブラウザで、次の図に示すように、URL http://localhost:8080/ords/ordstest/demo/emp/を入力します。

- ORDSTESTスキーマが/ordstest/パスで公開されました。

- EMP表が/test/emp/パスで公開されました。

F.4.1 REST Data Services配下での権限の作成

保護されたリソースへのアクセスの制御は権限を定義することで行われます。「権限」はアクセスを、指定したロールを少なくとも1セットは持つユーザーに制限します。次に権限を1つ以上のリソース・モジュールに関連付けます。必要なロールの1つを確実に持つように、ユーザーは認証されてから権限が付与され、その後リソース・モジュールにアクセスできるようになります。

リソースを保護するには、次の手順を実行します。

1. 権限を作成します。SQL Developerで、「REST Data Services」のPrivilegesノードを右クリックし、「新規権限」を選択して「権限の作成」ダイアログ・ボックスを表示します。

図F-14 権限を作成するダイアログ・ボックス

名前 : Demo

タイトル: Example Privilege

説明: Demonstrate controlling access with privileges

保護されたモジュール: リストにDemoモジュールが入っていることを確認します。必要に応じて、矢印ボタンを使用します。

「適用」をクリックします。

テスト・モジュールを保護する権限が作成されました。ただし、権限を特定のロールに制限していません。これはテスト・モジュールにアクセスする前にユーザーの認証を必要とすること意味します(次の手順)。

2. RESTfulサービスをテストします。Webブラウザで次のURLを入力します。
http://localhost:port/ords/ordstest/demo/emp/

3. リンクをクリックしてサイン・インし、test_developerの資格証明を入力します。

注意:
test_developerユーザーを作成するには、「SQL問合せからのRESTfulサービスの作成」の項を参照してください。

次のようなJSONドキュメントが表示されます。

関連トピック

- SQL問合せからのRESTfulサービスの作成

F.4.2 ロールの作成

この項では、ロールを作成および削除する方法について説明します。

ロールを作成するには、次の手順に従います。

1. 「RESTデータ・サービス」で「ロール」を右クリックし、続いて「新規ロール」をクリックします。

2. 「ロールの作成」ダイアログ・ボックスに、作成するロールの名前を入力します。

図F-15 新規ロール名の入力

3. 「適用」をクリックすると、新しいロールが作成されます。
ロールの名前を変更するか削除するには、ロール名を右クリックして、次のオプションの1つを選択します。

- 名前の変更: ロール名を変更する場合。

- 「削除」をクリックしてロールを削除します。

F.5 OAuthクライアント・アプリケーションの登録

この項では、REST APIにアクセスするためにアプリケーション(ここでは「サード・パーティ」アプリケーションと呼ぶ)を登録する方法を説明します。

OAuth 2.0は、エンド・ユーザーのために、REST APIのサード・パーティ・アプリケーションへのアクセスを制限する手段をHTTPサーバーに提供する標準のインターネット・プロトコルです。

- サード・パーティ・アプリケーションの作成者は、クライアント資格証明を取得するためにアプリケーションを登録する必要があります。

- クライアント資格証明のサード・パーティ・アプリケーションを使用すると、エンド・ユーザーに対してアクセスを承認するプロンプトを表示するWebフローを起動します。

そのため、サード・パーティ・アプリケーションがREST APIにアクセスできるするには、登録して、ユーザーがアクセスを承認する必要があります。そして、アプリケーションを登録できるようにするには、ユーザー登録アプリケーションを有効にするユーザー識別子を割り当てる必要があります。SQL Developerロールを持つユーザー(「SQL問合せからのRESTfulサービスの作成」で作成されたtest_developerなど)には、OAuthクライアントの登録が許可されています。

ヒント:

実際のアプリケーションでは、OAuthクライアントを登録できる特定のユーザーをプロビジョニングすることもできます。これらのユーザーにはOAuth Client Developerロールの権限を付与してください。

この項では、これらの処理を実行する方法の概要を示します。サード・パーティ・アプリケーションをどのように作成して統合するかの全機能のデモンストレーションではありません。含まれている概念の概要を示すのみです。

1. クライアント・アプリケーションを登録します。

a. Webブラウザで次のURLを入力します。

http://localhost:8080/ords/ordstest/oauth/clients/

b. プロンプトで、リンクをクリックしてサイン・インし、test_developerユーザーの資格証明を入力ます。

c. 新規クライアントをクリックし、次の情報を入力します。
名前: Test Client

説明: An example OAuth Client

リダイレクトURI: http://example.org/redirect

サポート電子メール: info@example.org

サポートURI: http://example.org/support

必要な権限: Example Privilege

d. 「作成」をクリックします。
クライアント登録が作成され、クライアントの認可URIが表示されます。暗黙の権限付与認証フロー(https://tools.ietf.org/html/rfc6749#section-4.2で説明)を使用するクライアントを作成しました。

クライアントに割り当てられている「クライアント識別子」および認可URIの値をメモします。これらの値は認可フローの開始に使用されます(次の主要手順)。

2. クライアント・アプリケーションを承認します。
実際のサード・パーティ・クライアント・アプリケーションでは、クライアントはWebブラウザを認可URIに誘導することによって承認フローを開始します。エンド・ユーザーには、サイン・インしてクライアント・アプリケーションへのアクセスを承認するためのプロンプトが表示されます。ブラウザは、承認用にaccess_tokenが組み込まれたURIフラグメント付きの、クライアントの登録されたリダイレクトURIにリダイレクトされます。このプロセスをシミュレートするには、次の手順を実行します。

a. Webブラウザで、前述の手順で確認した認可URIを入力します。URLは次のようになります(この値の例をコピーして貼り付けないでください)。

http://localhost:8080/ords/ordstest/oauth/auth?response_type=token&client_id=5B77A34A266EFB0056BE3497ED7099.&state=d5b7944-d27d-8e2c-4d5c-fb80e1114490&_auth_=force

client_id値は、アプリケーションに割り当てられたクライアント識別子の値である必要があります。正しいclient_id値を使用していることを確認してください。前述の例の値は使用しないでください。アプリケーションに割り当てられているクライアント識別子に置き換えてください。

state値は、クライアントが記憶する、一意の推測できない値にしてください。後でOracle REST Data Servicesから受け取ったリダイレクトがこの認可リクエストのレスポンスに入っていることを確認するために使用できます。この値がクロス・サイト・リクエスト・フォージェリ攻撃を防ぐために使用されます。これはとても重要で、省略できません。また、攻撃者によって推測またはや検出が可能な値にはしないでください。

b. プロンプトで、リンクをクリックしてサイン・インし、test_developerユーザーの資格証明を入力ます。

c. リクエストされたアクセスを確認し、「承認」をクリックします。
ブラウザは、次のようなURLにリダイレクトされます。

http://example.org/redirect#token_type=bearer&access_token=-i_Ows8j7JYu0p07jOFMEA..&expires_in=3600

OAuthクライアントを登録するときに、http://example.org/リダイレクトをリダイレクトURIとして指定しました。承認リクエストの完了時には、ブラウザはこの登録されたリダイレクトURIにリダイレクトされます。URIに追加された情報は、承認用に生成されたアクセス・トークンに関する情報です。

実際のアプリケーションでは、サード・パーティ・アプリケーションは、アクセス・トークンをキャッシュし、別のページにリダイレクトしてREST APIにアクセスするために認可されたことをユーザーに示し、アクセス・トークンをREST APIのすべての後続のリクエストに含めることでリダイレクトURIに応答します。ただし、このチュートリアルでは、次の主要な手順で説明しているように、アクセス・トークンの値をメモして、そのアクセス・トークンを含むHTTPリクエストを手動で作成するのみです。

アクセス・トークンの値(前述の例では-i_Ows8j7JYu0p07jOFMEA..)は承認されるたびに変更されます。

アクセス・トークンの有効期限が切れることに注意してください。前述の例では、3600秒後(&expires_in=3600)、つまり1時間後に有効期限が切れます。

3. 許可されたリクエストを発行します。
アクセス・トークンを取得した後は、クライアント・アプリケーションはアクセス・トークンを記憶し、保護されたリソースへのすべてのリクエストに含める必要があります。次の例に示すように、アクセス・トークンはHTTP認可リクエスト・ヘッダー(http://tools.ietf.org/html/rfc2616#section-14.8で説明)に含める必要があります。

Host: localhost:8080
GET /ords/ordstest/test/emp/
Authorization: Bearer -i_Ows8j7JYu0p07jOFMEA..

有効なHTTPリクエストの作成をエミュレートするには、cURLコマンドライン・ツールを使用します(必要に応じて、cURLをインストールします)。実際のアプリケーションでは、このリクエストはXMLHttpRequestなどHTTPリクエストを作成するクライアントによって実行されます。次に例を示します。

curl -i -H'Authorization: Bearer -i_Ows8j7JYu0p07jOFMEA..' http://localhost:8080/ords/ordstest/test/emp/

ただし、この例では、-i_Ows8j7JYu0p07jOFMEA..を前の手順でメモしたアクセス・トークン値で置き換えます。

次のJSONドキュメントのような出力が表示されます。

HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
"items":[
{"empno":7369,"ename":"SMITH","job":"CLERK","mgr":7902,"hiredate":"1980-12-17T00:00:00Z","sal":800,"comm":null,"deptno":20},
{"empno":7499,"ename":"ALLEN","job":"SALESMAN","mgr":7698,"hiredate":"1981-02-20T00:00:00Z","sal":1600,"comm":300,"deptno":30},
{"empno":7521,"ename":"WARD","job":"SALESMAN","mgr":7698,"hiredate":"1981-02-22T00:00:00Z","sal":1250,"comm":500,"deptno":30},
{"empno":7566,"ename":"JONES","job":"MANAGER","mgr":7839,"hiredate":"1981-04-01T23:00:00Z","sal":2975,"comm":null,"deptno":20},
{"empno":7654,"ename":"MARTIN","job":"SALESMAN","mgr":7698,"hiredate":"1981-09-27T23:00:00Z","sal":1250,"comm":1400,"deptno":30},
{"empno":7698,"ename":"BLAKE","job":"MANAGER","mgr":7839,"hiredate":"1981-04-30T23:00:00Z","sal":2850,"comm":null,"deptno":30},
{"empno":7782,"ename":"CLARK","job":"MANAGER","mgr":7839,"hiredate":"1981-06-08T23:00:00Z","sal":2450,"comm":null,"deptno":10}
],
"hasMore":true,
"limit":7,
"offset":0,
"count":7,
"links":[
{"rel":"self","href":"http://localhost:8080/ords/ordstest/test/emp/"},
{"rel":"describedby","href":"http://localhost:8080/metadata-catalog/test/emp/"},
{"rel":"first","href":"http://localhost:8080/ords/ordstest/test/emp/"},
{"rel":"next","href":"http://localhost:8080/ords/ordstest/test/emp/?offset=7"}
]
}

ただし、Authorizationヘッダーが省略された場合には、かわりにステータス401 Unauthorizedが戻されます。

関連項目:
http://curl.haxx.se/

索引

A  B  C  D  E  G  I  J  M  N  O  P  R  S  T  U

A

- アクセス・トークン

- 取得 1

- 保護 1

- 使用 1

- Apache Tomcat

- 説明 1

- Oracle REST Data Servicesイメージの構成 1

- デプロイ 1

- ダウンロード 1

- 認証

- WebLogicおよびGlassFishのユーザー・リポジトリに対する 1

B

- Bequeath接続 1

- ブラウザのオリジン 1

C

- コマンドライン・インタフェース 1

- configdirコマンド

- 構成ファイルの検索 1

- 構成フォルダの検索 1

- 構成ファイルの編集可能なパラメータ

- apex.excel2collection 1

- apex.excel2collection.onecollection 1

- jdbc.MaxConnectionReuseCount 1

- jdbc.MinLimit 1

- security.requestValidationFunction 1

- security.verifySSL 1

- soda.defaultLimit 1

- soda.maxLimit 1

- 構成ファイル

- 形式 1

- configdirコマンドを使用した検索 1

- 構成フォルダ

- 場所の設定 1

- 構造 1

- CORS (クロス・オリジン・リソース共有) 1 , 2

- CREATE_CLIENTプロシージャ 1

- CREATE_ROLEプロシージャ 1

- CREATE_SERVICEプロシージャ(非推奨) 1

- クロス・オリジン・リソース共有(CORS) 1 , 2

- クロス・サイト・リクエスト・フォージェリ(CSRF)攻撃 1

- CSRF (クロス・サイト・リクエスト・フォージェリ)攻撃 1

- cURL 1

D

- データベース・ユーザー 1

- defaults.xml

- 構成ファイル

- Oracle REST Data Services 1

- デバッグ・トレースの有効化 1

- 詳細なリクエスト・エラー・メッセージの有効化 1

- defaults.xmll, ファイル形式 1

- DEFINE_HANDLERプロシージャ 1

- DEFINE_MODULEプロシージャ 1

- DEFINE_PARAMETERプロシージャ 1

- DEFINE_PRIVILEGEプロシージャ 1

- DEFINE_SERVICEプロシージャ 1

- DEFINE_TEMPLATEプロシージャ 1

- DELETE_CLIENTプロシージャ 1

- DELETE_MODULEプロシージャ 1

- DELETE_PRIVILEGEプロシージャ 1

- DELETE_ROLEプロシージャ 1

- 配布オプション

- GlassFish Server 1

- Oracle WebLogic Server 1

- デプロイ・オプション

- Apache Tomcat 1

- DER

- DERへの秘密鍵の変換 1

- ダウンロード

- Apache Tomcat 1

- GlassFish Server 1

- Oracle WebLogic Server 1

- DROP_REST_FOR_SCHEMAプロシージャ 1

E

- ENABLE_OBJECTプロシージャ 1

- ENABLE_SCHEMAプロシージャ 1

G

- GlassFish Server

- 説明 1

- イメージ用のWARファイルの作成 1

- デプロイ 1

- ダウンロード 1

- デプロイのインストール 1 , 2

- GRANT_CLIENT_ROLEプロシージャ 1

- グラフィカル・ユーザー・インタフェースの管理 1

I

- イメージ・ギャラリの例 1

- インストール・オプション

- スタンドアロン・モード 1

- インストールの概要 1

J

- Java EEアプリケーション・サーバー

- サポート対象について 1

- JSON

- パラメータを渡すために使用 1

M

- 複数データベースの構成

- リクエストURLについて 1

- 追加データベースの構成 1

- リクエストのルーティング・ルール 1

- URL接頭辞に基づくリクエストのルーティング 1

N

- NoSQL

- Oracle REST Data Services 1

O

- OAuth2, デフォルトの動作 1

- OAUTHパッケージ

- CREATE_CLIENT 1

- DELETE_CLIENT 1

- GRANT_CLIENT_ROLE 1

- RENAME_CLIENT 1

- REVOKE_CLIENT_ROLE 1

- UPDATE_CLIENT 1

- Oracle GlassFish Server

- 管理コンソールの起動 1

- Oracle REST Data Services

- 説明 1

- アップグレードについて 1

- グラフィカル・ユーザー・インタフェースによる管理 1

- Bequeath接続 1

- キャッシュ 1

- 構成ファイル

- defaults.xml 1

- 構成ファイル 1

- 構成 1 , 2 , 3

- 複数データベースの構成 1

- コマンドライン・インタフェースによる構成 1 , 2

- データベース・ユーザー 1

- RESTfulサービスの開発 1

- ダウンロード 1

- 環境 1

- Excelの設定 1

- インストールの概要 1

- インストール 1

- PL/SQL API

- Oracle REST Data ServicesのPL/SQL API 1

- 前処理と後処理 1

- スタンドアロン・モードでの実行 1

- セキュリティ 1

- システム要件 1

- NoSQLとの併用 1

- Oracle REST Data Servicesの構成ファイル

- デバッグ・トレースの有効化 1

- 詳細なリクエスト・エラー・メッセージの有効化 1

- Oracle WebLogic Server

- 説明 1

- デプロイ 1

- ダウンロード 1

- インストール 1

- デプロイのインストール 1

- ORDSパッケージ

- CREATE_ROLE 1

- CREATE_SERVICE (非推奨) 1

- DEFINE_HANDLER 1

- DEFINE_MODULE 1

- DEFINE_PARAMETER 1

- DEFINE_PRIVILEGE 1

- DEFINE_SERVICE 1

- DEFINE_TEMPLATE 1

- DELETE_MODULE 1

- DELETE_PRIVILEGE 1

- DELETE_ROLE 1

- DROP_REST_FOR_SCHEMA 1

- ENABLE_OBJECT 1

- ENABLE_SCHEMA 1

- PUBLISH_MODULE 1

- RENAME_MODULE 1

- RENAME_PRIVILEGE 1

- RENAME_ROLE 1

- SET_MODULE_ORIGINS_ALLOWED 1

- SET_URL_MAPPING 1

P

- パラメータの引渡し

- JSONの使用, 1

- 問合せ文字列の使用 1

- ルート・パターンの使用 1

- 秘密鍵

- DERへの変換 1

- PUBLISH_MODULEプロシージャ 1

R

- RENAME_CLIENTプロシージャ 1

- RENAME_MODULEプロシージャ 1

- RENAME_PRIVILEGEプロシージャ 1

- RENAME_ROLEプロシージャ 1

- リソース・ハンドラ 1

- リソース・モジュール 1

- リソース・テンプレート 1

- RESTfulサービス

- 説明 1

- サード・パーティ・アプリケーションからのアクセス 1

- クロス・オリジン・リソース共有用の構成 1

- 開発 1

- 使用する前に 1

- イメージ・ギャラリの例 1

- 既存のグループ/ロール・モデルとの統合 1

- サンプル・サービス 1

- 保護 1

- 用語 1

- ユーザー・ロール 1

- cURLの使用 1

- REVOKE_CLIENT_ROLEプロシージャ 1

- role-mapping.xmlファイル 1

- ルート・パターン 1

S

- 同一生成元ポリシー 1

- SET_MODULE_ORIGINS_ALLOWEDプロシージャ 1

- SET_URL_MAPPINGプロシージャ 1

- SQL DeveloperのOracle REST Data Servicesの管理 1

- スタンドアロン・モード

- 起動 1

- サーバーの停止 1

- スタンドアロン・モード, 実行 1

- 構成フォルダの構造 1

- サポートされるJava EEアプリケーション・サーバー 1

- システム要件 1

T

- トラブルシューティング

- デバッグ・トレースの有効化 1

- 詳細なリクエスト・エラー・メッセージの有効化 1

U

- UPDATE_CLIENTプロシージャ 1

- アップサート操作 1

- URIパターン 1

- URIテンプレート 1

- url-mapping.xml

- ファイル形式 1

- リクエスト・ルールのルーティング 1

- RESTfulサービス用のユーザー・ロール 1

- 問合せ文字列の使用

- オプションのパフォーマンスを渡す 1

- ルート・パターンの使用

- 必須パラメータを渡すため 1

Oracleの法律上の注意点

コピーライト

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およびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

Pre-General Availability (一般提供前)版のドキュメントについて

このドキュメントがPre-General Availability (一般提供前)版の場合:

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

非公開のPre-General Availability (一般提供前)版のドキュメントについて

このドキュメントが非公開のPre-General Availability (一般提供前)版の場合:

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

このドキュメントには、ソフトウェアまたは印刷物などの形式を問わず、オラクルが独占的な権利を有する財産的情報が含まれています。この機密資料へのアクセスと使用は、お客様とオラクルとの間で締結され、お客様が遵守に同意した、Oracle Master Agreement、Oracle License and Oracle Services Agreement (オラクル・ライセンスおよびサービスに関する契約書)、Oracle Partner Network 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)を参照してください。