3. WebAPI仕様¶

Swagger WebAPI仕様書

POST /command/{machine}¶

指定したコマンドを実行

指定したコマンドの実行

example)
curl https://api.fugaku.r-ccs.riken.jp/command/computer/ -H "Authorization: Bearer $accessToken" -X POST -d '{"command": "mkdir -p ~/job-script; ls -ld ~/job-script"}'

Parameters

machine (string) --

マシン名

全マシン状態の取得(/status/)で得られるマシン名のいずれか。通常は、"computer"を指定する。

Request JSON Object

command (string) -- (required)

Status Codes

200 OK -- コマンド実行完了
403 Forbidden -- 認証エラー
422 Unprocessable Entity -- 必須パラメータエラー
500 Internal Server Error -- 内部サーバエラー

Response JSON Object

error (string) -- エラーID (required)
output (string) -- コマンド出力結果 (required)
status (string) -- ステータス (required)

GET /status/¶

全マシン状態の取得

全マシン状態の取得

サーバが管理している全マシンの状態を出力する。

example)
curl https://api.fugaku.r-ccs.riken.jp/status -H "Authorization: Bearer $accessToken" -X GET

Status Codes

200 OK -- 全マシン状態
403 Forbidden -- 認証エラー
500 Internal Server Error -- 内部サーバエラー

Response JSON Object

[].machine (string) -- マシン名 (required)
[].status (string) -- ステータス (required)

GET /status/{machine}¶

指定マシン状態の取得

指定マシン状態の取得

指定されたマシンの状態を出力する。

example)
curl -ik https://api.fugaku.r-ccs.riken.jp/api/status/computer/ -H "Authorization: Bearer $accessToken" -X GET

Parameters

machine (string) -- マシン名全マシン状態の取得(/status/)で得られるマシン名のいずれか。通常は、"computer"を指定する。

Status Codes

200 OK -- 特定マシン状態
403 Forbidden -- 認証エラー
500 Internal Server Error -- 内部サーバエラー

Response JSON Object

machine (string) -- マシン名 (required)
status (string) -- ステータス (required)

POST /file/{machine}/{file_path}¶

ファイルアップロード

新規ファイルアップロード

指定したマシン名、ファイルパスにファイルをアップロードする。

example)
curl https://api.fugaku.r-ccs.riken.jp/file/computer/home/hpcadmin/xxxxfile -H "Authorization: Bearer $accessToken" -X POST -d @xxxxfile

Parameters

machine (string) --

マシン名

全マシン状態の取得(/status/)で得られるマシン名のいずれか。通常は、"computer"を指定する。
file_path (string) --

アップロードファイルパス

ファイル名を指定する。

Status Codes

200 OK -- ファイルアップロード完了
403 Forbidden -- 認証エラー
409 Conflict -- コンフリクトエラー
422 Unprocessable Entity -- 必須パラメータエラー
500 Internal Server Error -- 内部サーバエラー

GET /file/{machine}/{file_path}¶

ファイルダウンロード

ファイルダウンロード

指定したマシン名、ファイルパスのファイルをダウンロードする。

example)
curl https://api.fugaku.r-ccs.riken.jp/file/computer/home/hpcadmin/xxxxfile -H "Authorization: Bearer $accessToken"

Parameters

machine (string) --

マシン名

全マシン状態の取得(/status/)で得られるマシン名のいずれか。通常は、"computer"を指定する。
file_path (string) --

ダウンロードファイルパス

ファイル名またはフォルダを指定する。

Query Parameters

view (string) --

ファイル情報取得可否

パラメータにreadを指定していない場合、file_pathで指定したファイルをダウンロードする。

パラメータにreadを指定している場合、指定したディレクトリのファイルリストを出力する。

Status Codes

200 OK --

ファイルダウンロード完了

example
read指定なしの場合：ファイルデータ (binary形式)
read指定ありの場合：{"status": "OK", "output":-rw-rw-r-- 1 f00156 f00156 119 2019-05-16 16:24 test.shn, "error":""}

400 Bad Request -- パラメータエラー
403 Forbidden -- 認証エラー
500 Internal Server Error -- 内部サーバエラー

PUT /file/{machine}/{file_path}¶

ファイル作成/変更

ファイルアップロード/変更

指定したマシン名、ファイルパスにファイルをアップロード(更新)する。

example)
curl https://api.fugaku.r-ccs.riken.jp/file/computer/home/hpcadmin/xxxxfile -H "Authorization: Bearer $accessToken" -X PUT -d @xxxxfile

Parameters

machine (string) --

マシン名

全マシン状態の取得(/status/)で得られるマシン名のいずれか。通常は、"computer"を指定する。
file_path (string) --

