16 RESTサービス

RESTサービスの構成とRESTサービスAPIの使用方法を学習します。

16.1 ORDSを使用したRESTサービスの構成

Oracle Trace File Analyzerには、HTTPSを介した呼出しおよび問合せを可能にするRESTサポートが含まれています。

構文

このRESTサポートを容易にするために、Oracle REST Data Services (ORDS)がインストールに含まれています。

tfactl rest [-status|-start|-stop|-upgrade|-uninstall] [-dir] [-port] [-user] [-debug [-level]]

ノート:

RESTコマンドはrootユーザーとしてのみ実行できます。

パラメータ

表16-1 RESTコマンドのパラメータ

パラメータ 説明

-status

現在のステータスを出力します。

-start

Oracle Trace File AnalyzerのRESTサービスを起動します(まだ実行されていない場合)。

-stop

Oracle Trace File AnalyzerのRESTサービスが実行中の場合は停止します。

-upgrade

構成されているORDS APIをアップグレードする必要があるかどうかをチェックします。

ORDS APIのアップグレードが必要な場合は、ORDSを停止し、APIをアップグレードしてからORDSを再起動します。

-uninstall

Oracle Trace File AnalyzerのREST構成を削除します。

–dir

Oracle Trace File AnalyzerのREST構成の詳細を格納するために使用するディレクトリ。

ユーザーのホーム・ディレクトリにデフォルト設定されます。

–port

ORDSを実行するポート。

デフォルトは9090です。

-user

ORDSを開始するユーザー。

デフォルトはGRID所有者です。

–debug

デバッグを有効にします。

–level

使用するデバッグのレベル。使用可能なレベルは次のとおりです。
  • 1 – 致命的

  • 2 – エラー

  • 3 - 警告

  • 4 – 情報(デフォルト)

  • 5 – デバッグ

  • 6 – トレース

ORDSの実行後、次のAPIを使用し、次の形式のリクエストを使用してRESTを呼び出すことができます。
https://host:port/ords/api
次に例を示します。
https://host:port/ords/tfactl/print/status

RESTの認証

Oracle Trace File AnalyzerのRESTは、ファースト・パーティCookieベースの認証(基本認証)を使用します。

Oracle Trace File AnalyzerのRESTアプリケーションは、Webアプリケーションが使用しているものと同じCookieセッションを使用し、RESTful APIに自身を認証し、権限を付与することが可能です。ファースト・パーティのアプリケーションにはRESTful APIへの完全なアクセス権があります。

Oracle Trace File Analyzerは、起動時にtfaadminユーザーおよびtfarestユーザーのパスワードの入力を求めます。

  • RESTコールにはtfarestユーザーを使用します

  • RESTコールの作成、およびRESTサービスの管理(たとえば、ロギング・レベルの変更)には、tfaadminを使用します

# ./tfactl rest -start

Configuring TFA REST Services using ORDS : 

This might take couple of minutes. Please be patient.

Adding Dependency Jars to ORDS

Adding users to ORDS :

Enter a password for user tfaadmin: 
Confirm password for user tfaadmin: 

Enter a password for user tfarest: 
Confirm password for user tfarest: 

Starting TFA REST Services

Successfully started TFA REST Services [PID : 32650]

URL : https://myserver:9090/ords/tfactl/print/status
次のURLを使用してブラウザからWebサービスにアクセスします。
https://host_name:9090/ords/tfactl/print/status

サインイン・リンクを含む401メッセージが表示されます。リンクをクリックし、作成したtfarest資格証明を使用してサインインすると、REST出力に遷移します。

または、curlコマンドで資格証明を指定することもできます。

# curl -k --user tfarest:mypassword https://myserver:9090/ords/tfactl/print/status
[ {
  "status" : "CheckOK",
  "hostname" : "myserver",
  "pid" : 2430,
  "port" : 5000,
  "version" : "18.2.0.0.0",
  "buildId" : "18200020180501035221",
  "inventoryStatus" : "COMPLETE"
} ]

16.2 Apache Tomcatを使用したRESTサービスの構成

