Vérifier l’API des autorisations
L’API Verify Entitlements fournit des points de terminaison qui vous permettent d’obtenir une liste d’autorisations valides, des détails sur les caractéristiques des autorisations et les dernières informations d’utilisation d’une autorisation.
Pour accéder à cette API, le module d’extension Entitlement Verification (sn_ent_verify) doit être activé.
Cette API est fournie dans l’espace de noms sn_ent_verify .
L’utilisateur appelant doit avoir le rôle sn_pss_core.pss_integrator.
- Compte [customer_account]
- Consommateur [csm_consumer]
- Autorisation [service_entitlement]
- Caractéristique d’autorisation [sn_pss_core_entitlement_characteristic]
- Utilisations des autorisations [sn_pss_core_entitlement_usage]
- Ménage [csm_household]
- Base d’installation [sn_install_base_item]
- Offre de produits [sn_prd_pm_product_offering]
- Modèle de produit [cmdb_model]
- Contrat de service [sn_pss_core_service_contract]
- Ligne de contrat de service [sn_pss_core_service_contract_line]
- Produit vendu [sn_install_base_sold_product]
Vérifier les autorisations : /sn_ent_verify/verifyentitlements
Renvoie les enregistrements d’autorisation valides en fonction du filtre fourni.
- Compte
- Consommateur
- Contrat
- Ménage
- Base d'installation
- Modèle de produit
- Offre de produits
- Ligne de contrat de service
- Autorisation vendue
- Produit vendu
- État
Lorsque plusieurs paramètres de filtre sont transmis, le point de terminaison applique l’opérateur AND aux paramètres. Par exemple, si vous transmettez des paramètres de filtre tels que « compte = boxeo » et « état = brouillon », le point de terminaison renvoie toutes les autorisations avec Compte = boxeo ET état = brouillon.
Vous pouvez implémenter la pagination pour les résultats de retour en transmettant les paramètres sysparm_offset de pagination système et sysparm_limit. Par défaut sysparm_offset , il est défini sur 0 et sysparm_limit est défini sur 10. Ainsi, si après avoir appliqué le filtre, 100 autorisations satisfont aux critères, la réponse inclura les 10 premières autorisations. Vous pouvez modifier ces valeurs en les transmettant dans l’appel de point de terminaison.
Format d'URL
URL versionnée : /api/sn_ent_verify/v1/verifyentitlements
URL par défaut : /api/sn_ent_verify/verifyentitlements
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| api_version | Facultatif. Version du point de terminaison auquel accéder. Exemple : v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière. Type de données : chaîne |
| sysparm_limit | Facultatif. Nombre maximal d'enregistrements à renvoyer. Pour les demandes qui dépassent ce nombre d'enregistrements, utilisez le paramètre sysparm_offset pour paginer la récupération d'enregistrements. Dans la réponse, le paramètre hasMore booléen est renvoyé. Il indique s’il existe d’autres enregistrements à renvoyer qui répondent aux critères de filtre. Type de données : nombre Par défaut : 10 Maximum : 100 |
| sysparm_offset | Facultatif. Index de début des enregistrements pour lequel commencer à récupérer des enregistrements. Utilisez cette valeur pour paginer la récupération des enregistrements. Cette fonctionnalité permet de récupérer tous les enregistrements, quel que soit le nombre d'enregistrements, par petits blocs gérables. Par exemple, lors du premier appel de ce point de terminaison, sysparm_offset est défini sur « 0 ». Pour parcourir simplement tous les enregistrements disponibles, utilisez le paramètre Ne transmettez pas de nombre négatif dans le paramètre sysparm_offset. Type de données : nombre Par défaut : 0 |
| Nom | Description |
|---|---|
| compte | Le account paramètre ou consumer doit être transmis. Ils s'excluent mutuellement. Sys_id de l’enregistrement de compte pour lequel renvoyer des enregistrements d’autorisation. Situé dans la table Compte [customer_account]. Type de données : chaîne Par défaut : Aucun |
| consommateur | Le account paramètre ou consumer doit être transmis. Ils s'excluent mutuellement. Sys_id de l’enregistrement de consommateur pour lequel renvoyer les enregistrements d’autorisation. Situé dans la table Consommateur [csm_consumer]. Type de données : chaîne Par défaut : Aucun |
| contrat | Sys_id de l’enregistrement de contrat pour lequel renvoyer les enregistrements d’autorisation. Situé dans la table Contrat [sn_pss_core_service_contract]. Type de données : chaîne Par défaut : Aucun |
| display_value | Marqueur indiquant s’il faut renvoyer la valeur de champ, la valeur d’affichage ou les deux. Valeurs valides :
Type de données : chaîne Valeur par défaut : false |
| household | Sys_id de l’enregistrement de ménage pour lequel renvoyer les enregistrements d’autorisation. Situé dans la table Ménage [csm_household]. Type de données : chaîne Par défaut : Aucun |
| install_base | Sys_id de l’enregistrement de base d’installation pour lequel renvoyer les enregistrements d’autorisation. Situé dans la table Base d’installation [sn_install_base_item]. Le point de terminaison utilise la sys_id de l’enregistrement de base d’installation pour rechercher la table Produit vendu couvert [sn_install_base_m2m_contract_sold_product] » afin de renvoyer toutes les autorisations couvertes par la base d’installation associée. Type de données : chaîne Par défaut : Aucun |
| Produit | Sys_id de l’enregistrement de produit pour lequel renvoyer les enregistrements d’autorisation. Situé dans la table Modèle de produit [cmdb_model]. Type de données : chaîne Par défaut : Aucun |
| product_offering | Sys_id de l’enregistrement d’offre de produit pour lequel renvoyer les enregistrements d’autorisation. Situé dans la table Offre de produits [sn_prd_pm_product_offering]. Type de données : chaîne Par défaut : Aucun |
| service_contract_line | Sys_id de l’enregistrement de ligne de contrat de service pour lequel renvoyer les enregistrements d’autorisation. Situé dans la table Ligne de contrat de service [sn_pss_core_service_contract_line]. Type de données : chaîne Par défaut : Aucun |
| sold_entitlement | Sys_id de l’enregistrement d’autorisation vendu pour lequel renvoyer les enregistrements d’autorisation. Situé dans la table Produit vendu [sn_install_base_sold_product]. Type de données : chaîne Par défaut : Aucun |
| sold_product | Sys_id de l’enregistrement du produit vendu pour lequel renvoyer les enregistrements d’autorisation. Situé dans la table Produit vendu [sn_install_base_sold_product]. Le point de terminaison utilise le sys_id de l’enregistrement du produit vendu pour rechercher la table « Produit vendu couvert [sn_install_base_m2m_contract_sold_product] » afin de renvoyer toutes les autorisations couvertes par le produit vendu associé. Type de données : chaîne Par défaut : Aucun |
| État | État des autorisations de retour. Valeurs valides :
Type de données : chaîne Par défaut : Tous |
| Nom | Description |
|---|---|
| Aucun |
En-têtes
Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml. Valeur par défaut : application/json |
| En-tête | Description |
|---|---|
| Aucun |
Codes d'état
Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été correctement traitée. |
| 403 | Interdit. L’utilisateur ne possède pas les droits d’accès à l’enregistrement spécifié. |
| 404 | Introuvable. L’élément demandé est introuvable. |
| 500 | Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur. |
Paramètres du corps de réponse (JSON ou XML)
| Nom | Description |
|---|---|
| autorisations liées aux services | Liste des autorisations qui correspondent aux critères de filtre réussis. Type de données : tableau d’objets |
| autorisations.compte | Sys_id de l’enregistrement de compte associé à cette autorisation. Situé dans la table Compte [customer_account]. Type de données : chaîne |
| Autorisations.Consommateur | Sys_id de l’enregistrement de consommateur associé à cette autorisation. Situé dans la table Consommateur [csm_consumer]. Type de données : chaîne |
| autorisations.contrat | Sys_id de l’enregistrement de contrat associé à cette autorisation. Situé dans la table Contrat [sn_pss_core_service_contract]. Type de données : chaîne |
| end_date | Valeur du champ Date de fin sur l’enregistrement d’autorisation associé. Type de données : chaîne |
| entitlements.entitlement_name | Nom de l’autorisation. Type de données : chaîne |
| Autorisations.Ménage | Sys_id de l’enregistrement de ménage associé à cette autorisation. Situé dans la table Ménage [csm_household]. Type de données : chaîne |
| autorisations.produit | Sys_id de l’enregistrement de produit associé à cette autorisation. Situé dans la table Modèle de produit [cmdb_model]. Type de données : chaîne |
| entitlements.product_offering | Sys_id de l’enregistrement d’offre de produit associé à cette autorisation. Situé dans la table Offre de produit [sn_prd_pm_product_offering]. Type de données : chaîne |
| entitlements.service_contract_line | Sys_id de l’enregistrement de ligne de contrat de service associé à cette autorisation. Situé dans la table Ligne de contrat de service [sn_pss_core_service_contract_line]. Type de données : chaîne |
| entitlements.sold_entitlement | Sys_id de l’enregistrement de l’autorisation vendue associé à cette autorisation. Situé dans la table Produit vendu [sn_install_base_sold_product]. Type de données : chaîne |
| entitlements.start_date | Valeur du champ Date de début sur l’enregistrement d’autorisation associé. Type de données : chaîne |
| autorisations.état | État de l’enregistrement des autorisations. Valeurs valides :
Type de données : chaîne |
| entitlements.sys_id | Sys_id de l’enregistrement d’autorisation. Situé dans la table Autorisation [service_entitlement]. Type de données : chaîne |
| erreur | Décrit l’erreur qui s’est produite. Type de données : objet Exemples de réponses d’erreur :
|
| error.detail | Informations détaillées sur la raison de l’échec de l’appel de point de terminaison. Type de données : chaîne |
| message.erreur | Message décrivant l’erreur à un niveau élevé. Type de données : chaîne |
| hasMore | Marqueur indiquant s’il existe d’autres enregistrements d’autorisation à renvoyer. Valeurs valides :
Type de données : booléennes |
| statut | État de l’appel de point de terminaison. Valeurs valides :
Type de données : chaîne |
| sysparm_limit | Si les sysparm_limit paramètres ont été transmis dans l’appel de point de terminaison, ils contiennent la valeur transmise, sinon ils contiennent la valeur par défaut. Type de données : nombre |
| sysparm_offset | Si les sysparm_offset paramètres ont été transmis dans l’appel de point de terminaison, ils contiennent la valeur transmise, sinon ils contiennent la valeur par défaut. Type de données : nombre |
Demande cURL
L’exemple de code suivant montre comment renvoyer les autorisations pour un compte spécifique.
curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?account=9e2fd2ee11b43110f877366201dea674" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Résultats renvoyés :
{
"result": {
"sysparm_offset": "0",
"sysparm_limit": "10",
"has_more": "false",
"entitlements": [
{
"sys_id": "38374bf251e27110f877bf82d3ddf30a",
"entitlement_name": "test ent",
"account": "9e2fd2ee11b43110f877366201dea674",
"consumer": null,
"household": null,
"contract": "0e1747f251e27110f877bf82d3ddf31c",
"service_contract_line": "da278fb251e27110f877bf82d3ddf3b7",
"state": "active",
"product_offering": null,
"sold_entitlement": null,
"product": null,
"start_date": "2023-11-21",
"end_date": ""
},
{
"sys_id": "e6ad4e4151723d10f877bf82d3ddf3fb",
"entitlement_name": "tets entitlement",
"account": "9e2fd2ee11b43110f877366201dea674",
"consumer": null,
"household": null,
"contract": "0e1747f251e27110f877bf82d3ddf31c",
"service_contract_line": "e79dce4151723d10f877bf82d3ddf31d",
"state": "active",
"product_offering": null,
"sold_entitlement": null,
"product": null,
"start_date": "2023-11-21",
"end_date": ""
}
],
"status": "success"
}
}Demande cURL
L’exemple de code suivant montre comment renvoyer des autorisations pour un compte et une ligne de contrat de service spécifiques.
curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?service_contract_line=e79dce4151723d10f877bf82d3ddf31d&account=9e2fd2ee11b43110f877366201dea674" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Résultats renvoyés :
{
"result": {
"sysparm_offset": "0",
"sysparm_limit": "10",
"has_more": "false",
"entitlements": [
{
"sys_id": "e6ad4e4151723d10f877bf82d3ddf3fb",
"entitlement_name": "test entitlement",
"account": "9e2fd2ee11b43110f877366201dea674",
"consumer": null,
"household": null,
"contract": "0e1747f251e27110f877bf82d3ddf31c",
"service_contract_line": "e79dce4151723d10f877bf82d3ddf31d",
"state": "active",
"product_offering": null,
"sold_entitlement": null,
"product": null,
"start_date": "2023-11-21",
"end_date": ""
}
],
"status": "success"
}
}Demande cURL
L’exemple de code suivant montre une réponse d’erreur.
curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?service_contract_line=e79dce4151723d10f877bf82d3ddf31d" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Résultats renvoyés :
{
"error": {
"detail": "At least one of Account or Consumer parameter is mandatory.",
"message": "At least one of Account or Consumer parameter is mandatory."
},
"status": "failure"
}Vérifier les autorisations : /sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/{id}
Renvoie les détails de l’enregistrement de la caractéristique d’autorisation spécifié et de son dernier enregistrement d’utilisation.
Le dernier enregistrement d’utilisation d’une caractéristique est défini comme l’enregistrement dont la date de début de la période est inférieure ou égale à la date actuelle et la date de fin de la période est supérieure ou égale à la date actuelle.
Format d'URL
URL versionnée : /api/sn_ent_verify/v1/verifyentitlements/getEntitlementCharacteristic/{id}
URL par défaut : /api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/{id}
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| api_version | Facultatif. Version du point de terminaison auquel accéder. Exemple : v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière. Type de données : chaîne |
| id | Sys_id de l’enregistrement de la caractéristique d’autorisation à retourner. Situé dans la table Caractéristique de l’autorisation [sn_pss_core_entitlement_characteristic]. Type de données : chaîne |
| Nom | Description |
|---|---|
| display_value | Marqueur indiquant s’il faut renvoyer la valeur de champ, la valeur d’affichage ou les deux. Valeurs valides :
Type de données : chaîne Valeur par défaut : false |
| Nom | Description |
|---|---|
| Aucun |
En-têtes
Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml. Valeur par défaut : application/json |
| En-tête | Description |
|---|---|
| Aucun |
Codes d'état
Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été correctement traitée. |
| 403 | Interdit. L’utilisateur ne possède pas les droits d’accès à l’enregistrement spécifié. |
| 404 | Introuvable. L’élément demandé est introuvable. |
| 500 | Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur. |
Paramètres du corps de réponse (JSON ou XML)
| Nom | Description |
|---|---|
| characteristic | Sys_id de l’enregistrement de caractéristique d’autorisation associé. Situé dans la table Caractéristique [sn_prd_pm_characteristic]. Type de données : chaîne |
| characteristic_option | Sys_id de l’enregistrement d’options de caractéristiques associées. Situé dans la table Option de caractéristique [sn_prd_pm_characteristic_option]. Type de données : chaîne |
| entitlement_usage | Détails sur l’enregistrement d’utilisation d’autorisation associé à l’enregistrement de caractéristique d’autorisation spécifié. Type de données : tableau d’objets |
| entitlement_usage.entitlement_characteristic | Sys_id de l’enregistrement de caractéristique d’autorisation associé. Situé dans la table Caractéristique de l’autorisation [sn_pss_core_entitlement_characteristic]. Type de données : chaîne |
| entitlement_usage.period_end | Valeur du champ de fin de période dans l’enregistrement d’utilisation de l’autorisation. Cette valeur correspond à la date à laquelle le suivi d’utilisation prend fin pour cette autorisation. Type de données : chaîne |
| entitlement_usage.period_start | Valeur du champ de début de la période dans l’enregistrement d’utilisation de l’autorisation. Cette valeur correspond à la date à laquelle le suivi d’utilisation commence pour cette autorisation. Type de données : chaîne |
| entitlement_usage.sys_id | ID système de l’enregistrement d’utilisation de l’autorisation renvoyé. Situé dans la table Utilisations des autorisations [sn_pss_core_entitlement_usage]. Type de données : chaîne |
| entitlement_usage.total_units | Nombre total d’unités achetées. Situé dans le champ Nombre total d’unités dans l’enregistrement d’utilisation de l’autorisation. Type de données : chaîne |
| entitlement_usage.used_units | Nombre d’unités qui ont été utilisées. Situé dans le champ Unités utilisées dans l’enregistrement d’utilisation de l’autorisation. Type de données : chaîne |
| sys_id | ID système de l’enregistrement de la caractéristique de l’autorisation. Situé dans la table Caractéristique de l’autorisation [sn_pss_core_entitlement_characteristic]. Type de données : chaîne |
| type | Valeur du champ Type dans l’enregistrement de la caractéristique d’autorisation. Valeurs possibles :
Type de données : chaîne |
| valide | Couverture pour donner la caractéristique. Pour certaines caractéristiques, les couvertures sont définies dans la table Option de caractéristique. Toutefois, si aucune couverture n’est définie dans la table Option de caractéristique, vous pouvez transmettre les informations de couverture dans le value paramètre. Les options de la caractéristique ne sont définies que pour les types de caractéristiques suivants :
Par exemple, si la caractéristique est « Nombre de remplacements » et que ses couvertures ne sont pas définies dans la table des options de caractéristique, vous pouvez spécifier les couvertures, telles que « 10 », « 20 », dans ce paramètre. Remarque : Ce paramètre contient la valeur de couverture finale de la caractéristique. S’il existe des informations dans la table des options de caractéristique, elles sont propagées à ce paramètre. Type de données : chaîne |
Demande cURL
L’exemple de code suivant montre comment appeler ce point de terminaison en utilisant toutes ses valeurs par défaut.
curl "https://instance.servicenow.com/api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/3c817faa43823110341605ed0bb8f23a" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Résultats renvoyés :
{
"result": {
"sys_id": "3c817faa43823110341605ed0bb8f23a",
"characteristic": "b73177aa43823110341605ed0bb8f246",
"type": "coverage",
"characteristic_option": "ff617baa43823110341605ed0bb8f266",
"value": "Minor parts",
"entitlement_usage": [
{
"sys_id": "03e3224d51b23d10f877bf82d3ddf310",
"period_start": "2022-12-12",
"period_end": "2025-12-12",
"entitlement_characteristic": "3c817faa43823110341605ed0bb8f23a",
"total_units": "10",
"used_units": "5"
}
]
}
}Demande cURL
L’exemple de code suivant montre comment appeler ce point de terminaison et renvoyer toutes les valeurs d’affichage.
curl "https://instance.servicenow.com/api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/3c817faa43823110341605ed0bb8f23a?display_value=all" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Résultats renvoyés :
{
"result": {
"sys_id": {
"label": "Sys ID",
"value": "3c817faa43823110341605ed0bb8f23a",
"displayValue": "3c817faa43823110341605ed0bb8f23a",
"type": "GUID"
},
"characteristic": {
"name": "characteristic",
"label": "Characteristic",
"value": "b73177aa43823110341605ed0bb8f246",
"display_value": "Repair parts covered",
"type": "reference"
},
"type": {
"name": "type",
"label": "Type",
"value": "coverage",
"display_value": "Coverage",
"type": "string"
},
"characteristic_option": {
"name": "characteristic_option",
"label": "Characteristic option",
"value": "ff617baa43823110341605ed0bb8f266",
"display_value": "Minor parts",
"type": "reference"
},
"value": {
"name": "value",
"label": "Value",
"value": "Minor parts",
"display_value": "Minor parts",
"type": "string"
},
"entitlement_usage": [
{
"sys_id": {
"label": "Sys ID",
"value": "03e3224d51b23d10f877bf82d3ddf310",
"displayValue": "03e3224d51b23d10f877bf82d3ddf310",
"type": "GUID"
},
"period_start": {
"name": "period_start",
"label": "Period start",
"value": "2022-12-12",
"display_value": "2022-12-12",
"type": "glide_date"
},
"period_end": {
"name": "period_end",
"label": "Period end",
"value": "2025-12-12",
"display_value": "2025-12-12",
"type": "glide_date"
},
"entitlement_characteristic": {
"name": "entitlement_characteristic",
"label": "Entitlement characteristic",
"value": "3c817faa43823110341605ed0bb8f23a",
"display_value": "Repair parts covered",
"type": "reference"
},
"total_units": {
"name": "total_units",
"label": "Total units",
"value": "10",
"display_value": "10",
"type": "string"
},
"used_units": {
"name": "used_units",
"label": "Used units",
"value": "5",
"display_value": "5",
"type": "string"
}
}
]
}
}