Extraction d'instances logicielles

Utilisez l'opération GET sur l'élément api/sam/software_instances pour demander des informations sur les logiciels installés dans votre infrastructure.

Important : 10.0.9

Cette API REST est désormais remplacée par l'API REST api/sam/v2/software_instances. Si certains de vos outils personnalisés ou processus internes reposent sur l'API REST api/sam/software_instances, il est recommandé de les ajuster de sorte qu'ils utilisent la nouvelle version de l'API. Pour plus d'informations, voir : Mappage de colonnes entre l'API REST software_instances et v2/software_instances.

Pour extraire les informations sur les instances logicielles installées sur vos systèmes informatiques, utilisez l'URL suivante :

https://hostname:port/api/sam/software_instances?token=token

Remarque :

Pour utiliser cette API, vous devez être affecté au groupe Tous les ordinateurs et disposer du droit Afficher les nœuds finals.
Chaque demande d'API doit être authentifiée avec le paramètre token. Vous pouvez l'extraire en utilisant l'API REST pour l'extraction du jeton d'authentification. Vous pouvez également vous connecter à BigFix Inventory, survoler l'icône Utilisateur et cliquer sur Profil. Cliquez ensuite sur Afficher le jeton.
Par défaut, les données extraites sont triées par id.

Tableau 1. Descriptions des opérations
Détails de l'opération	Description
Fonctionnement	`GET /api/sam/software_instances`
Finalité	Renvoie une liste de logiciels.
Méthode HTTP	`GET`
URI de resources	https://`server_host_name`:`port_number`/api/sam/software_instances
Relation du lien de l'URL	n/a
Paramètres de requête URI	Pour une liste de paramètres de requêtes applicables, voir : Paramètres de requête.
En-têtes de demande	Fonction métier `Accept-Language` (Facultatif) Valeurs en-US (seul l'anglais est pris en charge) Sert à négocier la langue de la réponse. Si cet en-tête n'est pas spécifié, le contenu est renvoyé dans la langue du serveur.
Charge de la demande	Non disponible
Demande `Content-Type`	`application/json`
En-têtes de réponse	En-tête `Content-Type` Valeurs `application/json` Définit le type de contenu de la réponse.
	En-tête `Content-Language` Valeurs en-US, … Définit la langue du contenu de la réponse. Si cet en-tête n'est pas spécifié, le contenu est renvoyé dans la langue du serveur.
	En-tête `Import-Mode` Valeurs `none`, `idle`, `running`, `pending` Indique l'état d'importation des données.
	En-tête `Import-Progress` Valeurs Une valeur en pourcentage, par exemple `59`. Indique la progression en pourcentage d'une importation de données.
	En-tête `Import-Last-Status` Valeurs `successful`, `failed` Indique l'état de la dernière importation de données.
	En-tête `Import-Last-Success-Time` Valeurs Date, par exemple `2014-06-18T04:00:29Z`. Indique l'heure de la dernière importation de données qui a réussi.
Charge de la réponse	`Software Instances` élément
Réponse`Content-Type`	`application/json`
Codes de réponse normaux HTTP	`200 – OK`
Codes de réponse HTTP d'erreur	`500 – "Bad Request"` si un paramètre de requête contient des erreurs ou est manquant Le corps du message comprend un message d'erreur détaillé.

Paramètres de requête

Vous pouvez utiliser des paramètres de requête pour limiter le nombre de résultats de votre recherche. Le tableau suivant présente les paramètres de requête que vous pouvez utiliser pour l'élément api/sam/software_instances.

Tableau 2. Paramètres de requête pour l'extraction de produits logiciels
Paramètre	Description	Requis	Valeur
columns[]	Indique les colonnes à extraire. Si vous n'indiquez pas ce paramètre, un ensemble de colonnes par défaut est extrait. Exemple : éxtrayez les colonnes name et version : `URL?columns[]=name&columns[]=version`	Non	Chaîne
order	Indiquez comment trier les données renvoyées. Le sens de tri par défaut des colonnes est croissant. Si vous souhaitez spécifier un tri par ordre décroissant, ajoutez `desc` au nom de la colonne. Exemple : Ordre décroissant par ID de système informatique : `URL?order[]=computer_system_id desc`	Non	Chaîne
limit	Indiquez le nombre de lignes à extraire. Si vous omettez ce paramètre, toutes les lignes sont extraites.	Non	Numérique
décalage	Indiquez le nombre de lignes à ignorer pour extraire les résultats. Vous pouvez l'utiliser en même temps que le paramètre de limite pour mettre en page les résultats. Exemple : éxtrayez 50 enregistrements en commençant après l'enregistrement 150 : `URL?limit=50&offset=150`	Non	Numérique
Jeton	Identificateur d'authentification utilisateur unique. Vous pouvez afficher votre jeton dans les préférences du profil de BigFix Inventory.	Oui	Alphanumérique
critères	éxtrayez les enregistrements qui correspondent à des conditions spécifiques. Le paramètre doit avoir la structure suivante, écrite sur une seule ligne : `<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>` Pour plus d'informations sur les opérateurs, voir Connecteurs et opérateurs communs. Exemple : éxtrayez des instances logicielles dont le nom d'éditeur contient "IBM" OU la dernière date vue dans une plage de dates spécifique : `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"] ] } ] }` Pour les colonnes qui utilisent les valeurs de date et d'heure, comme Vu pour la dernière fois, vous pouvez également récupérer les données sur une période au lieu d'une date spécifique. Pour ce faire, utilisez `last` ou `next` comme <operator>, puis spécifiez la valeur de temps selon la convention suivante : PxD/PxW/PxM/PxY, où x est un nombre compris entre 1 et 999 et D, W, M ou Y est un identificateur qui représente les jours, semaines, mois ou années, respectivement. Par exemple, pour extraire les instances logicielles signalées dans les 7 derniers jours, utilisez la demande API suivante : `URL?criteria={"and":[["last_seen","last","P7D"]]}`

Exemple de conversation HTTP

Demande

GET api/sam/software_instances
?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US

En-tête de réponse

HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: en-US

L'en-tête de réponse ci-dessus peut être suivi par différentes entrées, en fonction de l'état actuel de l'importation de données qui est représentée par Import-Mode. Pour comprendre les valeurs renvoyées, voir les définitions suivantes :

none - aucune importation de données n'a été initiée
idle - aucune importation de données ne s'exécute actuellement
running - une importation de données est en cours
pending - une action exécutée dans l'interface utilisateur nécessite le démarrage d'une importation de données pour que le changement prenne effet

Si aucune importation de données n'a été initiée :

Import-Mode: none

Si une importation de données est en cours :

Import-Mode: running
Import-Progress: 41

Si aucune importation de données n'est en cours d'exécution :

Import-Mode: idle/pending
Import-Last-Status: successful
Import-Last-Success-Time: Mon, 23 Jun 2014 12:18:29 GMT

Corps de réponse (JSON)

Si une entrée particulière est masquée par défaut, elle n'est pas extraite en cas d'utilisation de l'URL générale. Pour extraire ces données, vous devez utiliser les paramètres de requête pour spécifier le nom de la colonne masquée. Par exemple, vous pouvez extraire les colonnes computer_id et software_title_name en utilisant le paramètre columns[] :

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" 
   }
}