Oracle Trace File Analyzerのインストールには、Apache Tomcatを介してRESTサービスを有効にするWebアプリケーション・リソース(WAR)ファイルが含まれています。

Apache Tomcatを使用してRESTサービスを有効化するには:
  1. TFA_HOME/jlib/tfa.warにあるWARファイルをTomcatサーバーにデプロイします。
  2. tfaadminユーザーのパスワードを変更します。
    curl -k --user tfaadmin:tfaadmin -X POST "https://host/tfa/tfactl/user/update" '{ "password" : "some_new_password" }'
  3. tfarestユーザーのパスワードを変更します。
    curl -k --user tfarest:tfarest -X POST "https://host/tfa/tfactl/user/update" '{ "password" : "some_new_password" }'
  4. TomcatユーザーをOracle Trace File Analyzerのアクセス・リストに追加します。
    tfactl access add -user tomcat_user

16.3 RESTサービスのprint API

RESTサービスのprint APIの使用方法について説明します

16.3.1 print

GETリクエストを使用して、すべてのホストのステータスを出力します。

構文

/tfactl/print/status

例16-1 print

[ {
  "status" : "CheckOK",
  "hostname" : "myhost",
  "pid" : 73637,
  "port" : 9090,
  "version" : "18.1.0.0.0",
  "buildId" : "18100020180109014331",
  "inventoryStatus" : "COMPLETE"
} ]

16.3.2 hosts

GETリクエストを使用して、ホストのリストを出力します。

構文

/tfactl/print/hosts

例16-2 hosts

[ {
  "hostname" : "myhost"
} ]

16.3.3 actions

GETリクエストを使用して、すべてのホストで実行されたアクションのリストを出力します。

構文

/tfactl/print/actions

例16-3 actions

[ {
  "actionName" : "Run inventory",
  "hostname" : "Requested in all nodes",
  "client" : "tfactl",
  "startTime" : "Jan 09 07:50:26 PST",
  "endTime" : "Jan 09 07:50:29 PST",
  "status" : "COMPLETE",
  "comments" : null
} ]

16.3.4 repository

GETリクエストを使用して、すべてのホストのリポジトリの詳細を出力します。

構文

/tfactl/print/repository

例16-4 repository

[ {
  "hostname" : "myhost",
  "directory" : "/scratch/smith/view_storage/smith_tfa_latest/oracle/log/tfa/repository",
  "status" : "OPEN",
  "maxSizeMB" : 10240,
  "currentSizeMB" : 13,
  "freeSpaceMB" : 10227
} ]

16.3.5 collections

GETリクエストを使用して、すべての収集の詳細または特定の収集の詳細を出力します。

構文

/tfactl/print/collections
/tfactl/print/collections/{collectionid}

例16-5 collections

[ {
  "id" : "20171010115528myhost",
  "type" : "Manual Collection",
  "requestUser" : "smith",
  "nodeList" : "[]",
  "masterHost" : "myhost",
  "startTime" : "Mon Oct 09 23:55:32 PDT 2017",
  "endTime" : "Tue Oct 10 11:55:32 PDT 2017",
  "tag" : "/scratch/smith/view_storage/smith_tfa_latest/oracle/log/tfa/repository/tfa_11",
  "zipFileName" : "myhost.tfa_Tue_Oct_10_11_55_28_PDT_2017.zip",
  "componentList" : "[emagent, crsclient, oms, dbwlm,emplugins, cfgtools, afd, wls]",
  "zipFileSize" : 3055,
  "collectionTime" : 16,
  "events" : null
}]
[{
  "id" : "20171011044112myhost",
  "type" : "Manual Collection",
  "requestUser" : "smith",
  "nodeList" : "[]",
  "masterHost" : "myhost",
  "startTime" : "null",
  "endTime" : "Wed Oct 11 04:41:14 PDT 2017",
  "tag" : "/scratch/smith/view_storage/smith_tfa_latest/oracle/log/tfa/repository/TFA_T1",
  "zipFileName" : "myhost.TFA_T1.zip",
  "componentList" : "[]",
  "zipFileSize" : 0,
  "collectionTime" : 0,
  "events" : null
}]