ファイルパス

ファイル名を指定する。

Status Codes

200 OK -- ファイル作成/変更完了
400 Bad Request -- パラメータエラー
403 Forbidden -- 認証エラー
422 Unprocessable Entity -- 必須パラメータエラー
500 Internal Server Error -- 内部サーバエラー

GET /queue/{machine}¶

実行中ジョブ一覧取得

実行中ジョブの一覧獲得API  
対象マシン上で、ジョブスケジューラから実行中のジョブ一覧を取得する。  
ジョブIDが指定された場合は、ジョブIDのサブジョブ一覧を取得する。  

example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/ -H "Authorization: Bearer $accessToken" -X GET

Parameters

machine (string) --

マシン名

全マシン状態の取得(/status/)で得られるマシン名のいずれか。通常は、"computer"を指定する。

Query Parameters

index (integer) --

ファーストレコードのインデックス

ページングが必要な場合、limitと合わせて指定する。
limit (integer) --

最大取得レコード数

条件に合う件数がlimitを超過する場合、ジョブの投入時間でソートした古いものから返却する。
status (string) --

ジョブの現在の処理状態

指定された処理状態のジョブのみを返却する。
jobid (string) --

ジョブID

このパラメータが指定された場合、ジョブIDのサブジョブ一覧を取得する。

Status Codes

200 OK -- ジョブ一覧取得処理結果
403 Forbidden -- 認証エラー
500 Internal Server Error -- 内部サーバエラー

Response JSON Object

error (string) -- エラー内容 (required)
output[].accept_time (string) -- 投入時間（yyyy-MM-ddTHH:mm:ss+09:00）
output[].bulkno (string) -- バルク番号
output[].cpu_num (integer) -- 利用CPU数
output[].elapse (string) -- 経過時間
output[].elapse_limit (string) -- 経過時間制限
output[].end_code (string) -- 終了コード
output[].end_time (string) -- 終了時間（yyyy-MM-ddTHH:mm:ss+09:00）
output[].exit_subjob_num (string) -- 完了サブジョブ数
output[].group (string) -- ユーザグループ名
output[].jid (string) -- JID
output[].job_type (string) -- ジョブタイプ
output[].jobid (string) -- ジョブID (required)
output[].name (integer) -- 名称 (required)
output[].node_num (integer) -- ノード形状/ノード数
output[].pjm_code (string) -- PJMコード
output[].queue (string) -- キュー (required)
output[].rsc_grp (string) -- リソースグループ (required)
output[].start_time (string) -- 開始時間（yyyy-MM-ddTHH:mm:ss+09:00）
output[].status (string) -- ジョブの現在の処理状態 ACC　:　ジョブの投入が受け入れられた状態 RJT　:　投入が受付けられなかった状態 QUE　:　ジョブ実行待ち状態 RNA　:　ジョブ実行に必要な資源を獲得中 RNP　:　プロローグ実行中 RUN　:　ジョブ実行中 RNE　:　エピローグ実行中 RNO　:　ジョブ終了処理完了待ち状態 EXT　:　ジョブ終了処理完了 CCL　:　ジョブ実行中止による終了 HLD　:　ユーザによる固定状態 ERR　:　エラーによる固定状態 (required)
output[].stepno (string) -- ステップ番号
output[].subjob_depend (string) -- サブジョブ依存判定式
output[].subjob_num (string) -- サブジョブ数
output[].subjobid (string) -- サブジョブID
output[].timeuse (string) -- 利用時間 (required)
output[].user (string) -- ユーザ名 (required)
status (string) -- ステータス (required)

POST /queue/{machine}¶

ジョブ投入

ジョブ投入API  
指定したマシンから、ジョブスケジューラに対してジョブ投入命令を実行する。  
パラメータはjobfile,jobscriptのいずれかを指定する。
(両方指定された場合はjobfileパラメータを優先する)  

パラメータ	操作例
jobfile	/home/user01/test.sh<br>(スクリプトファイルを指定する)
jobscript	/home/user01/a.out < stdin.dat<br>(スクリプトコマンドを指定する)

example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/ -H "Authorization: Bearer $accessToken" -X POST -d '{"jobfile": "/home/hpcadmin/aaa.sh", "qopt": "jid=100"}'

Parameters

machine (string) --

マシン名

全マシン状態の取得(/status/)で得られるマシン名のいずれか。通常は、"computer"を指定する。

Status Codes

200 OK --

ジョブ投入処理の完了

outputにジョブIDが出力される
400 Bad Request -- パラメータエラー
403 Forbidden -- 認証エラー
422 Unprocessable Entity -- 必須パラメータエラー
500 Internal Server Error -- 内部サーバエラー

