Extraction de l'utilisation des métriques de licence (v2)

9.2.10 Disponible à partir de la version 9.2.10. Utilisez l'opération GET sur l'élément api/sam/v2/license_usage pour demander des informations sur l'utilisation des métriques de licence en fonction des produits installés dans votre infrastructure. Par défaut, les résultats sont renvoyés pour le groupe d'ordinateurs de l'utilisateur dont le jeton est utilisé pour l'authentification et couvrent la période pour laquelle les données sont agrégées dans ce groupe. Ils incluent également des zones personnalisées ajoutées au rapport Toutes les métriques.

Droits

Utilisateur Vous devez disposer des droits Afficher les métriques de licence pour utiliser cette API.

URL de la ressource

https://hostname:port/api/sam/v2/license_usage?token=token

Informations sur les ressources

Tableau 1. Informations sur les ressources
Détails de l'opération	Description
Méthode HTTP	`GET`
En-têtes de demande	Fonction métier `Accept-Language` (Facultatif) Valeurs en-US (seul l'anglais est pris en charge) Négocie la langue de la réponse. Si l'en-tête n'est pas spécifié, le contenu est renvoyé dans la langue du serveur.
Format de demande	`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 l'en-tête n'est pas spécifié, le contenu est renvoyé dans la langue du serveur.
	En-tête `startdate` Valeurs `YYYY-MM-DD` Indique la date à partir de laquelle les données sont extraites.
	En-tête `enddate` Valeurs `YYYY-MM-DD` Indique la date jusqu'à laquelle les données sont extraites.
	En-tête `computerGroupId` Valeurs éntier Indique l'ID du groupe d'ordinateurs pour lequel les données sont extraites.
Charge de la réponse	`License Usage` element
Format de réponse	`application/json`
Codes de réponse	`200 – OK` `400 – "Bad Request"` si un paramètre de requête contient des erreurs ou est manquant

Description de schéma

Pour extraire la liste de toutes les colonnes renvoyées par cette API REST, ainsi que leurs descriptions, utilisez la demande suivante :

GET api/sam/v2/schemas/license_usage.json?token=token

Colonnes disponibles

Tableau 2. Colonnes disponibles
Colonne	Description	Affichée par défaut	Type
product_publisher_name	Nom de l'éditeur du produit.	✓	Chaîne
product_id	Identificateur du produit logiciel.		éntier
product_name	Nom du produit logiciel.	✓	Chaîne
product_family_guid	Identificateur global unique du produit logiciel.		Chaîne
metric_id	Identificateur de la métrique de licence. Pour plus d'informations sur les valeurs renvoyées, voir : ID et noms de code de métrique.		Chaîne
metric_name	Nom de la métrique de licence. La valeur renvoyée par le paramètre `metric_name` est fournie à titre de référence et peut différer légèrement de la valeur indiquée pour la description de métrique dans ID métrique, nom de code et description. Il est recommandé d'extraire les métriques à l'aide des paramètres `metric_id` ou `metric_code_name`, puis de vérifier la description des métriques en vous reportant au ID métrique, nom de code et description.		Chaîne
metric_code_name	Nom de code de la métrique de licence. Pour plus d'informations sur les valeurs renvoyées, voir : ID et noms de code de métrique.	✓	Chaîne
hwm_quantity	Nombre maximal d'unités de métrique que le produit a utilisées au cours de la période d'extraction des données. Lorsque la quantité de métriques n'est pas mesurée pour une métrique de licence spécifique, la valeur renvoyée par le paramètre hwm_quantity est -1. La valeur -1 ne peut pas être utilisée pour le tri ou le filtrage.	✓	éntier
threshold	Nombre maximal d'unités de métrique que le produit est autorisé à utiliser au sein d'un groupe d'ordinateurs. La valeur est définie manuellement et est utilisée pour calculer le delta du seuil de métrique.		éntier
threshold_delta	Valeur calculée en soustrayant la quantité de métriques au seuil. Lorsque vous indiquez un seuil pour une métrique de licence qui n'est pas calculée, la valeur renvoyée par le paramètre threshold_delta est 2147483647. La valeur 2147483647 ne peut pas être utilisée pour le tri ou le filtrage.		éntier
imported_part_numbers	Numéro de référence que vous avez importé dans BigFix Inventory. Il représente le produit indiqué dans la colonne product_name et sa métrique de licence.		Chaîne
is_reaggregation_needed	Indique si un nouveau calcul est nécessaire pour le produit. Le paramètre ne peut pas être utilisé pour filtrer ou trier les résultats.		Valeur boléenne
custom_field_number	Zone personnalisée qui a été ajoutée au rapport Toutes les métriques. Pour obtenir la liste de toutes les zones personnalisées, affichez le schéma license_usage.json.		Problèmes divers
hwm_peak_time	Date et heure auxquelles le nombre d'unités de métrique le plus élevé a été utilisé par un produit pendant la période sélectionnée. Si la valeur du paramètre hwm_quantity est -1, la valeur de hwm_peak_time n'est pas significative. Remarque : L'extraction de la valeur de hwm_peak_time risque d'augmenter fortement le temps d'extraction des données.		Chaîne
bundle_id	ID du groupement FlexPoint ou du Cloud Pak auquel le produit est affecté.		éntier
bundle_name	Nom du groupement FlexPoint ou du Cloud Pak auquel le produit est affecté.		Chaîne
bundle_type	Type du groupement. Valeurs possibles : -1 - N'est pas un groupement 0 - Groupement FlexPoint 1 - Cloud Pak		Ensemble d'entiers
bundle_guid	GUID du groupement FlexPoint ou du Cloud Pak auquel le produit est affecté.		Chaîne
bundle_metric_contribution	Lorsque le produit fait partie d'un groupement FlexPoint ou d'un Cloud Pak, la colonne indique le nombre d'unités de métrique de licence que le produit spécifique représente dans la quantité de métriques globale du groupement FlexPoint ou du cloud Pak auquel ce produit est affecté. Il s'agit de la valeur de la colonne hwm_quantity multipliée par l'option de conversion indiquée pour le produit spécifique. Lorsque le produit ne fait pas partie du groupement FlexPoint ou d'un Cloud Pak, la colonne est vide.		éntier
product_bundle_ratio_divider	Lorsque le produit fait partie d'un groupement FlexPoint ou d'un Cloud Pak, la colonne affiche le diviseur du ratio utilisé pour convertir les métriques de licence du produit en métriques de licence du groupement. Par exemple, lorsque les utilisateurs IBM Security QRadar SOAR sont installés dans le cadre d'IBM Cloud Pak for Security, le ratio de conversion est 5:1. La valeur de la colonne product_bundle_ratio_divider dans ce cas est 5.		éntier
product_bundle_ratio_factor	Lorsque le produit fait partie d'un groupement FlexPoint ou d'un Cloud Pak, la colonne indique le facteur du ratio utilisé pour convertir les métriques de licence du produit en métriques de licence du groupement. Par exemple, lorsque les utilisateurs IBM Security QRadar SOAR sont installés dans le cadre d'IBM Cloud Pak for Security, le ratio de conversion est 5:1. La valeur de la colonne product_bundle_ratio_factor dans ce cas est 1.		éntier

Paramètres de requête

Tableau 3. Paramètres de requête
Paramètre	Description	Requis	Valeur
columns	Indique les colonnes à extraire. Si vous n'indiquez pas ce paramètre, seules les colonnes par défaut sont extraites. Exemple : Extraction du nom de produit et du delta de seuil `URL?columns[]=product_name&columns[]=threshold_delta`		Chaîne
computerGroupId	Indiquez l'ID du groupe d'ordinateurs pour lequel vous souhaitez extraire les données. Si vous ne spécifiez pas ce paramètre, les données sont extraites pour le groupe d'ordinateurs de l'utilisateur dont le jeton est utilisé pour l'authentification. Si vous spécifiez le paramètre, vous pouvez extraire les données d'un sous-groupe de ce groupe d'ordinateurs. Pour afficher les ID des groupes d'ordinateurs, connectez-vous à BigFix Inventory et accédez à Rapports > Groupes d'ordinateurs. Ensuite, survolez l'icône Gérer la vue de rapport , puis cliquez sur Configurer la vue et sélectionnez la colonne d'ID pour l'afficher sur le rapport. Exemple : éxtraire les données du groupe d'ordinateurs 5 `URL?computerGroupId=5`		éntier
order	Indiquez comment trier les données récupéré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 : Classement par delta de seuil `URL?order[]=threshold_delta desc`		Alphanumérique
limit	Indiquez le nombre de lignes à extraire. Si vous omettez ce paramètre, toutes les lignes sont extraites. Exemple : éxtraire 100 enregistrements `URL?limit=100`		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 limit pour mettre en page les résultats. Exemple : éxtrayez 50 enregistrements en commençant après l'enregistrement 150 `URL?limit=50&offset=150`		Numérique
startdate	Spécifiez la date à partir de laquelle vous souhaitez récupérer les données. Indiquez-la au format `YYYY-MM-DD`. Si vous n'indiquez pas le filtre, sa valeur par défaut est la date de la dernière importation de données réussie dans BigFix Inventory, moins le nombre de jours pour lesquels les données sont calculées dans le groupe d'ordinateurs (90 jours par défaut). Exemple : éxtraire les données à partir du 14 juillet 2017 `URL?startdate=2017-07-14`		Date
enddate	Indiquez la date jusqu'à laquelle vous souhaitez extraire les données. Indiquez-la au format `YYYY-MM-DD`. Si vous n'indiquez pas le filtre, sa valeur par défaut est la date de la dernière importation de données réussie dans BigFix Inventory. Exemple : éxtraire les données du 1er octobre 2017 au 31 octobre 2017 `URL?startdate=2017-10-01&enddate=2017-10-31`		Date
Jeton	Identificateur d'authentification utilisateur unique. 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.	✓	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-number> \| <json-null>` Remarque : L'API REST `license_usage` ne prend pas en charge les critères de filtrage imbriqués. Exemple 1 : Extraction des instances logicielles dont le nom de produit inclut "BigFix" et dont le delta de seuil est inférieur à 0 `URL?criteria={"and":[["product_name","contains","BigFix"], ["threshold_delta","<","0"] ] }` Dans le cas des zones `threshold` et `custom_field_number`, vous pouvez extraire toutes les entrées dont la valeur est indiquée ou n'est pas indiquée. Exemple 2 : Extraction des produits pour lesquels le seuil est indiqué `URL?criteria={"and":[["threshold","!=",]]}` Exemple 3 : Extraction des produits logiciels pour lesquels le seuil n'est pas indiqué `URL?criteria={"and":[["threshold","=",]]}` Si vous avez créé des zones personnalisées qui utilisent les valeurs de date, vous pouvez également extraire les données pour 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. Exemple 4 : Extraction des produits logiciels pour lesquels l'autorisation se termine le mois prochain `URL?criteria={"and":[["custom_field_1","next","P1M"]]}` Pour plus d'informations sur les opérateurs, voir : Connecteurs et opérateurs communs.		Chaîne

Exemple de conversation - Colonne par défaut

Demande

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

En-tête de réponse

Status Code: 200 OK
Content-Type: application/json
computerGroupId: 0
enddate: 2017-10-31
startdate: 2017-10-01

Corps de la réponse

[{

"product_publisher_name": "IBM",
"product_name": "WebSphere Service Registry and Repository",
"metric_code_name": "PVU_FULL_CAP",
"hwm_quantity": 480
}]

Exemple de conversation - Toutes les colonnes

Demande

GET api/sam/v2/license_usage?columns[]=product_id
&columns[]=product_name&columns[]=product_family_guid&columns[]=metric_id
&columns[]=metric_name&columns[]=metric_code_name&columns[]=hwm_quantity
&columns[]=threshold&columns[]=threshold_delta&columns[]=imported_part_numbers
&columns[]=is_reaggregation_needed&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US

Corps de la réponse

[{

"product_publisher_name": "IBM",
"product_id": 29258,
"product_name": "WebSphere Service Registry and Repository",
"product_family_guid": "3b31a72e-468d-47bb-825a-ea26c8e85199",
"metric_id": 3,
"metric_code_name": "PVU_FULL_CAP",
"metric_name": "PVU Full Capacity",
"hwm_quantity": 480,
"threshold": null,
"threshold_delta": null,
"imported_part_numbers": null,
"is_reaggregation_needed": 0
"bundle_name": null, 
"bundle_type": -1,
"bundle_guid": null,
"bundle_metric_contribution": null
}]

Exemple de conversation - Colonne supplémentaire

Demande

GET api/sam/v2/license_usages?columns[]=product_name
&columns[]=metric_name&columns[]=threshold_delta
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US

Corps de la réponse

[{
"product_name": "WebSphere Service Registry and Repository",
"metric_name": "PVU Full Capacity",
"threshold_delta": 100
}]

Exemple de conversation - Colonne par défaut

Pour extraire les données de zones personnalisées qui ont été ajoutées au rapport Toutes les métriques, commencez par afficher le schéma license_usage.json. Le schéma répertorie toutes les colonnes, y compris les zones personnalisées. Indiquez la zone personnalisée dont vous souhaitez extraire les données.

Demande - Vérification de la liste des zones personnalisées créées

GET api/sam/v2/schemas/license_usage.json?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623

Réponse - Liste de toutes les colonnes, y compris les zones personnalisées

[{
"product_name":
      {
       "type": "string",
       "description": "Name of the software product."
       },
...

"custom_field_1":
       {
       "type": "date",
       "title": "Entitlement End"
       }
}]

Après avoir identifié le nom de la zone personnalisée, vous pouvez l'utiliser dans la requête d'API REST.

Demande

GET api/sam/v2/license_usages?columns[]=product_name
&columns[]=custom_field_1&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US

Corps de la réponse

[{
"product_name": "WebSphere Service Registry and Repository",
"custom_field_1": "2017-10-01"
}]

Exemple de conversation - Extraction d'informations sur les groupements FlexPoint et les Cloud Paks

Demande

GET api/sam/v2/license_usages?columns[]=product_name
&columns[]=bundle_name&columns[]=bundle_type&columns[]=bundle_metric_contribution
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623&criteria={"and":[["bundle_type","in","[0,1]"]]}
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US

Corps de la réponse

[{
"product_name": "IBM WebSphere Application Server Network Deployment",
"bundle_name": "IBM Cloud Pak for Applications"
"bundle_type": "1"
"bundle_metric_contribution": "100"
}]