16.3.6 config

GETリクエストを使用して、すべてのホストの構成詳細を出力します。

構文

/tfactl/print/config

例16-6 config

[ {
  "hostname" : "myhost",
  "tfaVersion" : "18.1.0.0.0",
  "javaVersion" : "1.8",
  "inventoryTraceLevel" : 1,
  "collectionTraceLevel" : 1,
  "scanTraceLevel" : 1,
  "otherTraceLevel" : 3,
  "currentSizeMB" : 13,
  "maxSizeMB" : 10240,
  "maxLogSize" : 50,
  "maxLogCount" : 10,
  "maxCoreFileSize" : 50,
  "maxCoreCollectionSize" : 500,
  "minSpaceForRTScan" : 500,
  "diskUsageMoninterInterval" : 60,
  "manageLogsAutoPurgeInterval" : 60,
  "manageLogsAutoPurgePolicyAge" : "30d",
  "minFileAgeToPurge" : 12,
  "language" : "en",
  "encoding" : "UTF-8",
  "country" : "US",
  "alertLogLevel" : "ALL",
  "userLogLevel" : "ALL",
  "baseLogPath" : "ERROR",
  "tfaIpsPoolSize" : 5,
  "autoPurge" : true,
  "publicIp" : false,
  "fireZipsInRT" : true,
  "rtscan" : true,
  "diskUsageMonOn" : true,
  "manageLogsAutoPurgeOn" : false,
  "trimmingOn" : true
} ]

16.3.7 protocols

GETリクエストを使用して、すべてのホストのプロトコルの詳細を出力します。

構文

/tfactl/print/protocols

例16-7 protocols

{
  "hostname" : "myhost",
  "available" : [ "TLSv1.2" ],
  "restricted" : [ "SSLv3", "SSLv2Hello", "TLSv1", "TLSv1.1" ]}

16.3.8 directories

GETリクエストを使用して、すべてのホストのディレクトリの詳細を出力します。

構文

/tfactl/print/directories

例16-8 directories

[ {
  "hostname" : "myhost",
  "directory" : "/oem/app/oracle/product/emagent/agent_inst/install/logs",
  "components" : [ "EMPLUGINS" ],
  "permission" : "public",
  "owner" : "root",
  "collectionPolicy" : "exclusions",
  "collectAll" : false
}, {
  "hostname" : "myhost",
  "directory" : "/oem/app/oracle/product/emagent/agent_inst/sysman/log",
  "components" : [ "EMAGENT" ],
  "permission" : "public",
  "owner" : "root",
  "collectionPolicy" : "exclusions",
  "collectAll" : false
} ]

16.4 RESTサービスのdiagcollect API

RESTサービスのdiagcollect APIの使用方法を学習します。

16.4.1 diagcollect

POSTリクエストを使用して、収集の詳細を表示します。

構文

/tfactl/diagcollect

戻り値

すべてのコンポーネントの過去12時間のOracle Trace File Analyzerのデフォルト収集。

または、パラメータとして指定されたJSONデータによるOracle Trace File Analyzerの収集。

例16-9 diagcollect - デフォルト収集

{
  "collectionId" : "20180111011121slc12ekf",
  "zipName" : "TFA_DEF_ZIP_20180111011121",
  "tagName" : "TFA_DEF_TAG_20180111011121"
}

例16-10 diagcollect - パラメータとしてのJSONデータ

入力:

[{ 
  "components": "-database -asm -tns -crs -acfs -install -cfgtools -os", 
  "timePeriod": "-since n[d|h] | -last n[d|h] | -for date |
        -from date -to date",
  "tagName": "crs_crash_collection",
  "nodeList": "node1,node2",
  "options": "-nocopy | -notrim | -silent | -nocores | 
       -collectalldirs | -collectdir dir1,dir2..."
}]

出力:

[{
  "collectionId" : "20180111011121slc12ekf",
  "zipName" : "TFA_DEF_ZIP_20180111011121",
  "tagName" : "TFA_DEF_TAG_20180111011121"
}]

