ソフトウェア・インスタンスの取得

インフラストラクチャーにインストールされているソフトウェアに関する情報を要求するには、api/sam/software_instances エレメントに対して GET 操作を使用します。

重要: 10.0.9 この REST API は api/sam/v2/software_instances REST API に置き換えられました。api/sam/software_instances REST API に基づいているカスタム・ツールまたは内部プロセスがある場合は、新しいバージョンの API を使用するようにツールを調整することをお勧めします。これに関する情報については、以下を参照してください。software_instances REST API と v2/software_instances REST API の列のマッピング。
コンピューター・システムにインストールされているソフトウェア・インスタンスに関する情報を取得するには、次の URL を使用します。 
https://hostname:port/api/sam/software_instances?token=token
注:
  • この API を使用するには、「すべてのコンピューター」グループに割り当てられていて、「エンドポイントの表示」権限が付与されている必要があります。
  • 各 API 要求は、token パラメーターを使用して認証する必要があります。認証トークンを取得するための REST API を使用して取得することができます。BigFix Inventory にログインして「ユーザー」アイコン「ユーザー」アイコンにカーソルを移動して、「プロファイル」をクリックすることもできます。次に、「トークンの表示」をクリックします。
  • デフォルトでは、取得したデータは id 別にソートされます。
表 1. 操作の説明
操作の詳細 「説明」
操作 GET /api/sam/software_instances
目的 ソフトウェアのリストを返します。
HTTP メソッド GET
リソース URI https://server_host_name:port_number/api/sam/software_instances
URL リンク関係 n/a
URI 照会パラメーター 適用可能な照会パラメーターのリストについては、以下を参照してください。「照会パラメーター」。
要求ヘッダー
ヘッダー
Accept-Language (オプション)
値
en-US (英語のみをサポート)

応答の言語のネゴシエーションに使用されます。このヘッダーを指定しない場合、コンテンツはサーバーの言語で戻されます。
要求ペイロード n/a
要求 Content-Type
  • application/json
応答ヘッダー
ヘッダー
Content-Type
値
application/json

応答のコンテンツ・タイプを指定します。
ヘッダー
Content-Language
値
en-US, …

応答のコンテンツの言語を指定します。このヘッダーを指定しない場合、コンテンツはサーバーの言語で戻されます。
ヘッダー
Import-Mode
値
none､idle､running､pending

データ・インポートの状況を示します。
ヘッダー
Import-Progress
値
パーセント値 (例: 59)。

データ・インポートの進行状況をパーセントで示します。
ヘッダー
Import-Last-Status
値
successful、 failed

最後のデータ・インポート状況を示します。
ヘッダー
Import-Last-Success-Time
値
日付 (例: 2014-06-18T04:00:29Z)。

最後の正常なデータ・インポートの時刻を示します。
応答ペイロード Software Instances element
応答 Content-Type
  • application/json
正常な HTTP 応答コード
  • 200 – OK
エラーの HTTP 応答コード
  • 500 – "Bad Request" 照会パラメーターにエラーがあるか、照会パラメーターが欠落している場合

メッセージの本文にはエラー・メッセージと詳細が含まれます。

照会パラメーター

照会パラメーターは、検索結果の絞り込みに使用できます。以下の表は、api/sam/software_instances エレメントに対して使用できる照会パラメーターを示しています。
表 2. ソフトウェア製品を取得するための照会パラメーター
パラメーター 「説明」 必須 値
columns[] 取得する列を指定します。このパラメーターを指定しない場合は、一連のデフォルトの列が取得されます。例:
名前とバージョンの列を取得します。
URL?columns[]=name&columns[]=version
 いいえ ストリング
order 返されたデータのソート方法を指定します。列のソートのデフォルト方向は昇順です。降順ソートを指定する場合は、列名に desc を追加します。例:
コンピューター・システム ID の降順で並び替えるには、次のように指定します。
URL?order[]=computer_system_id desc
 いいえ ストリング
限界値 取得する行数を指定します。このパラメーターを省略した場合、すべての行が取得されます。 いいえ 数字
offset 結果の取得でスキップする行数を指定します。これを limit パラメーターと一緒に使用して、結果をページ編集できます。例:
レコード 150 の後から始まる 50 件のレコードを取得するには、次のとおり指定します。
URL?limit=50&offset=150
 いいえ 数字
