Autonomous DatabaseでのRESTのためのSODAの使用

Autonomous DatabaseによるRESTのためのSODAの使用

Autonomous Databaseでは、REST用のSimple Oracle Document Access (SODA)がサポートされています。

SODA for RESTの使用の概要
「SODA for RESTは、JSONドキュメントをデータベースに格納するために使用できる事前デプロイ済RESTサービスです」。
SODA for RESTを使用したオーダー・サンプル・データのロード
Oracleには、プレーン・テキスト・ファイルPOList.json内のJSON購買オーダーの実質的なセットがオブジェクトのJSON配列として用意されており、このような各オブジェクトは文書を表します。
SODA for RESTをOAuthクライアント資格証明とともに使用
OAuth認証を使用して、Autonomous DatabaseのSODA for RESTにアクセスできます。アプリケーションに応じて、OAuth認証を使用してSODA for RESTにアクセスすると、パフォーマンスおよびセキュリティを向上できます。

親トピック: Autonomous DatabaseでのRESTfulサービスの開発

SODA for RESTの使用の概要

SODA for RESTは、JSONドキュメントをデータベースに格納するために使用できる事前デプロイ済RESTサービスです。

SODAを使用すると、SQLを使用しなくても、NoSQL形式の柔軟なアプリケーション開発が可能になります。 SODAでは、JSONドキュメントは名前付きコレクションに格納され、単純なCRUD操作(作成、読取り、更新および削除)を使用して管理されます。また、SQLは必須ではありませんが、SODAコレクションに格納されたJSONは、必要に応じてSQLから完全にアクセスできます。たとえば、業務用アプリケーションは、(SQLなしで) SODAを使用して完全に作成できますが、後でデータはアプリケーションの外部からSQLを使用して分析できます。 Autonomous Database SODAを使用すると、アプリケーション開発者はNoSQLおよびSQLの最適な機能を利用できます。 - アナリティクスおよびレポート作成のためにSQLを活用する機能を失うことなく、高速で柔軟なスケーラブルなアプリケーション開発。

SODA for RESTはORDSに次のURLパターンでデプロイされます(schemaはREST対応のデータベース・スキーマに対応します)。

