本記事は「IDMC REST API入門」シリーズの第3回です。全4回にわたって、REST APIを使ったログインからジョブ実行・監視・ログ取得までの一連の流れを、公式ドキュメントの記述を交えて解説します。
シリーズ一覧：
第1回：REST APIの基本とログイン
第2回：ジョブ実行と停止
第3回：ジョブの監視 👈 本記事
第4回：ログ取得とまとめスクリプト
はじめに
第2回では、REST APIでのジョブ実行と停止を解説しました。ジョブを実行したら、次に必要なのは「ジョブが正常に完了したか？失敗したか？」を確認することです。
IDMCにはGUIのモニタ画面がありますが、REST APIでも同等の情報を取得できます。本記事では、REST APIによるジョブ監視の方法を解説し、GUI Monitor画面の情報がどのAPIに対応するのかを整理します。
2つの監視API：activityMonitorとactivityLog
IDMCのREST APIには、ジョブの状態を取得するためのリソースが2つあります。
| API | 対象 | 用途 |
|---|---|---|
/api/v2/activity/activityMonitor |
実行中のジョブ | 現在実行中のジョブのリアルタイム状態を取得 |
/api/v2/activity/activityLog |
完了済みのジョブ | 過去に完了（成功・失敗・停止）したジョブの履歴を取得 |
GUIのモニタ画面では「実行中のジョブ」と「すべてのジョブ」がありますが、REST APIでは「実行中のジョブ」と「完了済みのジョブ」を使い分ける必要があります。
activityMonitor：実行中ジョブの監視
基本的な使い方
/api/v2/activity/activityMonitor は、現在実行中のすべてのジョブを返します。特定のタスク名等で絞り込むパラメータは用意されていないため、特定のジョブの状態を確認するには、レスポンスの配列からクライアント側で対象のrunIdやtaskId等で検索する必要があります。
HTTPリクエストの例
GET <serverUrl>/api/v2/activity/activityMonitor
Content-Type: application/json
Accept: application/json
icSessionId: <icSessionId>
レスポンスの例
[
{
"@type": "activityMonitoryEntry",
"id": "XXXXXXXXXXXXXXXXXXXX",
"type": "WORKFLOW",
"taskId": "XXXXXXXXXXXXXXXXXXXX",
"taskName": "MyLinearTaskflow",
"objectName": "",
"runId": 11,
"startTime": "2026-03-17T03:02:35.000Z",
"startTimeUtc": "2026-03-17T07:02:35.000Z",
"executionState": "RUNNING",
"failedSourceRows": 0,
"successSourceRows": 0,
"failedTargetRows": 0,
"successTargetRows": 0,
"entries": [],
"startedBy": "user@example.com",
"runContextType": "ICS_UI",
"taskFederatedId": "XXXXXXXXXXXXXXXXXXXXXX"
},
{
"@type": "activityMonitoryEntry",
"id": "XXXXXXXXXXXXXXXXXXXX",
"type": "MTT",
"taskId": "XXXXXXXXXXXXXXXXXXXX",
"taskName": "MyMappingTask",
"objectName": "",
"runId": 15,
"startTime": "2026-03-17T03:02:37.000Z",
"startTimeUtc": "2026-03-17T07:02:37.000Z",
"executionState": "RUNNING",
"failedSourceRows": 0,
"successSourceRows": 0,
"failedTargetRows": 0,
"successTargetRows": 0,
"entries": [],
"agentId": "XXXXXXXXXXXXXXXXXXXX",
"startedBy": "user@example.com",
"runContextType": "REST_API_V2",
"taskFederatedId": "XXXXXXXXXXXXXXXXXXXXXX",
"runtimeEnvironmentId": "XXXXXXXXXXXXXXXXXXXX"
}
]
ドキュメントでは"activityMonitorEntry"オブジェクトが返ってくるとあるのですが、実際に返ってきたレスポンスの@typeフィールドを見ると"activityMonitoryEntry"`となっていて、"activityMonitor"と"Entry"の間に"y"が入っていました。
detailsパラメータ
activityMonitorにはdetailsパラメータがあります。
GET <serverUrl>/api/v2/activity/activityMonitor?details=true
公式ドキュメントには以下のように説明されています。
- true. Returns log information for tasks, linear taskflows, and child objects. Child objects can include tasks within linear taskflows, and objects within replication tasks.
- false. Returns log information for tasks and linear taskflows.
「REST API Reference」
Logs for running jobs
details=true を指定すると、リニアタスクフロー内の個別タスクやレプリケーションタスク内のオブジェクトなど、子要素の情報も含めて返されます。デフォルトはfalseです。
details=true を指定したときのレスポンスは以下のようになります。entries配下にサブタスクの情報が入っています。
[
{
"@type": "activityMonitoryEntry",
"id": "XXXXXXXXXXXXXXXXXXXX",
"type": "WORKFLOW",
"taskId": "XXXXXXXXXXXXXXXXXXXX",
"taskName": "MyLinearTaskflow",
"objectName": "",
"runId": 8,
"startTime": "2026-03-09T04:58:39.000Z",
"startTimeUtc": "2026-03-09T08:58:39.000Z",
"executionState": "RUNNING",
"failedSourceRows": 0,
"successSourceRows": 0,
"failedTargetRows": 0,
"successTargetRows": 0,
"entries": [
{
"@type": "activityMonitoryEntry",
"id": "XXXXXXXXXXXXXXXXXXXX",
"type": "MTT",
"taskId": "XXXXXXXXXXXXXXXXXXXX",
"taskName": "MyMappingTask1",
"objectName": "",
"runId": 8,
"startTime": "2026-03-09T04:58:39.000Z",
"startTimeUtc": "2026-03-09T08:58:39.000Z",
"executionState": "RUNNING",
"failedSourceRows": 0,
"successSourceRows": 0,
"failedTargetRows": 0,
"successTargetRows": 0,
"errorMsg": "No errors encountered.",
"errorCode": "0",
"entries": [],
"agentId": "XXXXXXXXXXXXXXXXXXXX",
"startedBy": "user@example.com",
"runContextType": "ICS_UI",
"taskFederatedId": "XXXXXXXXXXXXXXXXXXXXXX",
"runtimeEnvironmentId": "XXXXXXXXXXXXXXXXXXXX"
},
{
"@type": "activityMonitoryEntry",
"id": "XXXXXXXXXXXXXXXXXXXX",
"type": "MTT",
"taskId": "XXXXXXXXXXXXXXXXXXXX",
"taskName": "MyMappingTask2",
"objectName": "",
"runId": 8,
"executionState": "INITIALIZED",
"failedSourceRows": 0,
"successSourceRows": 0,
"failedTargetRows": 0,
"successTargetRows": 0,
"entries": [],
"startedBy": "user@example.com",
"runContextType": "ICS_UI",
"taskFederatedId": "XXXXXXXXXXXXXXXXXXXXXX",
"runtimeEnvironmentId": "XXXXXXXXXXXXXXXXXXXX"
}
],
"startedBy": "user@example.com",
"runContextType": "ICS_UI",
"taskFederatedId": "XXXXXXXXXXXXXXXXXXXXXX"
}
]
レスポンスの主要フィールド
レスポンスはactivityMonitoryEntryオブジェクトの配列で返されます。主要なフィールドを以下にまとめます。
| フィールド名 | 型 | 説明 |
|---|---|---|
id |
String | ログエントリID |
type |
String | タスクタイプ（MTT、DSS、WORKFLOWなど） |
taskId |
String | タスクID |
taskName |
String | タスク名 |
runId |
Long | 実行ID |
executionState |
String | 実行状態（後述） |
startTimeUtc |
Date/time | 開始時刻（UTC） |
endTimeUtc |
Date/time | 終了時刻（UTC） |
startedBy |
String | ジョブを開始したユーザー |
runContextType |
String | 起動方法 |
なお、時刻フィールドにはstartTime/endTime（米国東部時間）とstartTimeUtc/endTimeUtc（UTC）の2種類があります。日本で確認する場合は、startTimeUtc/endTimeUtcを使うと、9時間を加えるだけで JST に変換できるため、扱いやすいでしょう。
executionState（実行状態）の値
activityMonitor のレスポンスに含まれるexecutionStateは、以下の値を返します。
| executionState | 説明 |
|---|---|
QUEUED |
キューで待機中 |
INITIALIZED |
初期化中 |
RUNNING |
実行中 |
STOPPING |
停止処理中 |
FAILED |
失敗（リニアタスクフローのサブタスクのみ） |
ドキュメントにはFAILEDについて以下の記載があります。
FAILED can be returned for linear taskflow subtasks only.
「REST API Reference」
Logs for running jobs
つまり、activityMonitor でFAILEDが返されるのはリニアタスクフローのサブタスクに限られます。トップレベルのタスクが完了（成功・失敗問わず）すると、activityMonitor からは消えてactivityLogに移行します。
curlの例
curl -X GET '<serverUrl>/api/v2/activity/activityMonitor' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'icSessionId: <icSessionId>'
Pythonの例
import requests
def get_running_jobs(base_url, session_id, details=False):
url = f"{base_url}/api/v2/activity/activityMonitor"
if details:
url += "?details=true"
headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"icSessionId": session_id
}
response = requests.get(url, headers=headers)
entries = response.json()
for entry in entries:
print(f"タスク: {entry.get('taskName')}, "
f"runId: {entry.get('runId')}, "
f"状態: {entry.get('executionState')}")
return entries
activityLog：完了済みジョブの履歴
基本的な使い方
HTTPリクエストの例
GET <serverUrl>/api/v2/activity/activityLog
Content-Type: application/json
Accept: application/json
icSessionId: <icSessionId>
パラメータなしで呼び出すと、全タスクの直近のログエントリが最大200行まで返されます。
そのため、フィルタリングして目的のログを探す必要があります。
フィルタリングパラメータ
activityLog では次のフィルタリングが可能です。
① タスクIDで絞り込む
GET <serverUrl>/api/v2/activity/activityLog?taskId=<taskId>
② runIdで絞り込む（taskIdの指定も必須）
GET <serverUrl>/api/v2/activity/activityLog?runId=<runId>&taskId=<taskId>
runIdで絞り込む場合は必ずtaskIdも一緒に指定する必要があります。
③ ログエントリIDで取得する
GET <serverUrl>/api/v2/activity/activityLog/<id>
ログエントリIDはactivityLogの実行結果として返されるため、事前にはわかりません。取得するには、まずactivityLogを一度実行する必要があります。
④ スキップする行数と出力行数を設定する
GET <serverUrl>/api/v2/activity/activityLog?offset=<offset>&rowLimit=<rowLimit>
offset で最初の行から何行スキップするかを設定します。
また、rowLimit の最大値は1000です。省略時はデフォルトで最大200行が返されます。
フィルタリングに使うIDについて
activityLog ではid（ログエントリID）、runId、taskId を使って結果を絞り込めます。
これらの入手元は以下の通りです。
| ID | 入手元 | 説明 |
|---|---|---|
id |
activityLog 自体のレスポンス |
ログエントリID |
runId |
第2回で解説したジョブ実行（job リソース）のレスポンス |
ジョブ実行時に返される実行ID |
taskId |
第2回で解説したジョブ実行（job リソース）のレスポンス |
タスクのID |
つまり、第2回でジョブを実行した際に取得したrunIdとtaskIdを使えば、そのジョブの完了結果をactivityLogから直接取得できます。
レスポンスの主要なフィールド
レスポンスはactivityLogEntryオブジェクトの配列で返されます。
activityLogEntry オブジェクトは内部でさらに配列を保持するため、フィールド数が非常に多くなります。
主要なフィールドは以下ですが、activityMonitor のレスポンスとはフィールド名や構造が異なる点に注意してください。
| フィールド | 型 | 説明 |
|---|---|---|
id |
String | ログエントリID（sessionLog取得に使用） |
type |
String | タスクタイプ（MTT、DSS、WORKFLOWなど） |
objectId |
String | タスクID |
objectName |
String | タスク名 |
runId |
Long | ジョブ実行ID |
startTimeUtc |
Date/time | 開始時刻（UTC） |
endTimeUtc |
Date/time | 終了時刻（UTC） |
state |
Short | 完了状態（後述） |
activityMonitorとactivityLogのフィールド名の違い
同じ概念を表すフィールドでも、2つのAPIで名前が異なります。
| 概念 | activityMonitor | activityLog |
|---|---|---|
| タスクID | taskId |
objectId |
| タスク名 | taskName |
objectName |
| 実行状態 | executionState |
state |
スクリプトを作成する際は、このフィールド名の違いを意識する必要があります。
state（完了状態）の値
activityLogのstateは数値コードで返されます。
| state | 説明 |
|---|---|
1 |
正常完了 |
2 |
エラーありで完了 |
3 |
失敗 |
4 |
未起動 |
curlの例
# 特定タスクの履歴を取得
curl -X GET '<serverUrl>/api/v2/activity/activityLog?taskId=<taskId>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'icSessionId: <icSessionId>'
# 特定のrunIdの結果を取得
curl -X GET '<serverUrl>/api/v2/activity/activityLog?runId=<runId>&taskId=<taskId>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'icSessionId: <icSessionId>'
Pythonの例
import requests
STATE_MAP = {1: "成功", 2: "エラーあり完了", 3: "失敗", 4: "未起動"}
def get_job_result(base_url, session_id, task_id, run_id):
url = (f"{base_url}/api/v2/activity/activityLog"
f"?runId={run_id}&taskId={task_id}")
headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"icSessionId": session_id
}
response = requests.get(url, headers=headers)
entries = response.json()
if entries:
entry = entries[0]
state = entry.get("state")
print(f"タスク: {entry.get('objectName')}, "
f"状態: {STATE_MAP.get(state, '不明')}")
return entry
else:
print("該当するログエントリが見つかりません")
return None
利用時の注意点
-
activityLogのrunIdフィルタにtaskIdを付け忘れる
ドキュメントに明記されているとおり、runIdを指定する場合はtaskIdも必ず一緒に指定する必要があります。taskIdを省略するとエラーになります。 -
activityMonitorとactivityLogのフィールド名の違い
同じ「タスク名」でもactivityMonitorではtaskName、activityLogではobjectNameとフィールド名が異なります。両方のAPIを組み合わせるスクリプトでは、この違いを意識して実装してください。 -
activityLogのstateが数値であること
GUI Monitor画面では「Success」「Failed」と表示されますが、APIでは1/2/3/4の数値コードで返されます。判定ロジックを書く際は文字列比較ではなく数値比較を使ってください。
第3回のまとめ
今回は、REST APIによるジョブの監視方法を解説しました。ポイントを振り返ります。
-
ジョブの監視には
activityMonitor（実行中ジョブ）とactivityLog（完了済みジョブ）の2つのAPIを使い分ける。 -
activityMonitorではexecutionStateで実行状態を、activityLogではstateで最終結果を確認可能。2つのAPIはフィールド名が異なる部分があるため、スクリプトでは注意が必要。
次回（第4回・最終回）では、セッションログやエラーログの取得方法を解説し、ログイン→実行→監視→ログ取得までを一気通貫で実行するまとめスクリプトを作成します。
参考ドキュメント
NTT DATA公式アカウントです。 技術を愛するNTT DATAの技術者が、気軽に楽しく発信していきます。 当社のサービスなどについてのお問い合わせは、 お問い合わせフォーム nttdata.com/jp/ja/contact-us/ へお願いします。