token 固有のユーザー認証 ID。自分のトークンは、BigFix Inventory の「プロファイル」設定に表示できます。 はい 英数字
criteria 特定の条件と合致するレコードを取得します。このパラメーターでは、以下の構造が 1 行で記述されている必要があります。 
<criteria> ::= <left-brace> <boolean-operator><colon> <left-bracket> 
<criterion> [{ <comma> <criterion> }...] <right-bracket> <right-brace>

<boolean-operator> ::= "and" | "or"
<criterion> ::= <criteria> | <left-bracket> <column> <comma> <operator> <comma> <value> <right-bracket>
<column> ::= <json-string>
<operator> ::= <json-string>
<value> 	::= <json-array> | <json-string> | <json-numver> | <json-null>

演算子について詳しくは、共通のコネクターおよび演算子を参照してください。

例: 発行者名に「IBM」または特定の日付範囲の前回表示日が含まれているソフトウェア・システムを取得するには、次のとおり指定します。 
URL?criteria={ "or": [ ["publisher_name", "contains", "IBM"], 
{ "and": [ ["last_seen", ">", "1970-01-01T00:00:00+00:00Z"], 
["last_seen", "<", "1970-01-02T00:00:00+00:00Z"] ] } ] }
「前回表示日時」など、日時の値を使用する列の場合、特定の日付の代わりにある期間のデータを取得することもできます。これを行うには、last または next を <operator> として使用し、次の規則で時刻の値を指定します。PxD/PxW/PxM/PxY。ここで、x は 1 から 999 の範囲の数値であり、D、W、M、Y はそれぞれ、日、週、月、年を表す指定子です。例えば、過去 7 日間の間にレポートしたソフトウェア・インスタンスを取得するには、次の API 要求を使用します。 
URL?criteria={"and":[["last_seen","last","P7D"]]}

HTTP 会話の例

要求
GET api/sam/software_instances
?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
応答ヘッダー
HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: en-US
上記の応答ヘッダーの後には、Import-Mode で表わされるデータ・インポートの現在の状況に応じてそれぞれ異なる項目が続きます。返される値について理解するために、以下の定義を確認してください。
  • none - データ・インポートが一度も開始されていない
  • idle - データ・インポートは現在実行されていない
  • running - データ・インポートは進行中
  • pending - ユーザー・インターフェースで実行されるアクションが、データ・インポートを開始して変更を有効にすることを必要とする
データ・インポートが一度も開始されていない場合:
Import-Mode: none
データ・インポートが進行中の場合:
Import-Mode: running
Import-Progress: 41
データ・インポートが実行されていない場合:
Import-Mode: idle/pending
Import-Last-Status: successful
Import-Last-Success-Time: Mon, 23 Jun 2014 12:18:29 GMT
応答の本文 (JSON)
特定の項目がデフォルトで非表示になっている場合、一般 URL を使用してもその項目は取得されません。このようなデータを取得するには、照会パラメーターを使用して、非表示の列の名前を指定する必要があります。例えば、以下に示すように、columns[] パラメーターを使用して、computer_id 列および software_title_name 列を取得できます。 
URL?columns[]=computer_id&columns[]=catalog_dimension.software_title_name
{
"id": 123,	
"software_fact_id": 123, //hidden by default
"computer_system_id": 3,
"computer_id": 3,        //hidden by default
"discoverable_guid": "0768fb15-383c-4124-a7e2-0d76dda06874",
"default_product_guid": "78d380e0-9fb9-11e3-a151-005056872dc7",//hidden by default
"first_used": null,
"last_used": null,
"valid_from": "2014-04-02T14:24:04Z",
"valid_to": "9999-12-31T23:59:59Z",
"updated_at": "2014-04-02T14:24:04Z",
"signature_count": 1,
"total_time": 0,
"total_runs": 0,
"avg_run_time": null,
"avg_runs_per_day": null,
"process": null,
"deleted": false,        //hidden by default
"catalog_dimension":     //hidden by default
   {
   "software_title_name": "BigFix Platform Agent",
   "publisher_name": "IBM",
   "software_title_version_name": "BigFix Platform Agent",
   "software_title_release_name": "BigFix Platform Agent",
   "version": "9.0" 
   }
}