1. Cloud Control管理者ガイド
  2. REST APIを介したSQLの実行

F REST APIを介したSQLの実行

Enterprise Managerには、REST APIを介して抽出できる、リポジトリに収集された豊富な一連のモニタリング・データがあります。独自のSQLスクリプトおよびEnterprise ManagerのRESTエンドポイントを使用すると、リポジトリ・データを抽出できます。

Enterprise Managerのリポジトリ・データは、カスタム・ダッシュボードやキー・パフォーマンス・インディケータ(KPI)レポートの作成などの様々な目的のために抽出および使用できます。Enterprise ManagerのHTTPベースのRESTエンドポイントを使用すると、SQLを使用してリポジトリ情報を簡単に抽出できます。

REST APIでは、Enterprise Managerリポジトリからデータを抽出することに加えて、一部のRESTエンドポイントを使用して、Enterprise Managerによってモニタリング/管理されるデータベース・ターゲットからデータを抽出することもできます。

Enterprise Managerを使用すると、データベース・ターゲットに対してSQLScriptジョブを実行して、データ抽出を自動化できます。このジョブ・タイプでは、ジョブの実行用にホスト資格証明とデータベース資格証明の両方が必要です。ホスト資格証明の使用が許可されていない状況の場合は、SQLの実行ジョブを実行できます。このジョブには、データベース資格証明のみが必要です。

RESTエンドポイントについては、次の表を参照してください。

  • 表F-1: リポジトリ操作用のRESTエンドポイント
  • 表F-2: ターゲット・データベース操作用のRESTエンドポイント

RESTエンドポイントのアクセシビリティ

リポジトリはEnterprise Managerフレームワークの重要なコンポーネントであるため、リポジトリ・データベースの安全が確保されるように特定の保護を実装する必要があります。

リポジトリ関連のRESTエンドポイントは、次のものによって保護されます。

  • emctlを使用して、OMSプロパティoracle.sysman.db.restfulapi.executesql.repository.query.enableにtrueを設定する必要があります。

    例:

    
emctl set property -name oracle.sysman.db.restfulapi.executesql.repository.query.enable -value true -sysman_pwd “sysman”

  • 認可ヘッダー: Enterprise Managerのユーザー資格証明をヘッダーの一部として渡す必要があります。

特定のリポジトリ関連のREST操作の場合:

前述のエンドポイント保護設定に加えて、次の設定も必要となります。

  • リポジトリ・データベースで/repository/update RESTメソッドを呼び出すには、emctlを使用して、oracle.sysman.db.restfulapi.executesql.repository.update.enable OMSプロパティにtrueを設定します。

    例:

    
emctl set property -name oracle.sysman.db.restfulapi.executesql.repository.update.enable -value true -sysman_pwd “sysman”

  • リポジトリ・データベースで/repository/plsqlメソッドを呼び出すには、emctlを使用して、oracle.sysman.db.restfulapi.executesql.repository.plsql.enable OMSプロパティにtrueを設定します。 

    
emctl set property -name oracle.sysman.db.restfulapi.executesql.repository.plsql.enable -value true -sysman_pwd “sysman”
  • SELECT問合せのREST操作(つまり、/repository/query REST)を実行するEnterprise Managerユーザーには、(EM_USERロールに加えて)デフォルトで設定されるEnterprise Managerロールが付与されている必要があります。付与されていない場合は、ファイングレイン監査(FGA)によって、SQL問合せの結果が行なしに制限されます。

データベース・ターゲット関連のRESTエンドポイントは、次のものによって保護されます。

前述のロールに加えて、Enterprise Managerユーザーには次のターゲット権限も必要となります。

  • ターゲットの接続
  • データベースでの任意のSQLの実行

データベース・ターゲットでREST操作を有効にするには、emctlを使用して、oracle.sysman.db.restfulapi.executesql.target.query.enable OMSプロパティにtrueを設定する必要があります。 


