7.1.1 ユニット一覧の取得API
指定したユニットまたはユニット配下の,ジョブグループ,ジョブネット,およびジョブの情報を取得します。情報を取得するユニットは,条件を記述することで指定します。条件を複数記述した場合,すべての条件を満たすユニットの一覧が取得されます。
条件を満たすユニットが一つも存在しない場合,0件のユニット一覧を返却します。ログインしたJP1ユーザーに参照権限がないユニットの情報は取得結果に含まれません。取得できるユニットは最大1,000件です。取得件数が1,000件を超える場合は,条件を変更し,取得件数を絞り込んでください。
- 実行権限
-
ログインしたJP1ユーザーが,情報を取得するユニットに対して,次に示すどれかのJP1権限が与えられている必要があります。
-
JP1_AJS_Admin権限
-
JP1_AJS_Manager権限
-
JP1_AJS_Editor権限
-
JP1_AJS_Operator権限
-
JP1_AJS_Guest権限
-
- リクエストの形式
-
- リクエスト行
GET /application/component/apiVersion/objects/statuses?query httpVersion
- APIのバージョン
-
v1
- リソースを一意に識別する情報
-
なし
- パラメーター
-
「query」に指定するパラメーターを次の表に示します。
表7‒1 ユニット一覧の取得APIのパラメーター一覧 パラメーター
値の説明
必須・任意
mode
固定で「search」を指定します。
必須
manager
マネージャーホスト名またはIPアドレスを,1〜255バイトの文字列で指定します。
必須
serviceName
スケジューラーサービス名を,1〜30バイトの文字列で指定します。
必須
location
取得したいユニットの上位ユニット(ジョブグループまたはジョブネット)のユニット完全名を,1〜930バイトの文字列で指定します。
必須
searchLowerUnits
パラメーターlocationで指定したユニットの,直下1階層のユニット情報を取得対象とするか,配下のユニットすべての情報を取得対象とするかを,定数LowerTypeに規定されている文字列定数で指定します。定数LowerTypeの詳細については,「7.4.2(1) LowerType」を参照してください。
このパラメーターを指定しなかった場合,「NO(直下1階層のユニット)」が仮定されます。
任意
searchTarget
ユニットの定義だけを取得対象とするか,ユニットの定義および状態を取得対象とするかを,定数SearchTargetTypeに規定されている文字列定数で指定します。定数SearchTargetTypeの詳細については,「7.4.2(2) SearchTargetType」を参照してください。
「DEFINITION(定義)」を指定した場合は,次のパラメーターの指定は無視されます。
-
execID
-
generation
-
periodBegin
-
periodEnd
-
status
-
delayStatus
-
holdPlan
-
execHost
-
execHostMatchMethods
このパラメーターを指定しなかった場合,「DEFINITION_AND_STATUS(定義と状態)」が仮定されます。
任意
unitName
取得したいユニットの名称を指定します。
パラメーターunitNameMatchMethodsでユニット名の比較方法を指定した場合だけ,このパラメーターを指定できます。また,ユニット名の比較方法に「NO(検索条件にしない)」を指定した場合は,このパラメーターの指定は無視されます。
指定できるユニット名のバイト数は,パラメーターunitNameMatchMethodsの指定値によって異なります。
パラメーターunitNameMatchMethodsの指定値と,このパラメーターに指定できるバイト数を次に示します。
EQ,BW,EW,NE,CO,NC:1〜30バイト
RE:1〜64バイト
任意
unitNameMatchMethods
ユニット名の比較方法を定数MatchMethodsに規定されている文字列定数で指定します。定数MatchMethodsの詳細については,「7.4.2(3) MatchMethods」を参照してください。「NO(検索条件にしない)」を指定した場合は,すべてのユニット名が取得対象となります。
このパラメーターを指定しなかった場合,「NO」が仮定されます。
任意
execID
取得したいユニットの実行IDを「@[mmmm]{A〜Z}nnnn」の形式で指定します(例:@10A200)。
パラメーターgenerationで「EXECID(指定した実行IDの世代を取得)」を指定した場合だけ,このパラメーターを指定できます。その他の値を指定した場合,このパラメーターの指定は無視されます。
任意
unitType
取得したいユニットの種別を定数UnitTypeに規定されている文字列定数で指定します。定数UnitTypeの詳細については,「7.4.2(4) UnitType」を参照してください。
「NO(検索条件にしない)」を指定した場合,すべてのユニットの種別が取得対象となります。
「GROUP(ジョブグループなど)」を指定した場合,次のパラメーターの指定は無視されます。
-
execID
-
generation
-
periodBegin
-
periodEnd
-
status
-
delayStatus
-
holdPlan
-
execHost
-
execHostMatchMethods
-
releaseID
-
releaseInfoSearchMethods
「ROOT(ルートジョブネットなど)」および「NET(ジョブネットなど)」を指定した場合,次のパラメーターの指定は無視されます。
-
execHost
-
execHostMatchMethods
このパラメーターを指定しなかった場合,「NO」が仮定されます。
任意
generation
取得したいユニットの世代を定数GenerationTypeに規定されている文字列定数で指定します。定数GenerationTypeの詳細については,「7.4.2(5) GenerationType」を参照してください。
このパラメーターを指定しなかった場合,「STATUS(最新状態)」が仮定されます。
任意
periodBegin
取得したいユニットの世代の開始日時を,「YYYY-MM-DDThh:mm」の形式で指定します。指定した日時以降に存在する世代が取得対象となります。
指定できる値を次に示します。
-
YYYY:年を指定します。
年に指定できる値は,次のとおりです。
JP1/AJS3 - Web Consoleのバージョンが13-00以降,かつ接続先JP1/AJS3 - Managerのバージョンが13-00以降の場合:
1994〜環境設定パラメーターSCHEDULELIMITに設定した値(単位:年)※
上記以外の場合:
1994〜2036(単位:年)
-
MM:月を指定します。
月に指定できる値は,01〜12(単位:月)です。
-
DD:日にちを指定します。
日にちに指定できる値は,01〜指定した月の最終日(単位:日)です。
-
hh:時間を指定します。
時間に指定できる値は,00〜23(単位:時)です。
-
mm:分を指定します。
分に指定できる値は,00〜59(単位:分)です。
指定する日時は,要求先JP1/AJS3 - Managerのスケジューラーサービスローカル日時で指定してください。
パラメーターgenerationで「PERIOD(期間指定)」を指定した場合だけ,このパラメーターを指定できます。その他の値を指定した場合,このパラメーターの指定は無視されます。期間の終了日時はパラメーターperiodEndで指定します。
パラメーターperiodEndで指定した終了日時以前の日時を指定してください。
任意
periodEnd
取得したいユニットの世代の終了日時を,「YYYY-MM-DDThh:mm」の形式で指定します。指定した日時以前に存在する世代が取得対象になります。
指定できる値を次に示します。
-
YYYY:年を指定します。
年に指定できる値は,次のとおりです。
JP1/AJS3 - Web Consoleのバージョンが13-00以降,かつ接続先JP1/AJS3 - Managerのバージョンが13-00以降の場合:
1994〜環境設定パラメーターSCHEDULELIMITに設定した値(単位:年)※
上記以外の場合:
1994〜2036(単位:年)
-
MM:月を指定します。
月に指定できる値は,01〜12(単位:月)です。
-
DD:日にちを指定します。
日にちに指定できる値は,01〜指定した月の最終日(単位:日)です。
-
hh:時間を指定します。
時間に指定できる値は,00〜23(単位:時)です。
-
mm:分を指定します。
分に指定できる値は,00〜59(単位:分)です。
指定する日時は,要求先JP1/AJS3 - Managerのスケジューラーサービスローカル日時で指定してください。
パラメーターgenerationで「PERIOD(期間指定)」を指定した場合だけ,このパラメーターを指定します。その他の値を指定した場合,このパラメーターの指定は無視されます。
期間の開始日時はパラメーターperiodBeginで指定します。
パラメーターperiodBeginで指定した開始日時以降の日時を指定してください。
任意
status
取得したいユニットの状態を定数UnitStatusに規定されている文字列定数で指定します。定数UnitStatusの詳細については,「7.4.2(6) UnitStatus」を参照してください。
「NO(検索条件にしない)」を指定した場合,すべてのユニットの状態が取得対象となります。
「UNREGISTERED(未登録)」を指定した場合,次のパラメーターの指定は無視されます。
-
execID
-
generation
-
periodBegin
-
periodEnd
-
delayStatus
-
holdPlan
-
execHost
-
execHostMatchMethods
「UNREGISTERED(未登録)」を指定した場合で,ジョブネットリリース機能を使用しているときは,同一ユニット名のユニット情報が複数取得されることがあります。この場合,パラメーターreleaseInfoSearchMethodsとパラメーターreleaseIDを指定して,取得対象を特定してください。
このパラメーターを指定しなかった場合は,「NO」が仮定されます。
任意
delayStatus
取得したいユニットの遅延状態を定数DelayTypeに規定されている文字列定数で指定します。定数DelayTypeの詳細については,「7.4.2(7) DelayType」を参照してください。
このパラメーターを指定しなかった場合,「NO(遅延を検索条件にしない)」が仮定されます。
任意
holdPlan
取得したいユニットの保留予定の有無を定数HoldPlanに規定されている文字列定数で指定します。定数HoldPlanの詳細については,「7.4.2(8) HoldPlan」を参照してください。
「PLAN_YES(保留予定あり)」を指定した場合は,実行待ち,保留中,および実行が終了した世代が対象になります。実行が終了した世代も対象になるため,再実行時に保留される世代の情報も取得されます。実行待ちの世代だけ,実行が終了した世代だけ,または特定の世代だけを取得対象にしたい場合は,パラメーターgenerationやパラメーターstatusを同時に指定して,取得対象の世代を特定してください。
このパラメーターを指定しなかった場合,「NO(保留予定を検索条件にしない)」が仮定されます。
任意
unitComment
取得したいユニットのコメントを指定します。
パラメーターunitCommentMatchMethodsでコメントの比較方法を指定した場合だけ,このパラメーターを指定できます。コメントの比較方法に「NO(検索条件にしない)」を指定した場合は,このパラメーターの指定は無視されます。コメントの比較方法に「EQ(完全一致)」を指定して,このパラメーターに空文字列(0バイト)を指定した場合は,コメントの定義されていないユニットが取得対象となります。
指定できるコメントのバイト数は,パラメーターunitCommentMatchMethodsの指定値によって異なります。
パラメーターunitCommentMatchMethodsの指定値と,このパラメーターに指定できるバイト数を次に示します。
EQ,NE:0〜80バイト
BW,EW,CO,NC:1〜80バイト
RE:1〜164バイト
任意
unitCommentMatchMethods
ユニットのコメントの比較方法を定数MatchMethodsに規定されている文字列定数で指定します。定数MatchMethodsの詳細については,「7.4.2(3) MatchMethods」を参照してください。
このパラメーターを指定しなかった場合,「NO(検索条件にしない)」が仮定されます。
任意
execHost
取得したいユニットの実行ホストを指定します。ユニット定義の実行エージェントではなく,実際に実行されたエージェントホスト名を指定します。
パラメーターexecHostMatchMethodsで実行ホスト名の比較方法を指定した場合だけ,このパラメーターを指定できます。実行ホスト名の比較方法に「NO(検索条件にしない)」を指定した場合は,このパラメーターの指定は無視されます。実行ホスト名の比較方法に「EQ(完全一致)」を指定して,このパラメーターに空文字列(0バイト)を指定した場合は,実行ホストが確定していない待ち状態のジョブが取得対象になります。
指定できる実行ホストのバイト数は,パラメーターexecHostMatchMethodsの指定値によって異なります。
パラメーターexecHostMatchMethodsの指定値と,このパラメーターに指定できるバイト数を次に示します。
EQ,NE:0〜255バイト
BW,EW,CO,NC:1〜255バイト
RE:1〜514バイト
任意
execHostMatchMethods
ユニットの実行ホスト名の比較方法を定数MatchMethodsに規定されている文字列定数で指定します。定数MatchMethodsの詳細については,「7.4.2(3) MatchMethods」を参照してください。
このパラメーターを指定しなかった場合,「NO(検索条件にしない)」が仮定されます。
任意
releaseID
取得したいユニットのリリースIDを1〜30バイトの文字列で指定します。
パラメーターreleaseInfoSearchMethodsで「ID(リリースID)」を指定した場合に,このパラメーターを指定します。その他の指定では,このパラメーターの指定は無視されます。
任意
releaseInfoSearchMethods
リリース情報の取得方法を定数ReleaseInfoSearchMethodsに規定されている文字列定数で指定します。定数ReleaseInfoSearchMethodsの詳細については,「7.4.2(9) ReleaseInfoSearchMethods」を参照してください。
「NO(検索条件にしない)」を指定した場合,すべてのリリース情報が取得対象となります。
このパラメーターを指定しなかった場合,「NO」が仮定されます。
任意
- 注※
-
接続先JP1/AJS3 - Managerの環境設定パラメーターSCHEDULELIMITの詳細については,マニュアル「JP1/Automatic Job Management System 3 構築ガイド 20.4.2(123) SCHEDULELIMIT」を参照してください。
また,JP1/AJS3 - Web Consoleのバージョンはバージョン情報の取得APIの戻り値(productVersionNumber)を,接続先JP1/AJS3 - Managerのバージョンは,JP1/AJS3 - Managerのプロトコルバージョンの取得APIの戻り値(protocolVersionNumber)を確認してください。
バージョン情報の取得APIの詳細については,「7.1.37 バージョン情報の取得API」を参照してください。
JP1/AJS3 - Managerのプロトコルバージョンの取得APIの詳細については,「7.1.38 JP1/AJS3 - Managerのプロトコルバージョンの取得API」を参照してください。
-
- ステータスコード
-
レスポンスで返却するステータスコードを次の表に示します。
ステータスコード
テキスト記述
説明
200
OK
ユニット一覧の取得に成功しました。
400
Bad Request
クエリ文字列が不正です。
401
Unauthorized
認証が必要です。
403
Forbidden
実行権限がありません。
404
Not found
リソースにアクセスする権限がありません。または,リソースがありません。
409
Conflict
リクエストは現在のリソースの状態と矛盾しているため,処理を続行できません。
412
Precondition failed
Web Consoleサーバが利用できません。
500
Server-side error
Web Consoleサーバ処理エラーが発生しました。
- レスポンスの形式
-
- メッセージボディ
{ "statuses":[ステータス監視のリソース,...], "all":すべての情報を取得できたかどうか }
- 戻り値
-
ステータスコードが「200」の場合,次の情報を返却します。
メンバー
データ型
説明
statuses
object[]
ステータス監視のリソースの配列を返却します。条件を満たすユニットが一つも存在しない場合は,要素数0個の配列を返却します。ステータス監視のリソースの詳細については,「7.2.1 ステータス監視のリソース」を参照してください。
all
boolean
すべての情報を取得できたかどうかを返却します。
取得件数が1,000件を超えていない場合,「true」を返却します。取得件数が1,000件を超えている場合,「false」を返却します。
ただし,ログインしたJP1ユーザーに参照権限がないユニットの情報は,取得結果に含まれていません。このため,ログインしたJP1ユーザーに参照権限がないユニットの情報が取得できていない場合でも,取得件数が1,000件を超えていなければ,「true」を返却します。
- 使用例
-
ジョブグループ(/JobGroup)直下のユニット一覧(最新状態)を取得する場合のAPIの使用例を次に示します。
- リクエストの例
GET /ajs/api/v1/objects/statuses?mode=search&manager=HOSTM&serviceName=AJSROOT1&location=%2FJobGroup HTTP/1.1 Host: HOSTW:22252 Accept-Language: ja X-AJS-Authorization: dXNlcjpwYXNzd29yZA==
- レスポンス(メッセージボディ)の例
{ "statuses": [ { "definition": { "owner": "jp1admin", "customJobType": "", "registerStatus": "YES", "rootJobnetName": "/JobGroup/Jobnet", "recoveryUnit": false, "unitType": "ROOTNET", "unitComment": "", "simpleUnitName": "Jobnet", "parameters": "", "execAgent": "", "execFileName": "", "wait": false, "jobnetReleaseUnit": false, "jp1ResourceGroup": "", "unitName": "/JobGroup/Jobnet", "unitID": 1560 }, "release": null, "unitStatus": { "status": "RUNNING", "execHost": "", "startDelayStatus": "NO", "nestStartDelayStatus": "NO", "endDelayStatus": "NO", "nestEndDelayStatus": "NO", "startDelayTime": "", "endDelayTime": "", "changeType": "NO", "registerTime": "", "jobNumber": -1, "retCode": "", "simpleUnitName": "Jobnet", "schStartTime": "2015-09-02T00:00:00+09:00", "reStartTime": "", "endTime": "", "holdAttr": "NO", "startTime": "2015-09-02T22:50:28+09:00", "unitName": "/JobGroup/Jobnet", "execID": "@A2959" } } ], "all": true }