Response JSON Object

error (string) -- エラー内容 (required)
output (string) -- ジョブID (required)
status (string) -- ステータス (required)

GET /queue/{machine}/sacct¶

完了済みジョブ一覧取得

対象マシン上で、ジョブスケジューラから24時間以内に完了したジョブの一覧を取得する。  
ジョブIDが指定された場合は、ジョブIDのサブジョブ一覧を取得する。  

example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/sacct -H "Authorization: Bearer $accessToken"

Parameters

machine (string) --

マシン名

全マシン状態の取得(/status/)で得られるマシン名のいずれか。通常は、"computer"を指定する。

Query Parameters

index (integer) --

ファーストレコードのインデックス

ページングが必要な場合、limitと合わせて指定する。
limit (integer) --

最大取得レコード数

条件に合う件数がlimitを超過する場合、ジョブの投入時間でソートした古いものから返却する。
status (string) --

ジョブの現在の処理状態

指定された処理状態のジョブのみを返却する。
jobid (string) --

ジョブID

このパラメータが指定された場合、ジョブIDのサブジョブ一覧を取得する。

Status Codes

200 OK -- 完了済みジョブ一覧取得処理の完了
403 Forbidden -- 認証エラー
500 Internal Server Error -- 内部サーバエラー

Response JSON Object

error (string) -- エラー内容 (required)
output[].accept_time (string) -- 投入時間（yyyy-MM-ddTHH:mm:ss+09:00）
output[].bulkno (string) -- バルク番号
output[].cpu_num (integer) -- 利用CPU数
output[].elapse (string) -- 経過時間
output[].elapse_limit (string) -- 経過時間制限
output[].end_code (string) -- 終了コード
output[].end_time (string) -- 終了時間（yyyy-MM-ddTHH:mm:ss+09:00）
output[].exit_subjob_num (string) -- 完了サブジョブ数
output[].group (string) -- ユーザグループ名
output[].jid (string) -- JID
output[].job_type (string) -- ジョブタイプ
output[].jobid (string) -- ジョブID (required)
output[].name (integer) -- 名称 (required)
output[].node_num (integer) -- ノード形状/ノード数
output[].pjm_code (string) -- PJMコード
output[].queue (string) -- キュー (required)
output[].rsc_grp (string) -- リソースグループ (required)
output[].start_time (string) -- 開始時間（yyyy-MM-ddTHH:mm:ss+09:00）
output[].status (string) -- ジョブの現在の処理状態 ACC　:　ジョブの投入が受け入れられた状態 RJT　:　投入が受付けられなかった状態 QUE　:　ジョブ実行待ち状態 RNA　:　ジョブ実行に必要な資源を獲得中 RNP　:　プロローグ実行中 RUN　:　ジョブ実行中 RNE　:　エピローグ実行中 RNO　:　ジョブ終了処理完了待ち状態 EXT　:　ジョブ終了処理完了 CCL　:　ジョブ実行中止による終了 HLD　:　ユーザによる固定状態 ERR　:　エラーによる固定状態 (required)
output[].stepno (string) -- ステップ番号
output[].subjob_depend (string) -- サブジョブ依存判定式
output[].subjob_num (string) -- サブジョブ数
output[].subjobid (string) -- サブジョブID
output[].timeuse (string) -- 利用時間 (required)
output[].user (string) -- ユーザ名 (required)
status (string) -- ステータス (required)

GET /queue/{machine}/{jobid}¶

ジョブ詳細情報取得

ジョブの詳細情報取得API  
指定したジョブIDまたはサブジョブIDに該当するジョブの詳細情報を取得する。  

example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/{jobid}  -H "Authorization: Bearer $accessToken" -X GET

Parameters

machine (string) --

マシン名

全マシン状態の取得(/status/)で得られるマシン名のいずれか。通常は、"computer"を指定する。
jobid (string) --

ジョブID

詳細情報を取得するジョブIDを指定する。

Status Codes

200 OK -- ジョブ情報取得処理の完了
403 Forbidden -- 認証エラー
500 Internal Server Error -- 内部サーバエラー

Response JSON Object