emctl set property -name oracle.sysman.db.restfulapi.executesql.target.query.enable -value true -sysman_pwd “sysman”

特定のデータベース・ターゲット関連のREST操作の場合:

前述の設定に加えて、次のOMSプロパティにtrueを設定する必要があります。

  • ターゲット・データベースで/target/update RESTメソッドを呼び出すには、emctlを使用して、oracle.sysman.db.restfulapi.executesql.target.update.enable OMSプロパティにtrueを設定する必要があります。

    例:

    emctl set property -name oracle.sysman.db.restfulapi.executesql.target.update.enable -value true -sysman_pwd “sysman”
  • ターゲット・データベースで/target/plsql RESTメソッドを呼び出すには、emctlを使用して、oracle.sysman.db.restfulapi.executesql.target.plsql.enable OMSプロパティにtrueを設定する必要があります。

    例:

    emctl set property -name oracle.sysman.db.restfulapi.executesql.target.plsql.enable -value true -sysman_pwd “sysman”

問合せ結果の制限

リポジトリ/ターゲット・データベースがオーバーロードしないようにするために、REST SQL問合せによって返される行数および列数を制限するフラッド制御メカニズムが、次のOMSプロパティを使用して実装されています。

  • oracle.sysman.db.httpsql.numrows: 値が指定されていない場合、デフォルトで1000行が結果セットに返されます。

  • oracle.sysman.db.httpsql.numcols: 値が指定されていない場合、デフォルトで20列のみが結果セットに返されます。

RESTエンドポイント

次の表に、使用可能なEnterprise Managerリポジトリおよびターゲット・データベースのRESTエンドポイントを示します。

表F-1 リポジトリ操作用のRESTエンドポイント

RESTエンドポイント サンプル・ペイロード HTTPメソッド コメント 出力例
https://<EM_HOST>:<PORT>/em/websvcs/restful/emws/oracle.sysman.db/executesql/repository/query/v1
 { "sqlStatement": "SELECT * FROM sysman.MGMT$TARGET_METRIC_SETTINGS", "maxRowLimit": 2, "maxColumnLimit": 4 } POST

指定されたSELECT問合せをリポジトリDBで実行します。

maxRowLimitとmaxColumnLimitはオプションです。

 {"Result" : [{"target_name":"Management_Servers","target_type":"oracle_emsvrs_sys","target_guid":" [B@2f99ae59","metric_name":"Response"}, {"target_name":"\/EMGC_EMGC_DOMAIN\/EMGC_DOMAIN\/EMGC_ADMINSERVER\/mds-owsm","target_type":"metadata_repository","target_guid":" [B@12856d79","metric_name":"MDS_REPOSITORY_ROLLUP"}]}
https://<EM_HOST>:<PORT>/em/websvcs/restful/emws/oracle.sysman.db/executesql/repository/plsql/v1 例1: 返すデータがないPL/SQLブロックの実行。

{ "sqlStatement": " begin execute immediate 'create table test_sql_t1(col1 number(10))'; end; " }

 POST

指定されたPL/SQLブロックをリポジトリDBで実行します。

 { "Result":"PLSQL block executed successfully" }
. 例2: 複数の出力があるPL/SQLブロックの実行。

{ "sqlStatement": " DECLARE v_target_guid RAW(16); v_status NUMBER; v_sub_status NUMBER; BEGIN SELECT target_guid INTO v_target_guid FROM sysman.EM_TARGETS WHERE target_type = 'oracle_database' AND target_name = 'Oemrep_Database'; SYSMAN.MGMT_AVAIL.get_avail_state(v_target_guid,?,?); SYSMAN.EMD_MAINT_UTIL.get_em_db_sessions_cursor(?); END; ", "sqlParameters":[ {"type":"INTEGER","isOutparameter":true}, {"type":"INTEGER","isOutparameter":true}, {"type":"CURSOR","isOutparameter":true} ], "maxRowLimit": 2, "maxColumnLimit": 2 }

 POST

