| On this page |
概要 ¶
XML/RPCクライアントを介して(同じマシンから、または、ネットワーク上で)HQueueサーバーの関数をコールすることができます。このサーバーのAPIを使ってジョブを投入または照会することができます。
XML/RPCは、関数コールと戻り値をHTTPリクエスト/レスポンスに変換するための、言語に依存しな単純な規格です。 PythonにはビルトインのXML/RPCクライアントライブラリが入っているので、実際にそのプロトコルに関して何も知る必要がなく、単にリモートコールが可能な基本テクノロジーだと思って構いません。
HQueue クライアント に接続して関数をコールすることもできますが、このAPIだと非常に限られています。
サーバーに接続する方法 ¶
Python3では、xmlrpc.clientライブラリを使ってサーバーに接続することができます(Python2では、これはxmlrpclibライブラリでした)。
他の言語でXML/RPCクライアントを利用可能ですが、このページではPythonに限定しています。
import xmlrpc.client # HQueueサーバーに接続します。 hq = xmlrpc.client.ServerProxy("http://hq_server_hostname:5000")
戻り値のオブジェクトは、リモートAPIのプロキシとして作用します。 つまり、リモートのHQueueサーバー内の関数をコールするような感覚で、このオブジェクト上の関数アトリビュートをコールすることができます。 以下の利用可能な関数のリストを参照してください。
この接続が無効な場合、プロキシの関数をコールすると例外が発生します:
try: hq.ping() except ConnectionRefusedError: print("HQueue server is not available")
Note
引き起こされる例外の種類に関しては、XML/RPCクライアントライブラリのドキュメントを確認してください。
以下のサンプルは、プロキシオブジェクトの関数をコールする方法を示しています:
-
新しいジョブを投入する:
# Mantraを使ってIFDから画像をレンダリングするジョブを定義します。 job_spec = { "name": "Render My Image", "shell": "bash", "command": ( "cd $HQROOT/houdini_distros/hfs;" " source houdini_setup;" " mantra < $HQROOT/path/to/ifds/some_frame.ifd" ) } job_ids = hq.newjob(job_spec)
-
newjob()が返したJob ID(s)をgetJob()で使用することで、ジョブの進捗を照会することができます:job = hq_server.getJob(job_ids[0], ["progress", "status"]) status = job["status"] print("The job status is", status) if status in hq.getRunningJobStatusNames(): print("{:.2f}% complete".format(job["progress"] * 100.0))
クライアントに接続する方法 ¶
HQueueクライアントはXML/RPC APIサーバーとしても作用します。 これによって、クライアントからサーバーに心拍を送信したり、クライアントを強制終了させる関数をコールすることができます。
import xmlrpc.client # HQueueクライアントに接続します。 hq_client = xmlrpc.client.ServerProxy("http://hq_client_hostname:5001")
Client API ¶
getVersion()
→ str
HQueueクライアントのバージョンを返します。
ping()
→ bool
HQueueクライアントが生存していてアクティブになっているかどうかをテストします。これは常にTrueを返します。
wakeup()
クライアントがスリープ状態になっていて、その心拍をサーバーに送信させると、そのクライアンが目を覚まします。
terminate()
クライアントを強制終了させるように要求します。クライアントを強制終了させると、以下の結果になります:
-
そのクライアントで停止されているジョブがすべてキャンセルされます。
-
新しいジョブがそのクライアントに割り当てられなくなります。
-
そのクライアントで現在実行されているジョブは、それが完了するまで実行が継続されます。
-
HQueueサーバーのクライアントリストから、そのクライアントが削除されます。
-
そのクライアント上のすべてのジョブの実行が終了すると、そのクライアントプロセスが終了します。
サーバーAPI ¶
キュー ¶
runcmd(cmd)
→ int
HQueueファーム上で、指定したコマンドを実行します。これは、commandプロパティをcmdに設定した新しい匿名ジョブを作成することで行なわれます。ジョブはクライアントマシンに割り当てられてから処理されます。
匿名ジョブのIDを返します。
getNumWaitingJobs(wait_time=0, min_priority=-1, max_priority=-1)
→ int
wait_time分以上経過したジョブの数を返します。
待機中のジョブとは、リソースが空くのを待っているジョブのことです。例えば、利用可能なクライアントマシンが空くのを待機しています。
wait_timeが0またはマイナスの値なら、待機中ジョブの総数を返します。
min_priorityが0以上なら、min_priority以上の優先度を持つジョブのみが、その総数にカウントされます。 min_priorityが0未満の場合、最小優先度の制限が外れます。
max_priorityが0以上なら、max_priority以下の優先度を持つジョブのみが、その総数にカウントされます。 max_priorityが0未満の場合、最大優先度の制限が外れます。
getServerTime()
→ xmlrpc.client.DateTime
HQueueサーバーから報告された現在の時刻を返します。時刻はUTCです。
getServerErrors()
→ dict
HQueueサーバーから報告されたエラーを返します。報告するエラーがなければ、空っぽのリストを返します。
返される辞書には2つのキーが含まれています:totalとerrorsです。totalはサーバーエラーの数、errorsはエラーのリスト(各エラーはdictです)。
報告するエラーがなければ、空っぽの辞書を返します。
getVersion()
→ str
HQueueサーバーのバージョンを返します。
ping()
→ bool
HQueueサーバーが生存していてアクティブになっているかどうかをテストします。これは常にTrueを返します。
クライアント ¶
getClients(client_ids=None, attribs=None)
→ list
of dict
辞書のリストを返します。各辞書には、client_idsで指定したクライアント毎のアトリビュートを含んでいます。
client_idsはクライアントID番号のリストでなければなりません。client_idsを指定しない場合やNoneに設定されている場合は、登録されているクライアントすべてのアトリビュートを返します。
オプションのattribs引数に、返したいクライアントのアトリビュートのリストを設定することができます。これは関数の実行時間と返すデータ量を削減することができます。
以下にクライアントのアトリビュートのリストを載せます:
-
available- ジョブを処理するクライアントが現時点で利用可能か否か。 -
availabilityRules- ファーム上のクライアント有効ルールのリスト。 -
cpus- CPUの数。 -
cpuSpeed- プロセッサーの周波数。 -
description- 説明が設定されている場合は、そのクライアントの説明。クライアントに何も説明を設定していない場合は、空っぽの文字列が返されます。 -
disabled- クライアントがファーム上で無効になっているか否か。 -
groups- クライアントがメンバーになっているグループIDのリスト。 -
hostname- クライアントマシンの名前。 -
id- クライアントID。 -
idleTime- クライアントがアイドル(ログインユーザからの活動がない)状態になってからの分単位の経過時間。これはワークステーションにのみ適用されます。アイドル時間が不明なら-1に設定されます。 -
ip- クライアントのIPアドレス。 -
label- クライアントの表示ラベル。クライアントにnameが設定されていない場合は、このラベルはクライアントのhostnameになります。設定されている場合は、このラベルはhostname:nameになります。hostnameがクライアントのホスト名、nameがクライアントの名前です。 -
lastHeartbeat- クライアントが最後にサーバーと通信した時刻。時刻はUTCです。 -
latestNote- クライアントに該当したスレッドの最新のノートのテキスト。該当するスレッドがなければ、空っぽの文字列が返されます。 -
load- クライアントの負荷。 -
memory- キロバイト単位の物理メモリ量。 -
memoryInUse- プロセスで現在使用中のキロバイト単位の物理メモリ量。 -
name- クライアントのhqnode.iniファイルで名前が指定されていれば、それがクライアントの名前です。デフォルトでは、これは空っぽ(つまり、"")です。 -
needsUpgrade- クライアントのコードが古いかどうか、そしてアップデートを要求します。 -
platform- クライアントのオペレーティングシステムとアーキテクチャ。 -
runningJobs- クライアントで現在実行しているジョブのID。 -
threadId- クライアントに該当したノートスレッドのID。該当するスレッドがなければ、nullが返されます。 -
version- クライアントにインスールされたHQueueコードのバージョンを意味するハッシュ文字列。
getClient(client_id, attribs=None)
→ dict
getClients()を便利にした関数。指定したclient_idのクライアントのアトリビュートを辞書で返します。
getClientByName(clientname, attribs=None)
→ dict
getClients()を便利にした関数。指定したclientnameのクライアントのアトリビュートを辞書で返します。
clientnameには、ホスト名でクライアント指定するhostnameフォーマット、または、hostnameとnameを使ってクライアントを参照するhostname:nameフォーマットのどちらかを指定することができます。
デフォルトでは、クライアントの名前は空っぽ("")になっています。
getClientsByName(clientnames, attribs=None)
→ list
of dict
getClients()を便利にした関数。辞書のリストを返します。各辞書には、clientnamesで指定したクライアント名のクライアント毎のアトリビュートを含んでいます。
clientnamesはクライアント名のリストでなければなりません。clientnamesには、ホスト名でクライアント指定するhostnameフォーマット、または、hostnameとnameを使ってクライアントを参照するhostname:nameフォーマットのどちらかを指定することができます。
getClientErrors(client_id)
→ dict
client_idで指定したクライアンから報告されたエラーを返します。
返される辞書には2つのキーが含まれています:totalとerrors。totalはクライアントエラーの数、errorsはエラーのリスト(各エラーはdictです)。
報告するエラーがなければ、空っぽの辞書を返します。
upgradeClients(client_ids)
client_idsのリストにあるクライアントをアップグレードします。
クライアントグループ ¶
createClientGroup(name)
→ int
nameで指定した名前のクライアントグループを新しく作成します。その新しいグループのIDが返されます。
getClientGroups(group_ids=None, attribs=None)
→ list
of dict
辞書のリストを返します。各辞書には、group_idsで指定したクライアントグループ毎のアトリビュートを含んでいます。
group_idsは、グループID番号のリストでなければなりません。group_idsを指定しない場合やNoneに設定されている場合は、登録されているクライアントグループすべてのアトリビュートを返します。
オプションのattribs引数に、返したいクライアントグループのアトリビュートのリストを設定することができます。これは関数の実行時間と返すデータ量を削減することができます。
以下にクライアントグループのアトリビュートのリストを載せます:
-
clients- グループのメンバーであるクライアントのIDのリスト。 -
id- グループID -
name- グループ名
getClientGroup(group_id, attribs=None)
→ dict
getClientGroups()の便利関数。指定したクライアントグループのアトリビュートの辞書を返します。
getClientGroupByName(name, attribs=None)
→ dict
getClientGroups()の便利関数。指定したクライアントグループのアトリビュートの辞書を返します。
addClientToGroup(group_id, client_id)
client_idに関連したクライアントをgroup_idに関連したグループに追加します。
removeClientFromGroup(group_id, client_id)
group_idに関連したグループから、client_idに関連したクライアントを削除します。
deleteClientGroup(group_id)
group_idに関連したクライアントグループを削除します。
ジョブ管理 ¶
newjob(jobspec,parent_id=None,child_ids=[])
→ list
of int
ジョブをサーバーにサブミットします。jobspecには、ジョブの仕様を意味するJSON文字列、辞書、辞書のリストのどれかを指定することができます。ジョブの仕様の詳細は、ジョブの仕様を参照してください。
オプションのparent_id引数に、新しいジョブの親にしたいジョブのIDを設定することができます。
オプションのchild_ids引数に、新しいジョブの子にしたい既存ジョブのIDのリストを設定することができます。
このメソッドは新しいジョブのIDをリストで返します。
getUnfinishedRootJobIds()
→ list
of int
終了していないルートジョブのジョブIDをリストで返します。ルートジョブとは親ジョブのないジョブのことです。
getFinishedRootJobIds()
→ list
of int
終了したルートジョブすべてのジョブIDをリストで返します。ルートジョブとは、親ジョブのないジョブのことです。
pauseJobs(job_ids)
job_idsのリスト内の各ジョブにリンクされているジョブすべてを停止します。
この関数は非同期で、即座に戻ります。
resumeJobs(job_ids)
job_idsのリスト内の各ジョブにリンクされているジョブすべてを再開します。
この関数は非同期で、即座に戻ります。
rescheduleJobs(job_ids)
job_idsのリスト内の各ジョブにリンクされているジョブすべてのスケジュールを変更します。
この関数は非同期で、即座に戻ります。
cancelJobs(job_ids)
job_idsのリスト内の各ジョブにリンクされているジョブすべてをキャンセルします。
この関数は非同期で、即座に戻ります。
deleteJobs(job_ids)
job_idsのリスト内の各ジョブにリンクされているジョブすべてを削除します。
この関数は非同期で、即座に戻ります。
ejectJobs(job_ids)
job_idsのリスト内の各ジョブにリンクされているジョブすべてをイジェクトします。
この関数は非同期で、即座に戻ります。
ジョブ照会 ¶
getJobs(job_ids, attribs=None)
→ list
of dict
辞書のリストを返します。各辞書には、job_idsで指定したジョブ毎のアトリビュートを含んでいます。
job_idsはジョブID番号のリストでなければなりません。
オプションのattribs引数に、返したいジョブのアトリビュートのリストを設定することができます。これは関数の実行時間と返すデータ量を削減することができます。
以下にジョブのアトリビュートのリストを載せます:
-
children- 子ジョブのIDのリスト。 -
clients- ジョブを実行中または実行したクライアントのリスト。 -
clientsOnHold- ジョブを保留中(または予約している)のクライアントのリスト。ジョブを複数のクライアントで実行する必要があるのに、いくつかのクライアントしか現時点では利用できない場合には、ジョブをクライアントに保留することができます。保留中のクライアントの数がジョブを実行するのに十分な数になると、それらのクライアントにジョブが割り当てられます。 -
conditions- ジョブに与えられたスケジュール条件のリスト。 -
endTime- ジョブが終了した時刻。時刻はUTCです。ジョブ終了していない場合は、Noneに設定されます。 -
ETA- ジョブが完了するまでの秒単位の推定時間。ETAを計算できない場合は、-1に設定されます。このアトリビュートの計算には、HQueueがジョブとその子ジョブを照会する必要があるので、getJobsのパフォーマンスがかなり遅くなることに注意してください。 -
id- ジョブのID。 -
latestNote- ジョブに関連したスレッドの最近のノートのテキスト。スレッドがなければ、空っぽの文字列を返します。 -
logs- ジョブのステータス変更ログのすべてのリスト。 -
name- ジョブの名前。 -
overallProgress- ジョブとその子ジョブの全体の進捗状況のパーセンテージ(0.0から1.0までの間)。このアトリビュートの計算には、HQueueがジョブとその子ジョブを照会する必要があるので、getJobsのパフォーマンスがかなり遅くなることに注意してください。 -
parents- 親ジョブのIDのリスト。 -
priority- ジョブの優先度。 -
progress- ジョブコマンドの進捗状況のパーセンテージ(0.0から1.0までの間)。ジョブに実行するコマンドがなければ、常に0.0に設定されます。 -
queueTime- ジョブをHQueueにサブミットまたはキューしたした時刻。時刻はUTCです。 -
resources- ジョブが要求するリソースの辞書。各キーはリソース名で、各値はジョブが要求する各リソースの数です。ジョブがどのリソースも要求していない場合にはNoneが返されます。ジョブリソースの詳細は、リソースを参照してください。 -
showBlockedClientsWarning- JobページのRunning Jobsテーブルの状況項目に警告アイコンを表示させるかを指定するブーリアンフラグ。そのアイコンをクリックすると、ジョブがブロックしているクライアントに関する情報をダイアログで表示されます。 -
startTime- ジョブまたはその子ジョブが開始した時刻。時刻はUTCです。 -
status- 内部ジョブステータス。HQueueはジョブそれ自体だけを照会します(その子ジョブを照会しない)。そのため、このアトリビュートの要求は非常に高速に機能します。ジョブが終了しているかどうかだけに興味があるなら、 uiStatus の代わりに、このアトリビュートを要求します。このアトリビュートで利用可能な値は、 abandoned, canceled, failed, paused, pausing, resuming, running, succeeded, runnable, queued です。 runnable は waiting for machine UIステータスと同等です。 queued は、ジョブを実行する前にその子ジョブが終了するのを待っていることを意味しています。 -
tags- ジョブに追加したタグ、カスタムプロパティのリスト。特に single タグは他のジョブが実行されていないマシンにのみジョブが実行されることを意味します。 -
threadId- ジョブに関連したスレッドのID。スレッドがなければ、Noneを返します。 -
triesLeft- ジョブが失敗した後に再実行を試みる回数。例えば、ジョブのtriesLeftが2で、そのジョブを実行した後に失敗すれば、自動的に再スケジュールしてキューに入り、そのtriesLeftの値が減って1に設定されます。 -
uiStatus- HQueue Webインターフェースに表示されるジョブステータス。利用可能なUIジョブステータスのリストは、ジョブのステータスに載せています。このアトリビュートは、ジョブとその子ジョブすべてを照会する必要があるので、getJobsのパフォーマンスがかなり遅くなることに注意してください。 -
waitingFor- リソースが利用可能なのにジョブが待機している理由。ジョブが待機中でない場合やリソースが利用不可の場合は、空っぽの文字列が返されます。
getJob(job_id, attribs=None)
→ dict
getJobs()を便利にした関数。指定したジョブのアトリビュートを辞書で返します。
getJobHistory(client_id, limit=5)
→ list
of int
指定したクライアントで最近実行したジョブのIDをリストで返します。リストの中のIDは、1番目の項目がクライアントで最後に終了したジョブのIDとなるようにジョブの終了時刻順に並べられています。オプションのlimit引数を指定すれば、そのリストの最大数を指定することができます。
getJobOutput(job_id, max_last_chars=None)
→ str
指定したジョブの出力ログを返します。そのログを最大でオプションのmax_last_charsで指定した文字数まで返します。max_last_charsを指定しなかった場合は、出力ログすべてを返します。
getJobIdsAssignedToClient(client_id)
→ list
of int
指定したクライアントに割り当てられているジョブのIDをリストで返します。そのクライアントが存在しなければ、空っぽのリストが返されます。
getJobIdsByStatus(statuses)
→ list
of int
指定したステータスのリストで見つかったステータを持つジョブのIDをリストで返します。
有効なステータスの名前は以下の通りです:
-
abandoned -
canceled -
failed -
paused -
pausing -
queued -
resuming -
running -
runnable -
succeeded -
waiting
メタ ¶
getNetworkFolders()
→ list
of dict
登録済みのネットワークフォルダのリストを返します。 このリスト内の各ネットワークフォルダは、文字列キーと文字列値の辞書で表現されます。
以下は、そのネットワークフォルダ辞書のキーです:
-
name- ネットワークフォルダの名前。この名前は、ジョブ環境内の変数で使用され、ネットワークフォルダパスを表現します。 -
linuxMount- Linuxマシン上のネットワークフォルダのマウントポイントパス。 -
macOSMount- Mac OSマシン上のネットワークフォルダのマウントポイントパス。 -
windowsMount- Windowsマシン上のネットワークフォルダのマウントポイントパス。 -
linuxHostPath(廃止。下位互換のためだけにあります) - ネットワークフォルダのホストサーバーとパス。このキーは、Linuxマシン上にマウントポイントを作成するようにHQueueに要求する時に使用されていました。 -
macOSHostPath(廃止。下位互換のためだけにあります) - ネットワークフォルダのホストサーバーとパス。このキーは、Mac OSマシン上にマウントポイントを作成するようにHQueueに要求する時に使用されていました。 -
windowsHostPath(廃止。下位互換のためだけにあります) - ネットワークフォルダのホストサーバーとパス。このキーは、Windowsマシン上にマウントポイントを作成するようにHQueueに要求する時に使用されていました。
getAllJobStatusNames()
→ list
of str
取得可能なジョブステータスすべてをリストで返します。
getRunningJobStatusNames()
→ list
of str
実行中のジョブを意味するステータスをリストで返します。
getPausedJobStatusNames()
→ list
of str
停止ジョブを意味するステータスをタプルで返します。
getFinishedJobStatusNames()
→ list
of str
終了したジョブを意味するステータスをタプルで返します。
getSucceededStatusNames()
→ list
of str
成功したジョブステータスを意味する名前をリストで返します。
getWaitingJobStatusNames()
→ list
of str
待機中ジョブを意味するステータスをリストで返します。
getFailedJobStatusNames()
→ list
of str
失敗したジョブを意味するステータスをタプルで返します。
getUnfinishedJobStatusNames()
→ list
of str
終了していないジョブを意味するステータスをリストで返します。
getPriorityChangedEventNames()
→ list
of str
優先度変更イベントの名前をリストで返します。
getStartedJobEventNames()
→ list
of str
開始ジョブイベントを意味する名前をリストで返します。
getRescheduledEventNames()
→ list
of str
スケジュール変更イベントの名前をリストで返します。
getResumedEventNames()
→ list
of str
再開イベントの名前をリストで返します。
リソース ¶
詳細は、リソースを参照してください。
getResources(resource_ids=None)
→ list
of dict
辞書のリストを返します。各辞書はリソースを表現しています。引数を渡さなかった場合、すべてのリソースのリストが返されます。
コンフィギュレーション ¶
getConfig(key)
→ str
or None
指定したキーの設定値を返します。キーが設定ファイルに存在しなければ、Noneを返します。
getPermittedClientsList(job_id)
→ list
of str
指定したジョブの実行が許可されているクライアントのホスト名のリストを返します。クライアントに名前を設定していない場合、それらのクライントはホスト名で指定します。設定している場合、hostname:nameフォーマットで指定します。hostnameはクライアントのホスト名、nameはクライアントの名前です。
savePermittedClientsList(job_id, clients_list)
指定したジョブIDのジョブに許可されているクライアントホスト名の新しいリストを保存し、指定したクライアントのみがこのジョブを実行できるように適切な条件を作成します。以前の既存条件は置換されます。
clients_list内のクライアントには、以下のフォーマットのどれかで指定することができます:
-
'hostname' → 'hostname'のホスト名のクライアントがこのジョブを実行することができます。
-
'hostname:name' → 'hostname'のホスト名で、'name'の名前のクライアントのみがこのジョブを実行することができます。
-
'hostname:' → 'hostname'のホスト名で、名前が空っぽ(“”)のクライアントのみがこのジョブを実行することができます。
setdisabled(clientname, disabled)
→ bool
disabledの値に応じて、指定したクライアントマシンを無効または有効にします。disabledはTrueまたはFalseのどれかでなければなりません。
clientnameには、ホスト名でクライアントを指定したhostname書式、または、hostnameとnameを使ってクライアントを参照したhostname:name書式のどちらかを指定することができます。
デフォルトでは、クライアントの名前は空っぽ("")です。
メソッドが成功すればTrueを返します。失敗すればNoneを返します。
setShowBlockedClientsWarning(job_id, state)
指定したジョブのshowBlockedClientsWarningアトリビュートの値を設定します。指定したジョブに該当するJobsページのRunning Jobsテーブルの状況項目に警告アイコンを表示するには、stateをTrueに設定します。警告アイコンを非表示にするには、stateをFalseに設定します。そのアイコンをクリックすると、そのジョブがブロックしているクライアントに関する情報と、そのジョブで許可されているクライアントのリストを閲覧するためのオプションがあるダイアログが表示されます。
ノート ¶
詳細は、ノートの使い方を参照してください。
getNoteThreads(thread_ids=None,thread_attribs=None,note_attribs=None)
→ list
of dict
辞書のリストを返します。各辞書には、 thread_idsで指定したスレッド毎のアトリビュートを含んでいます。
thread_idsがNoneの場合は、すべてのスレッドの辞書が返されます。
thread_attribsに、返したいスレッドのアトリビュートのリストを設定します。ノートのアトリビュートを返したいなら、note_attribsに、返したいノートのアトリビュートのリストを設定します。これらの引数は関数の実行時間と返すデータ量を削減することができます。
以下にスレッドのアトリビュートのリストを載せます:
-
clientHostname- スレッドに関連したクライアントのホスト名。 -
clientId- スレッドに関連したクライアントのID。 -
clientLabel- スレッドに関連したクライアントの表示ラベル。クライアントに名前を設定していない場合、これはclientHostnameと同じになります。設定している場合、これはhostname:nameです。hostnameはクライアントのホスト名、nameはクライアントの名前です。 -
jobId- スレッドに関連したジョブのID。 -
notes- スレッドに属するノート。
以下にノートのアトリビュートのリストを載せます:
-
clientHostname- スレッドに関連したクライアントのホスト名。 -
clientId- スレッドに関連したクライアントのID。 -
clientLabel- スレッドに関連したクライアントの表示ラベル。クライアントに名前を設定していない場合、これはclientHostnameと同じになります。設定している場合、これはhostname:nameです。hostnameはクライアントのホスト名、nameはクライアントの名前です。 -
date- ノートを最後に追加した日付と時刻。 -
id- ノートのID。 -
jobId- スレッドに関連したジョブのID。 -
text- ノートの内容。 -
threadId- ノートの親スレッドのID。
getNoteThreadIds()
→ list
of int
すべてのスレッドのIDのリストを返します。
threadExists(thread_id)
→ bool
or None
指定したIDのスレッドが存在するかどうかを意味するブーリアン値を返します。
このメソッドを実行した時にエラーが起きると、Noneを返します。
removeSingleThread(thread_id)
→ bool
指定したIDのスレッドとそのスレッドに属するノートすべてを削除します。
成功すればTrueを返します。失敗すればFalseを返します。
removeThreads(thread_ids)
→ list
of int
複数指定したIDのスレッドとそれらのスレッドに属するノートすべてを削除します。
削除できなかったスレッドのIDをリストで返します。
getLatestNotes(thread_ids=None, attribs=None)
→ list
of dict
辞書のリストを返します。各辞書には、thread_idsで指定したスレッド毎の最近のノートのアトリビュートを含んでいます。
thread_idsはスレッドID番号のリストまたはNoneでなければなりません。Noneの場合は、ジョブのすべての最近のノートが返されます。
オプションのattribs引数に、返したいノートのアトリビュートのリストを設定することができます。これは関数の実行時間と返すデータ量を削減することができます。
以下にノートのアトリビュートのリストを載せます:
-
clientHostname- スレッドに関連したクライアントのホスト名。 -
clientId- スレッドに関連したクライアントのID。 -
clientLabel- スレッドに関連したクライアントの表示ラベル。クライアントに名前を設定していない場合、これはclientHostnameと同じになります。設定している場合、これはhostname:nameです。hostnameはクライアントのホスト名、nameはクライアントの名前です。 -
date- ノートを最後に追加した日付と時刻。 -
id- ノートのID。 -
jobId- スレッドに関連したジョブのID。 -
text- ノートの内容。 -
threadId- ノートの親スレッドのID。
addNote(note_text, thread_id, job_id, client_id)
→ bool
ノートを既存のメッセージスレッドまたは新しいスレッドに追加します。
client_idがNoneでない場合、ノートは指定したクライアントに関連したメッセージスレッドに追加されます。
job_idがNoneでない場合、ノートは指定したジョブに関連したメッセージスレッドに追加されます。
thread_idがNoneでない場合、ノートは指定したメッセージスレッドに追加されます。
client_idもjob_idもthread_idもNoneの場合、または、既存のメッセージスレッドがこれらの引数に対して見つからなかった場合、新しいメッセージスレッドが作成されます。
note_textが空っぽ、または、空白のみの場合、ノートは追加されません。
client_id、job_id、thread_idのどれか2個以上が指定されていて、それらがNoneでない場合、RPC失敗が返され、そのノートは追加されません。
(ノートが追加されなくても)常にTrueを返します。
removeNotes(note_ids)
→ list
of int
指定したIDのノートをサーバーから削除します。たくさんのノートを削除する場合は、スレッドの1番目のノートのIDをnote_idsの最後に入れてください。
削除できなかったノートのIDをリストで返します。
removeSingleNote(note_id)
→ bool
指定したIDのノートをサーバーから削除します。
成功すればTrueを返します。失敗すればFalseを返します。
廃止された関数 ¶
getClientsByHostname(hostnames, attribs=None)
→ list
of dict
廃止 代わりにgetClientsByName()を使用してください。
getClientByHostname(hostname, attribs=None)
→ dict
廃止 代わりにgetClientByName()を使用してください。
getHQRoot(platform, is_client=True)
→ str
or None
指定したプラットフォームのマシンで有効な$HQROOT環境変数の値を返します。
platformは、“linux”,“windows”,“macos”のどれかでなければなりません。
platformに“macosx”を指定できなくなりました。
platformがそれらの値のどれでもない場合は、Noneを返します。platformが“windows”でis_clientがTrueならUNCパスを返します。
getEnvRoot(platform, name, is_client=True)
→ str
or None
指定したプラットフォームのマシン上で表示される$name環境変数の値を返します。 nameはNetwork Foldersページで定義された有効な環境変数でなければなりません。 platformには、“linux”, “windows”, “macos”のどれかを指定してください。 platformに“macosx”を指定できなくなりました。
platformがそれらの値のどれでもない場合は、Noneを返します。platformが“windows”でis_clientがTrueならUNCパスを返します。