4 REST対応SQLサービス
REST対応SQLサービスはOracle Database SQLエンジンへのアクセスを提供するHTTPS Webサービスです。SQL文をサービスにPOSTできます。その後、サービスはOracle Databaseに対してSQL文を実行し、結果をクライアントにJSON形式で返します。
静的に定義されたRESTfulサービスでは、事前定義されたSQL文が使用され、固定および繰返し可能なサービスを必要とする際に役立ちます。REST対応SQLサービスでは、SQL文を動的に定義して、事前定義されたSQL文を使用せずにデータベースに対して実行できます。このため、RESTを介してデータにアクセスしやすくなります。
一般的なユースケース: Oracle Databaseがクラウド内にあり、HTTPS経由でREST APIを介して使用可能にする必要があります。
事前定義されたREST APIにより、レポートの結果を返したり、データベース内の共通表を更新するためのAPIを提供するなど、一般的な操作が提供されます。クライアント開発者が自分の問合せや、実行時にのみ書き込み可能な問合せを実行する必要があります。このような場合、REST対応SQLサービスは便利です。
注意:
Oracle REST Data Servicesをインストールしてあり、Oracle Databaseへのネットワーク接続を確立するためのSQL*Net (JDBC、OCI)がない場合は、REST対応SQLサービスによって、REST対応Oracleデータベース・スキーマに対してSQL、SQL*PlusおよびSQLcl文を問合せおよび実行するための簡単なメカニズムを使用できます。4.1 REST対応SQLサービスの用語
この項では、このドキュメント全体で使用されている共通の用語をいくつか紹介します。
-
REST対応SQLサービス: データベースへのSQLアクセスを提供するHTTPS Webサービス。SQL文をサービスにポストでき、結果がクライアントにJSON形式で返されます。
-
HTTPS: Hyper Text Transfer Protocol Secure(HTTPS)は、ブラウザと接続しているWebサイトの間でデータ送信に使用されるプロトコルであるHTTPのセキュアなバージョンです。Sはセキュアの略語です。ブラウザとOracle REST Data Servicesの間の通信がすべてが暗号化されることを意味します。
-
cURL: cURLはデータの転送に使用するコマンドライン・ツールです。無料のオープン・ソース・ソフトウェアであり、次の場所からダウンロード可能です。curl_haxx
- SQL*Net(またはNet8): SQL*Netは、プログラムとOracle Databaseの間のリモート・データ・アクセスを可能にするOracleのネットワーキング・ソフトウェアです。
4.2 REST対応SQLサービスの構成
デフォルトでは、REST対応SQLサービスがオフになっています。REST対応SQLサービス設定を構成するには、「REST対応SQLサービス設定の構成」を参照してください。
4.3 REST対応SQLサービスでのcURLの使用
この項では、cURLコマンドを使用してREST対応SQLサービスにアクセスする方法について説明します。
HTTPS POSTメソッドを使用して、REST対応SQLサービスにアクセスできます。REST対応SQLサービスにアクセスするには、cURLという名前のコマンドライン・ツールを使用できます。この強力なツールはほとんどのプラットフォームで使用可能で、REST対応SQLサービスとの間で送受信されるデータを接続および制御できます。
例4-1 cURLコマンドの例
リクエスト: curl -i -X POST --user ORDSTEST:ordstest --data-binary "select sysdate from dual" -H "Content-Type: application/sql" -k https://localhost:8088/ords/ordstest/_/sql
説明:
-
-iオプションを指定すると、サーバーから戻されたHTTPヘッダーが表示されます。 -
-kオプションを指定すると、安全でないとみなされるサーバー接続の場合でも、cURLを続行および操作できます。
レスポンス:
HTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"query",
"statementPos":{
"startLine":1,
"endLine":2
},
"statementText":"select sysdate from dual",
"response":[
],
"result":0,
"resultSet":{
"metadata":[
{
"columnName":"SYSDATE",
"jsonColumnName":"sysdate",
"columnTypeName":"DATE",
"precision":0,
"scale":0,
"isNullable":1
}
],
"items":[
{
"sysdate":"2017-07-21T08:06:44Z"
}
],
"hasMore":false,
"limit":1500,
"offset":0,
"count":1
}
}
]
}4.4 REST対応SQLサービスのスタート・ガイド
REST対応SQLサービスはHTTPS POSTメソッドを介してのみ提供されます。
4.4.1 Oracle DatabaseスキーマのREST対応
REST対応SQLサービスを使用するOracle DatabaseスキーマをREST対応にする必要があります。Oracle DatabaseスキーマをREST対応にするには、SQL DeveloperまたはPL/SQL APIを使用できます。
ORDSTESTをREST対応にする方法を示しています。SQL> CONNECT ORDSTEST/*****;
Connected
SQL> exec ords.enable_schema;
anonymous block completed
SQL> commit;
Commit complete.
SQL>関連トピック
4.4.2 REST対応SQL認証
この項では、REST対応SQLサービスを使用するスキーマを認証する方法について説明します。
REST対応SQLサービスを使用する前に、SQL Developerロールを使用して認証する必要があります。
-
ファースト・パーティ認証(BASIC認証): この認証の場合、SQL Developerロールを持つOracle REST Data Servicesのユーザーを作成します。このOracle REST Data Servicesユーザーは、REST対応の任意のOracle Databaseスキーマに対してSQLを実行できるようになります。
-
スキーマ認証: この認証の場合、大文字のOracle Databaseスキーマ名とOracle Databaseスキーマのパスワードを使用します(たとえば
HRとHRPassword)。このタイプのユーザーは、指定したスキーマに対してSQLを実行できるようになります。Oracle REST Data ServicesによってSQL Developerロールが付与されます。 -
OAuth 2クライアント資格証明: この認証では、次のステップを実行してOracle REST Data ServicesのクライアントにSQL Developerロールを付与します。
-
OAUTH.create_clientを使用してクライアントを作成します。 -
SQL Developerロールをクライアントに付与します。
-
クライアントの
client_idおよびclient_secretを使用してアクセス・トークンを取得します。 -
後続のREST対応SQLリクエストでアクセス・トークンを指定します。
-
4.4.3 REST対応SQLエンドポイント
この項では、REST対応SQLサービスへのアクセスに使用する形式またはパターンを示しています。
Oracle REST Data ServicesがJava EEアプリケーション・サーバーで実行されている場合、REST対応SQLサービスにはHTTPSを介してのみアクセスできます。Oracle REST Data Servicesがスタンドアロン・モードで実行されている場合、Oracle REST Data ServicesがHTTPSを使用するように構成できます。このドキュメントの例ではこの構成を使用します。
次のURLの例では、指定したスキーマ別名のREST対応SQLサービスが特定されます。
パターン: https://<HOST>/ords/<SchemaAlias>/_/sql
例: https://host/ords/ordstest/_/sql
説明: デフォルト・ポートは443
サポートされるコンテンツ・タイプおよびペイロード・データ型
-
ヘッダーContent-Type
-
application/sql: SQL文を表す -
application/json: JSONドキュメントを表す
-
-
ペイロードのデータ型
-
SQL: SQL、PL/SQL、SQL*Plus、SQLcl文
-
JSONドキュメント:SQL文、およびバインド変数などのその他のオプションを持つJSONドキュメント
-
4.5 REST対応SQLサービスの例
この項では、セキュアなHTTPSアクセスでOracle REST Data Servicesのスタンドアロン設定を使用する、別のHTTPS POSTリクエストの例を示します。
HTTPS POSTリクエスト・メッセージのペイロード・データは、次のいずれかの形式になります。
4.5.1 application/sql Content-Typeを使用するPOSTリクエスト
application/sqlとしてのContent-Typeを持つPOSTリクエストの場合、SQL、SQL*PlusおよびSQLcl文を使用してペイロードが指定されます。次の例に示すように、ペイロードは単一行の文、複数行の文、または複数行の文で構成されるファイルにすることができます。
4.5.1.1 単一のSQL文の使用
次の例では、スキーマ認証を使用して、demo Oracle Databaseスキーマに対して1つのSQL文を実行します。
リクエスト:
curl -i -X POST --user DEMO:demo --data-binary "select sysdate from dual" -H "Content-Type: application/sql" -k https://localhost:8088/ords/demo/_/sqlHTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"query",
"statementPos":{
"startLine":1,
"endLine":2
},
"statementText":"select sysdate from dual",
"response":[
],
"result":0,
"resultSet":{
"metadata":[
{
"columnName":"SYSDATE",
"jsonColumnName":"sysdate",
"columnTypeName":"DATE",
"precision":0,
"scale":0,
"isNullable":1
}
],
"items":[
{
"sysdate":"2017-07-21T08:06:44Z"
}
],
"hasMore":false,
"limit":1500,
"offset":0,
"count":1
}
}
]
}説明:
-
DEMOはOracle Databaseスキーマの名前です。 -
demoはOracle Databaseスキーマのパスワードです。 -
select sysdate from dualは、DEMOOracle Databaseスキーマで実行されるSQL文です。 -
Content-Type: application/sqlはコンテンツ・タイプです。application/sqlとapplication/jsonのみがサポートされます。 -
https://localhost:8088/ords/demo/_/sqlは、demoOracle DatabaseスキーマのREST対応SQLサービスの場所です。
4.5.1.2 cURLを使用したファイルの使用
複数行のSQL文の場合、リクエストでファイルをペイロード・データとして使用するのが便利です。
ファイル: simple_query.sql
SELECT 10
FROM dual;リクエスト:
curl -i -X POST --user DEMO:demo --data-binary "@simple_query.sql" -H "Content-Type: application/sql" -k https://localhost:8088/ords/demo/_/sql
HTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"query",
"statementPos":{
"startLine":1,
"endLine":1
},
"statementText":"SELECT 10 FROM dual",
"response":[
],
"result":0,
"resultSet":{
"metadata":[
{
"columnName":"10",
"jsonColumnName":"10",
"columnTypeName":"NUMBER",
"precision":0,
"scale":-127,
"isNullable":1
}
],
"items":[
{
"10":10
}
],
"hasMore":false,
"limit":1500,
"offset":0,
"count":1
}
}
]
}4.5.1.3 複数のSQL文の使用
各POSTリクエストで1つ以上の文を実行できます。文の区切りは、SQL*Plus文の行末、SQL文のセミコロン、およびPL/SQL文のスラッシュ(/)など、Oracle DatabaseのSQL*Plusスクリプトの構文と類似しています。
script.sql:CREATE TABLE T1 (col1 INT);
DESC T1
INSERT INTO T1 VALUES(1);
SELECT * FROM T1;
BEGIN
INSERT INTO T1 VALUES(2);
END;
/
SELECT * FROM T1;リクエスト: curl -i -X POST --user DEMO:demo --data-binary "@script.sql" -H "Content-Type: application/sql" -k https://localhost:8088/ords/demo/_/sql
HTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"ddl",
"statementPos":{
"startLine":1,
"endLine":1
},
"statementText":"CREATE TABLE T_EXAMPLE1 (col1 INT)",
"response":[
"\nTable T_EXAMPLE1 created.\n\n"
],
"result":0
},
{
"statementId":2,
"statementType":"sqlplus",
"statementPos":{
"startLine":2,
"endLine":2
},
"statementText":"DESC T_EXAMPLE1",
"response":[
"Name Null\n Type \n---- ----- ---------- \nCOL1 NUMBER(38) \n"
],
"result":0
},
{
"statementId":3,
"statementType":"dml",
"statementPos":{
"startLine":3,
"endLine":3
},
"statementText":"INSERT INTO T_EXAMPLE1 VALUES(1)",
"response":[
"\n1 row inserted.\n\n"
],
"result":1
},
{
"statementId":4,
"statementType":"query",
"statementPos":{
"startLine":4,
"endLine":4
},
"statementText":"SELECT * FROM T_EXAMPLE1",
"response":[
],
"result":1,
"resultSet":{
"metadata":[
{
"columnName":"COL1",
"jsonColumnName":"col1",
"columnTypeName":"NUMBER",
"precision":38,
"scale":0,
"isNullable":1
}
],
"items":[
{
"col1":1
}
],
"hasMore":false,
"limit":1500,
"offset":0,
" count":1
}
},
{
"statementId":5,
"statementType":"plsql",
"statementPos":{
"startLine":5,
"endLine":8
},
"statementText":"BEGIN\n INSERT INTO T_EXAMPLE1 VALUES(2);\nEND;",
"response":[
"\nPL\/SQL procedure successfully completed.\n\n"
],
"result":1
},
{
"statementId":6,
"statementType":"query",
"statementPos":{
"startLine":9,
"endLine":9
},
"statementText":"SELECT * FROM T_EXAMPLE1",
"response":[
],
"result":1,
"resultSet":{
"metadata":[
{
"columnName":"COL1",
"jsonColumnName":"col1",
"columnTypeName":"NUMBER",
"precision":38,
"scale":0,
"isNullable":1
}
],
"items":[
{
"col1":1
},
{
"col1":2
}
],
"hasMore":false,
"limit":1500,
"offset":0,
"count":2
}
},
{
"statementId":7,
"statementType":"ddl",
"statementPos":{
"startLine":10,
"endLine":10
},
"statementText":"DROP TABLE T_EXAMPLE1",
"response":[
"\nTable T_EXAMPLE1 dropped.\n\n"
],
"result":1
}
]
}4.5.2 application/json Content-Typeを使用するPOSTリクエスト
JSONドキュメントをペイロードとして使用すると、次の項で示すように、より複雑なリクエストを定義できます。
4.5.2.1 cURLを使用したファイルの使用
次の例では、JSONドキュメント(simple_query.jsonファイル内)をREST対応SQLサービスにポストします。
ファイル: simple_query.json
{ "statementText":"SELECT TO_DATE('01-01-1976','dd-mm-yyyy') FROM dual;"}
リクエスト: curl -i -X POST --user DEMO:demo --data-binary "@simple_query.json" -H "Content-Type: application/json" -k https://localhost:8088/ords/demo/_/sql
-
statementTextはSQL文(1つまたは複数)を保持します。 -
Content-Typeはapplication/jsonです。
HTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"query",
"statementPos":{
"startLine":1,
"endLine":1
},
"statementText":"SELECT TO_DATE('01-01-1976','dd-mm-yyyy') FROM dual",
"response":[
],
"result":0,
"resultSet":{
"metadata":[
{
"columnName":"TO_DATE('01-01-1976','DD-MM-YYYY')",
"jsonColumnName":"to_date('01-01-1976','dd-mm-yyyy')",
"columnTypeName":"DATE",
"precision":0,
"scale":0,
"isNullable":1
}
],
"items":[
{
"to_date('01-01-1976','dd-mm-yyyy')":"1976-01-01T00:00:00Z"
}
],
"hasMore":false,
"limit":1500,
"offset":0,
"count":1
}
}
]
}4.5.2.2 POSTリクエストでのページ区切りの制限値の指定
問合せから返される膨大な結果セットをページで区切るには、POST JSONリクエストでlimit値を指定できます。
limit.json{
"statementText": "
WITH data(r) AS (
SELECT 1 r FROM dual
UNION ALL
SELECT r+1 FROM data WHERE r < 100
)
SELECT r FROM data;",
"limit": 5
}リクエスト: curl -i -X POST --user DEMO:demo --data-binary "@limit.json" -H "Content-Type: application/json" -k https://localhost:8088/ords/demo/_/sql
limitは問合せから返される行の最大数です。
注意:
問合せから返される行の最大数は、default.xmlファイルに設定されているmisc.pagination.maxRows値に基づいています。
HTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"query",
"statementPos":{
"startLine":1,
"endLine":1
},
"statementText":" WITH data(r) AS ( SELECT 1 r FROM dual UNION ALL SELECT r+1 FROM data WHERE r < 100 ) SELECT r FROM data",
"response":[
],
"result":0,
"resultSet":{
"metadata":[
{
"columnName":"R",
"jsonColumnName":"r",
"columnTypeName":"NUMBER",
"precision":0,
"scale":-127,
"isNullable":1
}
],
"items":[
{
"r":1
},
{
"r":2
},
{
"r":3
},
{
"r":4
},
{
"r":5
}
],
"hasMore":true,
"limit":5,
"offset":0,
"count":5
}
}
]
}関連トピック
4.5.2.3 POSTリクエストでのページ区切りのオフセット値の指定
POST JSONリクエストでoffset値を指定できます。この値は、戻す必要がある最初の行を指定し、問合せから返される結果セットのページ区切りに使用されます。
offset_limit.json{
"statementText": "
WITH data(r) AS (
SELECT 1 r FROM dual
UNION ALL
SELECT r+1 FROM data WHERE r < 100
)
SELECT r FROM data;",
"offset": 25,
"limit": 5
}リクエスト: curl -i -X POST --user DEMO:demo --data-binary "@offset_limit.json" -H "Content-Type: application/json" -k https://localhost:8088/ords/demo/_/sql
説明: offsetは結果セットで戻される最初の行です。一般にこれを使用して、結果セットの行の次のページを返す大規模な結果セットのページ区切りが行われます。
注意:
REST対応SQLサービスへの各リクエストは固有のトランザクションで実行されるので、戻された行が前のリクエストと一致するかどうかを確認できません。これらのリスクを回避するため、ページ区切りを必要とする問合せでは、主キーでORDER BY句を使用する必要があります。HTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"query",
"statementPos":{
"startLine":1,
"endLine":1
},
"statementText":" WITH data(r) AS ( SELECT 1 r FROM dual UNION ALL SELECT r+1 FROM data WHERE r < 100 ) SELECT r FROM data",
"response":[
],
"result":0,
"resultSet":{
"metadata":[
{
"columnName":"R",
"jsonColumnName":"r",
"columnTypeName":"NUMBER",
"precision":0,
"scale":-127,
"isNullable":1
}
],
"items":[
{
"r":26
},
{
"r":27
},
{
"r":28
},
{
"r":29
}
{
"r":30
}
],
"hasMore":true,
"limit":5,
"offset":25,
"count":5
}
}
]
}4.5.2.4 POSTリクエストでのバインドの定義
JSON形式のバインドを定義できます。この機能は、バインドをパラメータとして使用するプロシージャおよびファンクションをコールする場合に便利です。
例4-2 POSTリクエストでのバインド
binds.json{
"statementText": "CREATE PROCEDURE TEST_OUT_PARAMETER (V_PARAM_IN INT IN, V_PARAM_OUT INT OUT) AS BEGIN V_PARAM_OUT := V_PARAM_IN + 10; END;
/
EXEC TEST_OUT_PARAMETER(:var1, :var2)",
"binds":[
{"name":"var1","data_type":"NUMBER","value":10},
{"name":"var2","data_type":"NUMBER","mode":"out"}
]
}リクエスト: curl -i -X POST --user DEMO:demo --data-binary "@binds.json" -H "Content-Type: application/json" -k https://localhost:8088/ords/demo/_/sql
HTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"plsql",
"statementPos":{
"startLine":1,
"endLine":2
},
"statementText":"CREATE PROCEDURE TEST_OUT_PARAMETER (V_PARAM_IN IN INT, V_PARAM_OUT OUT INT) AS BEGIN V_PARAM_OUT := V_PARAM_IN + 10; END;",
"response":[
"\nProcedure TEST_OUT_PARAMETER compiled\n\n"
],
"result":0,
"binds":[
{
"name":"var1",
"data_type":"NUMBER",
"value":10
},
{
"name":"var2",
"data_type":"NUMBER",
"mode":"out",
"result":null
}
]
},
{
"statementId":2,
"statementType":"sqlplus",
"statementPos":{
"startLine":3,
"endLine":3
},
"statementText":"EXEC TEST_OUT_PARAMETER(:var1, :var2)",
"response":[
"\nPL\/SQL procedure successfully completed.\n\n"
],
"result":0,
"binds":[
{
"name":"var1",
"data_type":"NUMBER",
"value":10
},
{
"name":"var2",
"data_type":"NUMBER",
"mode":"out",
"result":20
}
]
}
]
}例4-3 POSTリクエストでの複合バインド
ファイル:complex_bind_example.json{
"statementText":"
declare
type t is table of number index by binary_integer;
l_in t := :IN;
l_out t;
begin
for i in 1..l_in.count loop
l_out(i) := l_in(i) * 2;
end loop;
:L_OUT := l_out;
end;
",
"binds":[
{
"name":"IN",
"data_type":"PL/SQL TABLE",
"type_name":"",
"type_subname":"",
"type_components":[
{
"data_type":"NUMBER"
}
],
"value":[
2,
4,
7
]
},
{
"name":"L_OUT",
"data_type":"PL/SQL TABLE",
"type_name":"",
"type_subname":"",
"type_components":[
{
"data_type":"NUMBER"
}
],
"mode":"out"
}
]
}
リクエスト: curl -i -X POST --user DEMO:demo --data-binary "@complex_bind_example.json" -H "Content-Type: application/json" -k https://localhost:8088/ords/demo/_/sql
HTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"plsql",
"statementPos":{
"startLine":2,
"endLine":12
},
"statementText":"declare \n type t is table of number index by binary_integer; \n l_in t := :IN; \n l_out t; \n begin \n for i in 1..l_in.count loop \n l_out(i) := l_in(i) * 2; \n end loop; \n :L_OUT := l_out; \n end;",
"response":[
],
"result":1,
"binds":[
{
"name":"IN",
"data_type":"PL/SQL TABLE",
"type_components":[
{
"data_type":"NUMBER"
}
],
"type_name":"",
"type_subname":"",
"value":[
2,
4,
7
]
},
{
"name":"L_OUT",
"data_type":"PL/SQL TABLE",
"mode":"out",
"type_components":[
{
"data_type":"NUMBER"
}
],
"type_name":"",
"type_subname":"",
"result":[
4,
8,
14
]
}
]
}
]
}
4.5.2.5 POSTリクエストでのバッチ文の指定
この項では、POSTリクエストでバッチ文およびバッチ・バインド値を使用する例を示します。
例4-4 バッチ文
{
"statementText":[
"insert into adhoc_table_simple values(1)",
"insert into adhoc_table_simple values(2)",
"delete from adhoc_table_simple"
]
}
リクエスト: curl -i -X POST --user DEMO:demo --data-binary "@batch_example.json" -H "Content-Type: application/json" -k https://localhost:8088/ords/demo/_/sql
HTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"dml",
"statementPos":{
"startLine":0,
"endLine":0
},
"statementText":[
"insert into adhoc_table_simple values(1)",
"insert into adhoc_table_simple values(2)",
"delete from adhoc_table_simple"
],
"response":[
"\n1 row inserted.\n\n",
"\n1 row inserted.\n\n",
"\n2 rows inserted.\n\n"
],
"result":[
1,
1,
2
]
}
]
}
例4-5 バッチ・バインド値
{
"statementText":"INSERT INTO ADHOC_TABLE_DATE VALUES(?,?)",
"binds":[
{
"index":1,
"data_type":"NUMBER",
"batch":true,
"value":[
3,
6,
9,
13,
17
]
},
{
"index":2,
"data_type":"DATE",
"batch":true,
"value":[
"2017-02-21T06:12:20Z",
"2017-02-21T06:12:20Z",
"2017-02-21T06:12:20Z",
"2017-02-21T06:12:20Z",
"2017-02-21T06:12:20Z"
]
}
]
}
リクエスト: curl -i -X POST --user DEMO:demo --data-binary "@batch_bind_example.json" -H "Content-Type: application/json" -k https://localhost:8088/ords/demo/_/sql
HTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"dml",
"statementPos":{
"startLine":1,
"endLine":2
},
"statementText":"INSERT INTO ADHOC_TABLE_DATE VALUES(?,?)",
"response":[
"\n1 row inserted.\n\n",
"\n1 row inserted.\n\n",
"\n1 row inserted.\n\n",
"\n1 row inserted.\n\n",
"\n1 row inserted.\n\n"
],
"result":[
1,
1,
1,
1,
1
],
"binds":[
{
"index":1,
"data_type":"NUMBER",
"batch":true,
"value":[
3,
6,
9,
13,
17
]
},
{
"index":2,
"data_type":"DATE",
"batch":true,
"value":[
"2017-02-21T06:12:20Z",
"2017-02-21T06:12:20Z",
"2017-02-21T06:12:20Z",
"2017-02-21T06:12:20Z",
"2017-02-21T06:12:20Z"
]
}
]
}
]
}
4.5.3 DATEおよびTIMESTAMP形式を使用するPOSTリクエストの例
例4-6 ヨーロッパ/ロンドンとして設定したOracle REST Data Servicesタイムゾーン
Oracle DatabaseのDATEおよびTIMESTAMPデータ型には、関連付けられているタイムゾーンはありません。DATEおよびTIMESTAMP値はアプリケーションのタイムゾーンに関連付けられます。Oracle REST Data ServicesおよびREST対応SQLサービスからは、値がJSON形式で戻されます。JSONの標準では、UTCズールー形式を使用して日付およびタイムスタンプ値が戻されます。Oracle REST Data ServicesおよびREST対応SQLサービスは、Oracle REST Data Servicesが実行されているタイムゾーンを使用して、Oracle DatabaseのDATEおよびTIMESTAMP値をズールー形式で戻します。
このプロセスをさらに容易にするために、UTCタイムゾーンを使用してOracle REST Data Servicesを実行することをお薦めします。
date.json{
"statementText":"SELECT TO_DATE('2016-01-01 10:00:03','yyyy-mm-dd hh24:mi:ss' ) winter, TO_DATE('2016-07-01 10:00:03','yyyy-mm-dd hh24:mi:ss' ) summer FROM dual;"
}リクエスト: curl -i -X POST --user DEMO:demo --data-binary "@date.json" -H "Content-Type: application/json" -k https://localhost:8088/ords/demo/_/sql
注意:
この例では、どちらのDATE値も10a.m.として指定されています。"summer"値は午前9時のズールー時間として戻されます。これはイギリスの夏時間によるものです。
HTTP/1.1 200 OK
Date: Wed, 26 Jul 2017 14:59:27 GMT
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
Server: Jetty(9.2.21.v20170120)
{
"env":{
"defaultTimeZone":"Europe/London"
},
"items":[
{
"statementId":1,
"statementType":"query",
"statementPos":{
"startLine":1,
"endLine":1
},
"statementText":"SELECT TO_DATE('2016-01-01 10:00:03','yyyy-mm-dd hh24:mi:ss' ) winter, TO_DATE('2016-07-01 10:00:03','yyyy-mm-dd hh24:mi:ss' ) summer FROM dual",
"response":[
],
"result":0,
"resultSet":{
"metadata":[
{
"columnName":"WINTER",
"jsonColumnName":"winter",
"columnTypeName":"DATE",
"precision":0,
"scale":0,
"isNullable":1
},
{
"columnName":"SUMMER",
"jsonColumnName":"summer",
"columnTypeName":"DATE",
"precision":0,
"scale":0,
"isNullable":1
}
],
"items":[
{
"winter":"2016-01-01T10:00:03Z",
"summer":"2016-07-01T09:00:03Z"
}
],
"hasMore":false,
"limit":1500,
"offset":0,
"count":1
}
}
]
}
4.5.4 サポートされるデータ型と形式
次のコード・スニペットでは、サポートされる様々なデータ型と形式を示します。
{
"statementText":"SELECT ?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,? FROM dual",
"binds":[
{
"index":1,
"data_type":"NUMBER",
"value":1233
},
{
"index":2,
"data_type":"NUMERIC",
"value":123
},
{
"index":3,
"data_type":"DECIMAL",
"value":123
},
{
"index":4,
"data_type":"DEC",
"value":123
},
{
"index":5,
"data_type":"NUMBER",
"value":123
},
{
"index":6,
"data_type":"INTEGER",
"value":123
},
{
"index":7,
"data_type":"INT",
"value":123
},
{
"index":8,
"data_type":"SMALLINT",
"value":123
},
{
"index":9,
"data_type":"FLOAT",
"value":123
},
{
"index":10,
"data_type":"DOUBLE PRECISION",
"value":123
},
{
"index":11,
"data_type":"REAL",
"value":123
},
{
"index":12,
"data_type":"BINARY_FLOAT",
"value":123
},
{
"index":13,
"data_type":"BINARY_DOUBLE",
"value":123
},
{
"index":14,
"data_type":"CHAR",
"value":"abc"
},
{
"index":15,
"data_type":"CHARACTER",
"value":"abc"
},
{
"index":16,
"data_type":"VARCHAR",
"value":"abc"
},
{
"index":17,
"data_type":"VARCHAR2",
"value":"abc"
},
{
"index":18,
"data_type":"CHAR VARYING",
"value":"abc"
},
{
"index":19,
"data_type":"CHARACTER VARYING",
"value":"abc"
},
{
"index":20,
"data_type":"NCHAR",
"value":"abc"
},
{
"index":21,
"data_type":"NATIONAL CHAR",
"value":"abc"
},
{
"index":22,
"data_type":"NATIONAL CHARACTER",
"value":"abc"
},
{
"index":23,
"data_type":"NVARCHAR",
"value":"abc"
},
{
"index":24,
"data_type":"NVARCHAR2",
"value":"abc"
},
{
"index":25,
"data_type":"NCHAR VARYING",
"value":"abc"
},
{
"index":26,
"data_type":"NATIONAL CHAR VARYING",
"value":"abc"
},
{
"index":27,
"data_type":"NATIONAL CHARACTER VARYING",
"value":"abc"
},
{
"index":28,
"data_type":"DATE",
"value":"01-Jan-2016"
},
{
"index":29,
"data_type":"TIMESTAMP",
"value":"1976-02-01T00:00:00Z"
},
{
"index":30,
"data_type":"TIMESTAMP",
"value":"1976-02-01T00:00:00Z"
},
{
"index":31,
"data_type":"TIMESTAMP WITH LOCAL TIME ZONE",
"value":"1976-02-01T00:00:00Z"
},
{
"index":32,
"data_type":"TIMESTAMP WITH TIME ZONE",
"value":"1976-02-01T00:00:00Z"
},
{
"index":33,
"data_type":"INTERVALYM",
"value":"P10Y10M"
},
{
"index":34,
"data_type":"INTERVAL YEAR TO MONTH",
"value":"P10Y10M"
},
{
"index":35,
"data_type":"INTERVAL YEAR(2) TO MONTH",
"value":"P10Y10M"
},
{
"index":36,
"data_type":"INTERVALDS",
"value":"P11DT10H10M10S"
},
{
"index":37,
"data_type":"INTERVAL DAY TO SECOND",
"value":"P11DT10H10M10S"
},
{
"index":38,
"data_type":"INTERVAL DAY(2) TO SECOND(6)",
"value":"P11DT10H10M10S"
},
{
"index":39,
"data_type":"ROWID",
"value":1
},
{
"index":40,
"data_type":"RAW",
"value":"AB"
},
{
"index":41,
"data_type":"LONG RAW",
"value":"AB"
},
{
"index":42,
"data_type":"CLOB",
"value":"clobvalue"
},
{
"index":43,
"data_type":"NCLOB",
"value":"clobvalue"
},
{
"index":45,
"data_type":"LONG",
"value":"A"
}
]
} 4.6 REST対応SQLリクエストおよびレスポンスの仕様
4.6.1 リクエストの仕様
application/sqlのリクエスト仕様
リクエストの本文はUTF8のプレーン・テキストです。文は通常のSQL*Plusの終了文字で区切ることができます。
application/jsonの仕様
| JSONPath | 型 | 説明 | 例 | デフォルト値 | 使用可能な値 |
|---|---|---|---|---|---|
$.statementText |
文字列 |
実行するSQL文を指定します。 |
"select 1 from dual" |
該当なし |
該当なし |
$.statementText |
配列 |
配列を使用するバッチDML文を指定します。1つのDML文は配列内の文字列ごとに指定されます。 |
[ "insert into test1 values(1)","update test1 set col1=2" ] |
該当なし |
該当なし |
$.offset |
数値 |
問合せ結果をオフセットするための行数を指定します。これは、問合せから戻される結果セットのページ区切りに使用されます。 |
25 |
0 |
0からmisc.pagination.maxRowsまでの間です。
|
$.limit |
数値 |
問合せから戻される行の最大数を指定します。
|
500 |
misc.pagination.maxRows |
0からmisc.pagination.maxRowsまでの間です。
|
$.binds |
配列 |
バインド情報を指定するオブジェクトの配列を指定します。 |
"binds":[ { "name":"mybind1", "data_type":"NUMBER", "mode":"out" }, { "name":"mybind2", "data_type":"NUMBER", "value":7 } ] |
該当なし |
該当なし |
$.binds[*].name |
文字列 |
名前表記法を使用している場合、バインドの名前を指定します。 |
"mybind" |
該当なし |
該当なし |
$.binds[*].index |
数値 |
位置表記法を使用している場合、バインドの索引を指定します。 |
1 |
該当なし |
Between 1 to n |
$.binds[*].data_type |
文字列 |
バインドのOracleデータ型を指定します。 |
"NUMBER" |
該当なし |
詳細は、「Oracle組込み型」を参照してください |
$.binds[*].value |
任意の値 |
バインドの値を指定します。 |
"value to insert" |
null |
次のデータ型のいずれかになります。
詳細は、「Oracle組込み型」を参照してください |
$.binds[*].mode |
文字列 |
バインドが使用されるモードを指定します。 |
"out" |
"in" |
[ "in" , "inout", "out" ] |
$.binds[*].batch |
ブール値 |
バッチ・バインドを実行するかどうかを指定します。バッチ・バインドを実行する場合、値を 値を |
true |
false |
[ true, false ] |
$.binds[*].type_name |
文字列 |
現在、空の文字列のみが値として認められています。 |
"" |
該当なし |
該当なし |
$.binds[*].type_subname |
文字列 |
現在、空の文字列のみが値として認められています。 |
"" |
該当なし |
該当なし |
$.binds[*].type_components |
配列 |
PL/SQL TABLEのデータ型の配列を指定します
|
[{"data_type":"NUMBER"}] |
該当なし |
該当なし |
$.binds[*].type_components[*].data_type |
文字列 |
PL/SQL TABLEの列のOracleデータ型を指定します。
|
"NUMBER" |
該当なし |
詳細は、「Oracle組込み型」を参照してください |
4.6.2 レスポンスの仕様
| JSONPath | データ型 | 説明 | 値の例 | 使用可能な値 |
|---|---|---|---|---|
$.env |
オブジェクト |
Oracle REST Data Services環境に関する情報を指定します。 |
該当なし |
該当なし |
$.env.defaultTimeZone |
文字列 |
Oracle REST Data Servicesサーバーが稼働しているタイムゾーンを指定します。 |
"Europe/London" |
該当なし |
$.items |
配列 |
実行される文ごとに1つのアイテムがあることを指定します。 |
該当なし |
該当なし |
$.items[*].statementId |
数値 |
文の順序番号を指定します。 |
1 |
該当なし |
$.items[*].statementType |
文字列 |
文のタイプを指定します。 |
"query" |
[ "query" , "dml", "ddl", "plsql" , "sqlplus" , "ignore", "transaction-control", "session-control", "system-control", "jdbc", "other" ] |
$.items[*].statementPos |
オブジェクト |
指定された文の位置に関する情報を指定します。 |
該当なし |
該当なし |
$.items[*].statementPos.startLine |
数値 |
文の開始行を指定します。 |
該当なし |
該当なし |
$.items[*].statementPos.endLine |
数値 |
文の最後の行を指定します。 |
該当なし |
該当なし |
$items[*].statementText |
文字列 |
実行するSQL文を指定します。 |
"select 1 from dual" |
該当なし |
$items[*].statementText |
配列 |
配列を使用してバッチDML文を指定できるということを指定します。 配列内の文字列ごとに1つのDML文が指定されます。 |
[ "insert into test1 values(1)","update test1 set col1=2" ] |
該当なし |
$.items[*].response |
配列 |
文字列の配列を指定します。文の実行時に生成される応答。 |
[ "\n1 row inserted.\n\n" ] |
該当なし |
$.items[*].result |
数値 |
文の実行時に生成される結果を指定します。 DML文では、影響を受けた行の数になります。 |
5 |
該当なし |
$.items[*].result |
配列 |
バッチの各文を実行したときに生成される結果を指定します。 DML文では、影響を受けた行の数になります。 |
[ 1, 1, 2 ] |
該当なし |
$.items[*].resultSet |
オブジェクト |
問合せから生成された結果セットに関する情報を指定します。 |
該当なし |
該当なし |
$.items[*].resultSet.metadata |
配列 |
配列の各オブジェクトから、列のメタデータに関する情報が提供されるということを指定します。 |
該当なし |
該当なし |
$.items[*].resultSet.metadata[*].columnName |
文字列 |
Oracle Databaseで使用される列の名前を指定します。 |
該当なし |
該当なし |
$.items[*].resultSet.metadata[*].jsonColumnName |
文字列 |
次の場所で使用される列の名前を指定します
|
該当なし |
該当なし |
$.items[*].resultSet.metadata[*].columnTypeName |
文字列 |
列のOracle Databaseデータ型を指定します。 |
該当なし |
該当なし |
$.items[*].resultSet.metadata[*].precision |
数値 |
列の精度を指定します。 |
該当なし |
該当なし |
$.items[*].resultSet.metadata[*].scale |
数値 |
列のスケールを指定します。 |
該当なし |
該当なし |
$.items[*].resultSet.metadata[*].isNullable |
数値 |
列にNULLを使用できるかどうかを指定します。 列にNULLを使用できない場合は0です。 列にNULLを使用できる場合は1です。 |
該当なし |
該当なし |
$.items[*].resultSet.items |
配列 |
結果セットで戻されたすべての行のリストを指定します。 |
該当なし |
該当なし |
$.items[*].resultSet.items[*].<columnname> |
任意の型 |
結果セット内の特定の列および行の値を指定します。 |
該当なし |
該当なし |
$.items[*].resultSet.hasMore |
ブール値 |
結果セットにある行数がこれを超えているかどうかを指定します。結果セットにある行数がこれを超えている場合、値は 結果セットの行は、 |
false |
[ true , false ] |
$.items[*].resultSet.count |
数値 |
戻される行の数を指定します。 |
該当なし |
該当なし |
$.items[*].resultSet.offset |
数値 |
問合せ結果をオフセットするための行数を指定します。これは、問合せから戻される結果セットのページ区切りに使用されます。 |
25 |
0から |
$.items[*].resultSet.limit |
数値 |
問合せから戻される行の最大数を指定します。
|
500 |
0から |
$.items[*].binds |
配列 |
バインド情報を指定するオブジェクトの配列を指定します。 |
"binds":[ { "name":"mybind1", "data_type":"NUMBER", "mode":"out" }, { "name":"mybind2", "data_type":"NUMBER", "value":7 } ] |
該当なし |
$.items[*].binds[*].name |
文字列 |
名前表記法を使用している場合、バインドの名前を指定します。 |
"mybind" |
該当なし |
$.items[*].binds[*].index |
数値 |
位置表記法を使用している場合、バインドの索引を指定します。 |
1 |
1 - n |
$.items[*].binds[*].data_type |
文字列 |
バインドのOracleデータ型を指定します。 |
"NUMBER" |
詳細は、「Oracle組込み型」を参照してください |
$.items[*].binds[*].value |
任意の型 |
バインドの値を指定します。 |
"value to insert" |
次のデータ型のいずれかを指定します。
詳細は、「Oracle組込み型」を参照してください |
$.items[*].binds[*].result |
任意の型 |
OUTバインドの結果を指定します。 |
該当なし |
該当なし |
$.items[*].binds[*].mode |
文字列 |
バインドが使用されるモードを指定します。 |
"out" |
[ "in" , "inout", "out" ] |
$.items[*].binds[*].batch |
ブール値 |
バッチ・バインドを実行するかどうかを指定します。バッチ・バインドを実行する場合、値を バッチ・バインドが実行される場合、値は 値が |
true |
[ true, false ] |
$.items[*].binds[*].type_name |
文字列 |
現在、空の文字列のみが値として認められています。 |
"" |
該当なし |
$.items[*].binds[*].type_subname |
文字列 |
現在、空の文字列のみが値として認められています。 |
"" |
該当なし |
$.items[*].binds[*].type_components |
配列 |
PL/SQL TABLEのデータ型の配列
|
[{"data_type":"NUMBER"}] |
該当なし |
$.items[*].binds[*].type_components[*].data_type |
文字列 |
PL/SQL TABLEの列のOracleデータ型。
|
"NUMBER" |
詳細は、「Oracle組込み型」を参照してください |
4.7 サポートされているSQL、SQL*PlusおよびSQLcl文
この項では、REST対応SQLサービスに対してサポートされるすべてのSQL、SQL*PlusおよびSQLcl文を示します。
4.7.1 サポートされているSQL文
この項では、REST対応SQLサービスでサポートされるSQL文を示します。
REST対応SQLサービスでは、すべてのSQLコマンドがサポートされます。指定されたOracle Databaseスキーマに適切な権限がある場合は、それらを実行できます。Oracle REST Data Servicesでは、ページ区切りをサポートするために、すべての問合せが実行前にインライン・ビューになります。問合せは指定する形式とは関係なく、インラインになります。問合せでないその他すべてのSQL文は、そのまま実行されます。
-
ビューおよびインライン・ビューではあいまいな列名を使用できないので、問合せ内のすべての列名は一意である必要があります。
-
カーソル式は、ビューまたはインライン・ビューには表示されません。
-
WITH FUNCTION句はインライン・ビューではサポートされません。
関連トピック
4.7.2 サポートされているPL/SQL文
REST対応SQLサービスでは、PL/SQL文およびブロックがサポートされます。
例4-7 PL/SQL文
DECLARE v_message VARCHAR2(100) := 'Hello World';
BEGIN
FOR i IN 1..3 LOOP
DBMS_OUTPUT.PUT_LINE (v_message);
END LOOP;
END;
/関連トピック
4.7.3 サポートされているSQL*Plus文
この項では、REST対応SQLサービスでサポートされるすべてのSQL*Plus文を示します。
REST対応SQLサービスでは、書式設定に関連する文を除き、ほとんどのSQL*Plus文がサポートされます。特定のOracle Databaseスキーマには、SQL*Plus文を実行するのに適切な権限が必要です。
-
SET system_variable value -
/ (slash) -
DEF[INE] [variable] | [variable = text] -
DESC[RIBE] {[schema.]object[@connect_identifier]} -
EXEC[UTE] statement -
HELP | ? [topic] -
PRINT [variable ...] -
PRO[MPT] [text] -
REM[ARK] -
SHO[W] [option] -
TIMI[NG] [START text | SHOW | STOP] -
UNDEF[INE] variable ... -
VAR[IABLE] [variable [type][=value]]
関連トピック
4.7.3.1 システム変数の設定
system_variableおよびvalueの可能な値のリストを次に示します。
注意:
コマンドSET CMDS[EP] {; | c | ON | OFF}は廃止されています。
-
SET APPI[NFO]{ON | OFF | text} -
SET AUTOP[RINT] {ON | OFF} -
SET AUTOT[RACE] {ON | OFF | TRACE[ONLY]} [EXP[LAIN]] [STAT[ISTICS]] -
SET BLO[CKTERMINATOR] {. | c | ON | OFF} -
SET CMDS[EP] {; | c | ON | OFF} -
SET COLINVI[SIBLE] [ON | OFF] -
SET CON[CAT] {. | c | ON | OFF} -
SET COPYC[OMMIT] {0 | n} -
SET DEF[INE] {& | c | ON | OFF} -
SET DESCRIBE [DEPTH {1 | n | ALL}] [LINENUM {ON | OFF}] [INDENT {ON | OFF}] -
SET ECHO {ON | OFF} -
SET ERRORL[OGGING] {ON | OFF} [TABLE [schema.]tablename] [TRUNCATE] [IDENTIFIER identifier] -
SET ESC[APE] {\ | c | ON | OFF} -
SET FEED[BACK] {6 | n | ON | OFF | ONLY}] -
SET SERVEROUT[PUT] {ON | OFF} [SIZE {n | UNL[IMITED]}] [FOR[MAT] {WRA[PPED] | WOR[D_WRAPPED] | TRU[NCATED]}] -
SET SHOW[MODE] {ON | OFF} -
SET SQLBL[ANKLINES] {ON | OFF} -
SET SQLP[ROMPT] {SQL> | text} -
SET TI[ME] {ON | OFF} -
SET TIMI[NG] {ON | OFF} -
SET VER[IFY] {ON | OFF}
関連トピック
4.7.3.2 システム変数の表示
この項では、SHO[W] optionコマンドで使用する語句または句のいずれかであるoptionの可能な値を示します。
option変数の可能な値のリストを次に示します。
注意:
コマンドSHOW CMDSEPおよびSHOW DESCR[IBE]は廃止されています。
-
SHOW system_variable -
SHOW EDITION -
SHOW ERR[ORS] [ { ANALYTIC VIEW | ATTRIBUTE DIMENSION | HIERARCHY | FUNCTION | PROCEDURE | PACKAGE | PACKAGE BODY | TRIGGER | VIEW | TYPE | TYPE BODY | DIMENSION | JAVA CLASS } [schema.]name] -
SHOW PDBS -
SHOW SGA -
SHOW SQLCODE -
SHOW COLINVI[SIBLE] -
SHOW APPIN[FO] -
SHOW AUTOT[RACE] -
SHOW BINDS -
SHOW BLO[CK TERMINATOR] -
SHOW CMDSEP -
SHOW COPYTYPECHECK -
SHOW COPYCOMMIT -
SHOW DEFINE -
SHOW DEFINES -
SHOW DESCR[IBE] -
SHOW ECHO -
SHOW EDITION -
SHOW ERRORL[OGGING] -
SHOW ESC[APE] -
SHOW FEEDBACK -
SHOW CONCAT -
SHOW SHOW[MODE] -
SHOW RECYC[LEBIN] -
SHOW RELEASE -
SHOW SQLBL[ANKLINES] -
SHOW SCAN -
SHOW SERVEROUT[PUT] -
SHOW SPACE -
SHOW TABLES -
SHOW TIMI[NG] -
SHOW USER -
SHOW VER[IFY] -
SHOW XQUERY
関連トピック