/ords/schema/soda/latest/*

次の例では、cURLコマンドライン・ツール(http://curl.haxx.se/)を使用して、RESTリクエストをデータベースに送信します。ただし、サード・パーティのRESTクライアントおよびライブラリも動作する必要があります。この例では、REST対応のデータベース・スキーマADMINを使用します。 cURLコマンドを使用したRESTのためのSODAは、「Oracle Cloudシェル」から実行できます。

このコマンドは、fruitという名前の新しいコレクションをADMINスキーマに作成します:

> curl -X PUT -u 'ADMIN:<password>' \
"https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

次のコマンドにより、3つのJSONドキュメントをfruitコレクションに挿入します:

> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" --data '{"name":"orange", "count":42}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

{"items":[{"id":"6F7E5C60197E4C8A83AC7D7654F2E375"...
 
> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" --data '{"name":"pear", "count":5}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

{"items":[{"id":"83714B1E2BBA41F7BA4FA93B109E1E85"...
 
> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" \
 --data '{"name":"apple", "count":12, "color":"red"}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

{"items":[{"id":"BAD7EFA9A2AB49359B8F5251F0B28549"...

この例では、コレクションから格納されたJSONドキュメントを取得します:

> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" --data '{"name":"orange"}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit?action=query"

{
  "items": [
    {
      "id":"6F7E5C60197E4C8A83AC7D7654F2E375",
      "etag":"57215643953D7C858A7CB28E14BB48549178BE307D1247860AFAB2A958400E16",
      "lastModified":"2019-07-12T19:00:28.199666Z",
      "created":"2019-07-12T19:00:28.199666Z",
      "value":{"name":"orange", "count":42}
    }
  ],
  "hasMore":false,
  "count":1
}

次のSQL問合せは、fruitコレクションにアクセスします:

SELECT 
     f.json_document.name,
     f.json_document.count,
     f.json_document.color
FROM fruit f;

この問合せでは、次の3つの行が返されます:

name      count     color
--------- --------- -------
orange    42        null
pear      5         null
apple     12        red

ノート:

Always Free Autonomous DatabaseをOracle Database 23aiとともに使用している場合、Oracleでは次のことをお薦めします:

Oracle Database 21cより前のデータベース・リリースを使用して開始されたプロジェクトの場合、SODAドライバの項の例で指定されているように、デフォルト・コレクションのメタデータを明示的に指定します。リリースOracle Database 21c以降を使用して開始されたプロジェクトの場合は、デフォルト・メタデータのみを使用します。詳細については、「SODAドライバ」を参照してください。

次の例は、SODAおよびSQL/JSON機能のサブセットを示しています。詳細は、次を参照してください:

Simple Oracle Document Access (SODA)の詳細は、「REST用のSODA」を参照してください
SODA for REST HTTP操作の詳細は、「REST HTTP操作用のSODA」を参照してください

親トピック: Autonomous DatabaseでのSODA for RESTの使用

SODA for RESTを使用した発注書サンプル・データのロード

Oracleには、プレーン・テキスト・ファイルPOList.json内のJSONPurchase-Orderの実質的なセットがオブジェクトのJSON配列として用意されており、このような各オブジェクトは文書を表します。

次の例では、cURLコマンドライン・ツール(http://curl.haxx.se/)を使用して、RESTリクエストをデータベースに送信します。ただし、サード・パーティのRESTクライアントおよびライブラリも動作する必要があります。この例では、REST対応のデータベース・スキーマADMINを使用します。 SODA for RESTは、「Oracle Cloudシェル」からcURLコマンドとともに使用できます。

次のcurlコマンドを使用して、Autonomous Database with SODA for RESTのコレクションpurchaseorderにこのサンプル購買オーダー・データ・セットをロードできます:

curl -X GET "https://raw.githubusercontent.com/oracle/db-sample-schemas/master/order_entry/POList.json" -o POList.json

curl -X PUT -u 'ADMIN:password' \
"https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/purchaseorder"

curl -X POST -H -u 'ADMIN:password' 'Content-type: application/json' -d @POList.json \
"https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/purchaseorder?action=insert"

その後、この購買オーダー・データを使用して、「Oracle Database JSON開発者ガイド」で例を試すことができます。

たとえば、次の問合せでは、JSONドキュメントのidと、表purchaseorderの列json_documentに格納されているJSONPurchase-Orderコレクションの値の両方が選択されます。選択した値は、JSON列json_documentのフィールドPONumber、ReferenceおよびRequestorから取得され、仮想列としてドキュメントから投影されます(詳細は、「JSON_TABLEのかわりのSQL NESTED句」を参照してください)。

SELECT id, t.*
  FROM purchaseorder
    NESTED json_document COLUMNS(PONumber, Reference, Requestor) t;

詳細は、次を参照してください:

Simple Oracle Document Access (SODA)の詳細は、「REST用のSODA」を参照してください
SODA for REST HTTP操作の詳細は、「REST HTTP操作用のSODA」を参照してください

親トピック: Autonomous DatabaseでのSODA for RESTの使用

OAuthクライアント資格証明によるRESTのためのSODAの使用

OAuth認証を使用して、Autonomous Database上のRESTのためのSODAにアクセスできます。アプリケーションに応じて、OAuth認証を使用してSODA for RESTにアクセスすると、パフォーマンスおよびセキュリティを向上できます。

OAuth認証を使用してAutonomous Database上のSODA for RESTへのアクセスを制限するには、次のステップを実行します:

ADMINユーザーとして、データベース・アクションにアクセスし、必要な権限を持つユーザーを作成します。
1. ADMINとしてデータベース・アクションにアクセスします。
  詳細については、「ADMINとしてのデータベース・アクションへのアクセス」を参照してください。
2. データベース・アクションで、をクリックして使用可能なアクションを表示します。
3. データベース・アクションで、「管理」の下の「データベース・ユーザー」を選択します。
4. 「ユーザーの作成」をクリックします。
5. 「ユーザーの作成」領域の「ユーザー」タブで、「ユーザー名」および「パスワード」を入力し、パスワードを確認します。
6. 「Webアクセス」を選択します。
7. 「ユーザーの作成」領域で「付与されたロール」タブを選択し、DWROLEをユーザーに付与します。
8. 「ユーザーの作成」をクリックします。
詳細については、「Autonomous Databaseでのユーザーおよびユーザー・ロールの管理 - データベース・アクションによる接続」を参照してください。
データベース・アクションのSQLワークシートを使用して、データのロードに必要なユーザー権限を付与します。
1. ADMINとしてデータベース・アクションにアクセスします。
  詳細については、「ADMINとしてのデータベース・アクションへのアクセス」を参照してください。
2. データベース・アクションで、をクリックして使用可能なアクションを表示します。
3. データベース・アクションで、「開発」の下のSQLをクリックしてSQLワークシートを開きます。
4. ステップ1のユーザーにデータをロードするために必要なユーザー権限を付与します。
```
GRANT UNLIMITED TABLESPACE TO user_name;
```
詳細については、「Autonomous Databaseでのユーザー権限の管理 - クライアント・ツールによる接続」を参照してください。
ADMINユーザーとしてサインアウトします。
OAuth認証を使用するように設定されているユーザーとしてデータベース・アクションにサインインします。
データベース・アクションで、SQLワークシートを使用してOAuthクライアントを登録します。
1. OAuthクライアントを登録します。
  たとえば、SQLワークシートに次のコマンドを入力して、ユーザーおよびクライアント・アプリケーションに適切な値を指定します。
```
BEGIN
  OAUTH.create_client(
    p_name            => 'my_client',
    p_grant_type      => 'client_credentials',
    p_owner           => 'Example Company',
    p_description     => 'A client for my SODA REST resources',
    p_support_email   => 'user_name@example.com',
    p_privilege_names => 'my_priv'
  );
 
  OAUTH.grant_client_role(
    p_client_name => 'my_client',
    p_role_name   => 'SQL Developer'
  );
 
  OAUTH.grant_client_role(
    p_client_name => 'my_client',
    p_role_name   => 'SODA Developer'
  );
  COMMIT;
END;
/
```
2. SQLワークシートで、「スクリプトの実行」をクリックしてコマンドを実行します。
詳細については、「OAUTH PL/SQLパッケージのリファレンス」を参照してください。

これにより、OAuthクライアント資格証明を使用してmy_priv権限にアクセスするためのmy_clientという名前のクライアントが登録されます。
アクセス・トークンの生成に必要なclient_idおよびclient_secretを取得します。
たとえば、SQLワークシートで次のコマンドを実行します:
```
SELECT id, name, client_id, client_secret FROM user_ords_clients;
```
アクセス・トークンを取得します。アクセス・トークンを取得するには、REST GETリクエストをdatabase_ORDS_urluser_name/oauth/tokenに送信します。

database_ORDS_urlは、「RESTfulサービスとソーダ」カードの「関連サービス」の下にあるデータベース・アクションから使用できます。詳細については、「REST用のRESTfulサービスおよびSODAへのアクセス」を参照してください。

次のコマンドでは、ステップ6で取得したclient_idおよびclient_secretを使用します。
次の例では、cURLコマンドライン・ツール(http://curl.haxx.se/)を使用して、RESTリクエストをAutonomous Databaseに送信します。ただし、サード・パーティのRESTクライアントおよびライブラリも動作する必要があります。
cURLコマンドライン・ツールを使用して、REST GETリクエストを送信できます。たとえば:
```
> curl -i -k --user SBA-iO9Xe12cdZHYfryBGQ..:vvUQ1AagTqAqdA2oN7afSg.. --data "grant_type=client_credentials"https://mqssyowmqvgac1y-doc.adb.region.oraclecloudapps.com/ords/user_name/oauth/token
HTTP/1.1 200 OK
Date: Mon, 22 Jun 2020 15:17:11 GMT
Content-Type: application/jsonTransfer-Encoding: chunked
Connection: keep-alive
X-Frame-Options: SAMEORIGIN  

{"access_token":"JbOKtAuDgEh2DXx0QhvPGg","token_type":"bearer","expires_in":3600}
```
curl --user引数を使用してclient_idとclient_secretの両方を指定するには、client_idとclient_secretを区切るコロンを入力します。ユーザー名、client_idおよびcurlのみを指定すると、パスワードの入力を求められ、プロンプトでclient_secretを入力できます。

アクセス・トークンを使用して、保護されたリソースにアクセスします。

前のステップで取得したトークンは、Authorizationヘッダーに渡されます。たとえば:

> curl -i -H "Authorization: Bearer JbOKtAuDgEh2DXx0QhvPGg" -X GET https://database_id.adb.region.oraclecloudapps.com/ords/user_name/soda/latest
HTTP/1.1 200 OK
Date: Mon, 22 Jun 2020 15:20:58 GMT
Content-Type: application/json
Content-Length: 28
Connection: keep-alive
X-Frame-Options: SAMEORIGIN
Cache-Control: private,must-revalidate,max-age=0


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

RESTful Servicesへのセキュアなアクセスの詳細は、「RESTfulサービスへのセキュア・アクセスの構成」を参照してください。

親トピック: Autonomous DatabaseでのSODA for RESTの使用