DBのユーザーIDとパスワードを使用して、指定されたPL/SQLブロックをターゲットDBで実行します。

 {"Result":[{"OutParameter3":[{"INST_ID":1,"SID":10},{"INST_ID":1,"SID":11}]},{"OutParameter1":1},{"OutParameter2":99}]}
. 例#3: 入力パラメータと出力パラメータの両方を持つPL/SQLブロックの実行。

{ "sqlStatement": " DECLARE BEGIN SYSMAN.EM_TARGET.GET_AGENT_VERSION_FOR_TARGET(?,?,?); END; ", "sqlParameters":[ {"type":"STRING","value":"Oemrep_Database"}, {"type":"STRING","value":"oracle_database"}, {"type":"STRING","isOutparameter":true} ] }

 POST

指定されたPLSQLブロックをターゲットで実行して、結果を返します(ある場合)。

{"Result":[{"OutParameter3":"13.4.0.0.0"}]}
https://<EM_HOST>:<PORT>/em/websvcs/restful/emws/oracle.sysman.db/executesql/repository/update/v1 { "sqlStatement": "CREATE TABLE test_SQL_T3 AS (SELECT * FROM sysman.ADP_EVENT_J2EE where 1<>1)" } POST

指定されたDML問合せをリポジトリDBで実行します。

 { "Result":0 }

表F-2 ターゲット・データベース操作用のRESTエンドポイント

RESTエンドポイント サンプル・ペイロード HTTPメソッド コメント 出力例
https://<EM_HOST>:<PORT>/em/websvcs/restful/emws/oracle.sysman.db/executesql/target/query/v1 {"targetName":"Oemrep_Database", "targetType": "oracle_database", "sqlStatement": "SELECT * FROM sysman.MGMT$TARGET_METRIC_SETTINGS", "credential": {"DBCredsMonitoring":"testcred"}, "maxRowLimit": 3, "maxColumnLimit": 2} POST

ペイロードのDBCredsMonitoringプロパティで参照される名前付きDB資格証明を使用して、指定されたSELECT問合せをターゲットDBで実行します。

maxRowLimitとmaxColumnLimitはオプションです。maxRowLimit/maxColumnLimit値が-1の場合は、すべての行または列が結果セットに返されます。

{"Result" : [{"target_name":"Management_Servers", "target_type":"oracle_emsvrs_sys"}, {"target_name":"\/EMGC_EMGC_DOMAIN\/EMGC_DOMAIN\/EMGC_ADMINSERVER\/mds-owsm", "target_type":"metadata_repository"}, {"target_name":"\/EMGC_EMGC_DOMAIN\/EMGC_DOMAIN\/EMGC_ADMINSERVER\/mds-owsm", "target_type":"metadata_repository"}]}
https://<EM_HOST>:<PORT>/em/websvcs/restful/emws/oracle.sysman.db/executesql/target/query/v1 {"targetName":"Oemrep_Database", "targetType": "oracle_database", "sqlStatement": "SELECT * FROM sysman.MGMT$TARGET_METRIC_SETTINGS where target_name=? and warning_operator=?", "sqlParameters":[ {"type":"STRING","value":"Management_Servers"}, {"type":"INTEGER","value":"1"} ], "credential": { "DBCredsMonitoring":"testcred" }, "maxRowLimit": 2, "maxColumnLimit": 2 }

sqlParametersは、sqlStatementに疑問符(?)が含まれている場合にのみ必要となります。

タイプには、次のいずれかを指定できます

  • STRING
  • INTEGER
  • DATE
  • BYTE
  • BOOLEAN
  • CURSOR (PL/SQLタイプの文の場合のみ)
 POST

指定された名前付きDB資格証明(ペイロードのDBCredsMonitoringプロパティを参照)を使用して、指定されたSELECT問合せをターゲットDBで実行します。

maxRowLimitとmaxColumnLimitはオプションです。

 {"Result" : [{"target_name":"Management_Servers","target_type":"oracle_emsvrs_sys"}]}