16.5 RESTサービスのdownload API

RESTサービスのdownload APIの使用方法を学習します。

16.5.1 download

GETリクエストを使用して、特定の収集IDの収集ZIPファイルをダウンロードします。

構文

/tfactl/download/{collectionid}

戻り値

指定された収集IDの収集ZIPファイル。

使用上のノート

収集ZIPファイルをダウンロードする収集IDを指定します。

16.6 RESTサービスのrun API

RESTサービスのrun APIの使用方法を学習します。

16.6.1 alertsummary

GETリクエストを使用して、alertsummaryコマンドを実行します。

構文

/tfactl/run/alertsummary

戻り値

alertsummaryコマンドを実行し、アラート・サマリーを返します。

例16-11 alertsummary

[ {
  "line" : "Output from host : myserver"
}, {
  "line" : "------------------------------"
}, {
  "line" : "Reading /scratch/app/oradb/diag/rdbms/apxcmupg/apxcmupg_2/trace/alert_apxcmupg_2.log"
}, {
  "line" : "+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-"
}, {
  "line" : "------------------------------------------------------------------------"
}, {
  "line" : "Oct 20 08:20:43 Database started"
}, {
  "line" : "------------------------------------------------------------------------"
}, {
  "line" : "Nov 05 20:27:50 Database started"
},
....
....

16.6.2 calog

GETリクエストを使用して、calogコマンドを実行します。

構文

/tfactl/run/calog

16.6.3 changes

GETリクエストを使用して、changesコマンドを実行します。

構文

/tfactl/run/changes

例16-12 changes

[ {
  "line" : "Output from host : myserver"
}, {
  "line" : "------------------------------"
}, {
  "line" : "[Jul/25/2018 03:45:15.325]: Parameter: fs.aio-nr: Value: 276224 => 277760"
}, {
  "line" : "[Jul/25/2018 03:45:15.325]: Parameter: kernel.random.entropy_avail: Value: 192 => 152"
}, {
  "line" : "[Jul/25/2018 03:45:15.325]: Parameter: kernel.random.uuid: 
Value: 5eac06d7-560a-466d-a035-efe836fe0b57 => 3f329d9c-25d3-4057-ab00-17d031645490"
}, {
  "line" : "[Jul/25/2018 15:46:15.325]: Parameter: fs.aio-nr: Value: 277760 => 279296"
},
....
....

16.6.4 events

GETリクエストを使用して、eventsコマンドを実行します。

構文

/tfactl/run/events

例16-13 events

[ {
  "line" : "Output from host : myserver"
}, {
  "line" : "------------------------------"
}, {
  "line" : "Event Summary:"
}, {
  "line" : "INFO    :0"
}, {
  "line" : "ERROR   :0"
}, {
  "line" : "WARNING :0"
}, {
  "line" : "Event Timeline:"
}, {
  "line" : "No Events Found"
} ]

16.6.5 history

GETリクエストを使用して、historyコマンドを実行します。

構文

/tfactl/run/history

16.7 RESTサービスのuser API

RESTサービスのuser APIの使用方法を学習します。

16.7.1 add

POSTリクエストを使用して、Oracle Trace File Analyzer RESTサービスにユーザーを追加します。

構文

/tfactl/user/add

例16-14 add

入力:

{
  "userName" : "test",
  "password" : "test"
}

出力:

{
  "status": "SUCCESS",
  "message": "Successfully added test to TFA REST Services"
}

16.7.2 delete

POSTリクエストを使用して、Oracle Trace File Analyzer RESTサービスのユーザーを削除します。

構文

/tfactl/user/delete

例16-15 delete

入力:

{
  "userName" : "test"
}

出力:

{
  "status": "SUCCESS",
  "message": "Successfully removed test from TFA REST Services"
}

16.7.3 update

POSTリクエストを使用して、Oracle Trace File Analyzer RESTサービスのユーザーのパスワードを更新します。

構文

/tfactl/user/update

例16-16 update

入力:

{
  "password" : "test"
}

出力:

{
  "status": "SUCCESS",
  "message": "Successfully updated users's profile in TFA"
}