error (string) -- エラー内容 (required)
output[].accept_time (string) -- 投入時間（yyyy-MM-ddTHH:mm:ss+09:00）
output[].bulkno (string) -- バルク番号
output[].cpu_num (integer) -- 利用CPU数
output[].elapse (string) -- 経過時間
output[].elapse_limit (string) -- 経過時間制限
output[].end_code (string) -- 終了コード
output[].end_time (string) -- 終了時間（yyyy-MM-ddTHH:mm:ss+09:00）
output[].exit_subjob_num (string) -- 完了サブジョブ数
output[].group (string) -- ユーザグループ名
output[].jid (string) -- JID
output[].job_type (string) -- ジョブタイプ
output[].jobid (string) -- ジョブID (required)
output[].name (integer) -- 名称 (required)
output[].node_num (integer) -- ノード形状/ノード数
output[].pjm_code (string) -- PJMコード
output[].queue (string) -- キュー (required)
output[].rsc_grp (string) -- リソースグループ (required)
output[].start_time (string) -- 開始時間（yyyy-MM-ddTHH:mm:ss+09:00）
output[].status (string) -- ジョブの現在の処理状態 ACC　:　ジョブの投入が受け入れられた状態 RJT　:　投入が受付けられなかった状態 QUE　:　ジョブ実行待ち状態 RNA　:　ジョブ実行に必要な資源を獲得中 RNP　:　プロローグ実行中 RUN　:　ジョブ実行中 RNE　:　エピローグ実行中 RNO　:　ジョブ終了処理完了待ち状態 EXT　:　ジョブ終了処理完了 CCL　:　ジョブ実行中止による終了 HLD　:　ユーザによる固定状態 ERR　:　エラーによる固定状態 (required)
output[].stepno (string) -- ステップ番号
output[].subjob_depend (string) -- サブジョブ依存判定式
output[].subjob_num (string) -- サブジョブ数
output[].subjobid (string) -- サブジョブID
output[].timeuse (string) -- 利用時間 (required)
output[].user (string) -- ユーザ名 (required)
status (string) -- ステータス (required)

DELETE /queue/{machine}/{jobid}¶

ジョブキャンセル

指定したジョブIDに該当するジョブをキャンセルする。  
"-(ハイフン)"を使用することによって、ジョブIDの範囲指定が可能です。サブジョブIDも同様に範囲指定が可能です。 

例：ジョブID 1 から 100 までを範囲指定する場合 

1-100 

例：ステップジョブ(ジョブID=100)のステップ番号 1 から 10 までを範囲指定する場合 

100_1-10  

例：バルクジョブ(ジョブID=101)のバルク番号 1 から 10 までを範囲指定する場合 

101[1-10] 

範囲指定する場合、範囲内に以下のようなジョブが含まれていてもエラーにせず、そのジョブを無視して処理を継続します。 

存在しないジョブ , ユーザに権限が無いジョブ , 指定できない状態のジョブ

成功した場合、キャンセル無視の有無を問わず指定した全ジョブIDを返します。

example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/{jobid}  -H "Authorization: Bearer $accessToken"  -X delete

Parameters

machine (string) --

マシン名

全マシン状態の取得(/status/)で得られるマシン名のいずれか。通常は、"computer"を指定する。
jobid (string) --

ジョブID

キャンセルするジョブIDを指定する。

Status Codes

200 OK -- ジョブキャンセル処理の完了
500 Internal Server Error -- 内部サーバエラー

Response JSON Object

error (string) -- エラー内容 (required)
output (string) -- ジョブキャンセル出力結果(jobid) (required)
status (string) -- ステータス (required)

PUT /queue/{machine}/jobscript¶

ジョブ実行スクリプトの生成/変更

ジョブ実行スクリプトの生成/変更API  
対象マシン上にジョブ実行スクリプトを作成する。同名のファイルが存在する場合は、上書きする。
バルクジョブ、ステップジョブを作成する場合は、COMMON_DATAのJTYPEを指定する。

example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/jobscript -H "Authorization: Bearer $accessToken" -X PUT -d '{"script":{"APP_DATA":{"ProgramGroupList":{"ProgramGroup":[{"ProgramList":{"Program":[{"Type":"mpi","FileName":"a.sh","ThreadMode":"parallel","Threads":"100"}]},"GroupType":"serialgroup"}]}},"COMMON_DATA":{}}}'

Parameters

machine (string) --

マシン名

全マシン状態の取得(/status/)で得られるマシン名のいずれか。通常は、"computer"を指定する

Request JSON Object