https://<EM_HOST>:<PORT>/em/websvcs/restful/emws/oracle.sysman.db/executesql/target/plsql/v1 例1: 返すデータがないPL/SQLブロックの実行。

{"targetName":"Oemrep_Database", "targetType": "oracle_database", "sqlStatement": " begin execute immediate 'create table test_sql_t1(col1 number(10))'; end; ", "credential": { "DBCredsMonitoring":"testcred" } }

 POST 指定された名前付きDB資格証明(ペイロードのDBCredsMonitoringプロパティを参照)を使用して、指定されたPL/SQLブロックをターゲットDBで実行します。 {""Result"": "PLSQL Block executed successfully"}
. 例2: 複数の出力があるPL/SQLブロックの実行。

{"targetName":"Oemrep_Database", "targetType": "oracle_database", "sqlStatement": " DECLARE v_target_guid RAW(16); v_status NUMBER; v_sub_status NUMBER; BEGIN SELECT target_guid INTO v_target_guid FROM sysman.EM_TARGETS WHERE target_type = 'oracle_database' AND target_name = 'Oemrep_Database'; SYSMAN.MGMT_AVAIL.get_avail_state(v_target_guid,?,?); SYSMAN.EMD_MAINT_UTIL.get_em_db_sessions_cursor(?); END; ", "sqlParameters":[ {"type":"INTEGER","isOutparameter":true}, {"type":"INTEGER","isOutparameter":true}, {"type":"CURSOR","isOutparameter":true} ], "credential": {"DBCredsMonitoring":"testcred"}, "maxRowLimit": 2, "maxColumnLimit": 2 }

 POST 指定された名前付きDB資格証明(ペイロードのDBCredsMonitoringプロパティを参照)を使用して、指定されたPL/SQLブロックをターゲットDBで実行します。

ペイロードのDBCredsMonitoringプロパティで参照される名前付きDB資格証明を使用して、指定されたSELECT問合せをターゲットDBで実行します。

{"Result":[{"OutParameter3":[{"INST_ID":1,"SID":10},{"INST_ID":1,"SID":11}]}, {"OutParameter1":1},{"OutParameter2":99}]}
. 例#3: 入力パラメータと出力パラメータの両方を持つPL/SQLブロックの実行。

{"targetName":"Oemrep_Database", "targetType": "oracle_database", "sqlStatement": " DECLARE BEGIN SYSMAN.EM_TARGET.GET_AGENT_VERSION_FOR_TARGET(?,?,?); END; ", "credential": {"DBCredsMonitoring":"testcred"}, "sqlParameters":[ {"type":"STRING","value":"Oemrep_Database"}, {"type":"STRING","value":"oracle_database"}, {"type":"STRING","isOutparameter":true} ] }

 POST 指定された名前付きDB資格証明(ペイロードのDBCredsMonitoringプロパティを参照)を使用して、指定されたPL/SQLブロックをターゲットDBで実行して、結果を返します(ある場合)。 {"Result":[{"OutParameter3":"13.4.0.0.0"}]}
https://<EM_HOST>:<PORT>/em/websvcs/restful/emws/oracle.sysman.db/executesql/target/update/v1 {"targetName":"Oemrep_Database", "targetType": "oracle_database", "sqlStatement": "DELETE FROM mytable where empId<2000 and empId > 1998", "credential": { "DBCredsMonitoring":"testcred" } } POST

指定された名前付きDB資格証明(ペイロードのDBCredsMonitoringプロパティを参照)を使用して、指定されたDML問合せをターゲットDBで実行します。

ほとんどのDML文では、結果の行数はそのDMLの影響を受けます。

 { "Result": 2 }

ノート:

ターゲット・データベースのエンドポイントに対するペイロードで受け入れられるのは、名前付き資格証明のみです。RESTエンドポイント操作を実行するEnterprise Manager管理者が、ペイロードに指定されたデータベース・ターゲットで有効な名前付き資格証明をすでに作成していることを確認します。