filename (string) --
script.APP_DATA.ProgramGroupList.ProgramGroup.GroupType (string) --
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.Argument (string) -- 実行プログラムの引数
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].Collect (integer) -- 各ランクからステージアウトされたファイルを区別しない場合：1 (指定されない場合はステージアウトされたファイル名の末尾にランク番号が付与される)
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].FileName (string) -- 実行プログラムが入出力するファイル。
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].IsDirectory (integer) -- ディレクトリをファイルステージングさせる場合：1
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].Rank (string) -- ステージング対象のランク番号を指定する。
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].StageIn (integer) -- ファイルをステージインさせる場合：1
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].StageOut (integer) -- ファイルをステージアウトさせる場合：1
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].UnitNo (string) -- 実行プログラムが入出力するファイルに対応する装置番号を指定する。実行プログラムがFortranである場合のみ有効。
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileName (string) -- 実行プログラム名 (required)
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.Procs (string) -- プロセス当たりのスレッド数。実行プログラムがスレッド並列の場合にのみ有効。
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.StdInFileName (string) -- 標準入力ファイル名
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.StdInRank (string) -- 標準入力ファイルを対象とするファイルステージングノードのランク番号。
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.StdOutCollect (integer) -- *各ランクからステージアウトされたファイルを区別しない場合：1 *指定されない場合はステージアウトされたファイル名の末尾にランク番号が付与される。
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.StdOutFileName (string) -- 標準出力ファイル名
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.StdOutRank (string) -- 標準出力ファイルを対象とするファイルステージングノードのランク番号。
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.ThreadMode (string) -- ・自動並列の場合："parallel" ・OpenMPの場合："omp" ・1スレッドプロセスの場合：指定しない
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.Threads (integer) -- プログラム実行スレッド数
script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.Type (string) -- ・単体プログラムとして実行する場合："serial" ・MPI並列プログラムとして実行する場合："mpi"
script.COMMON_DATA.DEPEND_JID (string) -- 依存ジョブID指定。ジョブタイプ識別子に"S"が指定されている場合のみ有効。
script.COMMON_DATA.ELAPSE (string) -- ジョブの最大実行時間設定。 3パターンでの指定方法が可能。 ①"HHHH:MM:SS" ②"HHHH:MM" ③"HHHH"
script.COMMON_DATA.JGRP (string) -- ジョブ課金グループ指定。
script.COMMON_DATA.JNAME (string) -- 名称: 半角英数記号で63文字まで指定できる。先頭文字は、半角英字のみ。記号は、"-_@."の4種類とする。
script.COMMON_DATA.JTYPE (string) -- ジョブタイプ識別子: *通常ジョブの場合：指定しない *バルクジョブの場合："B" *ステップジョブの場合:"S"
script.COMMON_DATA.NODE (string) -- ジョブに割当てるノード形状を指定する。 X, XxY, XxYxZのいずれかの形式で指定する。
script.COMMON_DATA.NODES (integer) -- 実行プログラムがMPI並列プログラムの場合に、静的に起動するMPIプロセス数。
script.COMMON_DATA.QOPT (string) -- キューのオプション指定。
script.COMMON_DATA.QUEUE (string) -- ジョブを投入するリソースのグループ名指定。
script.COMMON_DATA.QUOTA (string) -- ジョブが使用するディスク使用料の最大値(GB単位)。
script.COMMON_DATA.QUOTA_TYPE (string) -- クォータの型指定。
script.COMMON_DATA.SNUM (string) -- 自サブジョブ番号。ジョブタイプ識別子に"S"が指定されている場合のみ有効。
script.COMMON_DATA.STEP_CODE (string) -- 依存するサブジョブID。ジョブタイプ識別子に"S"が指定されている場合のみ有効。
script.COMMON_DATA.STEP_CONDITION (string) -- 依存関係式。ジョブタイプ識別子に"S"が指定されている場合のみ有効。
script.COMMON_DATA.SUBJOBS_NODE (integer) -- バルクジョブノード数。ジョブタイプ識別子に"B"が指定されている場合のみ有効。
script.COMMON_DATA.SUBJOB_END (string) -- バルクジョブ終了番号。ジョブタイプ識別子に"B"が指定されている場合のみ有効。
script.COMMON_DATA.SUBJOB_START (string) -- バルクジョブ開始番号。ジョブタイプ識別子に"B"が指定されている場合のみ有効。
script.COMMON_DATA.SYSTEM (string) -- ジョブを投入するリソースのユニット名指定。
script.COMMON_DATA.USE_RANK_DIR (string) -- ユーザランクディレクトリの仕様有無フラグ。
script.COMMON_DATA.USE_RANL_DIR (boolean) -- ランク番号ディレクトリを使用する場合：true

Status Codes

200 OK -- ジョブ実行スクリプトの生成完了
400 Bad Request -- パラメータエラー
403 Forbidden -- 認証エラー
422 Unprocessable Entity -- 必須パラメータエラー
500 Internal Server Error -- 内部サーバエラー

Response JSON Object

error (string) -- エラー内容 (required)
output (string) -- ジョブ実行スクリプト生成結果 (required)
status (string) -- ステータス (required)