REST APIs
REST (REpresentational State Transfer) est une architecture simple sans état qui fournit des normes entre les systèmes informatiques sur le Web, ce qui leur permet de communiquer plus facilement les uns avec les autres.
La Now Platform fournit diverses REST APIs qui sont actives par défaut. Ces API vous offrent la possibilité d'interagir avec diverses fonctionnalités ServiceNow au sein de votre application. Cette fonctionnalité permet, entre autres, d'effectuer des opérations de création, de lecture, de mise à jour et de suppression (CRUD) sur des tables existantes (API Table), mais aussi d'insérer des données dans une base de données MetricBase (API Base de données chronologiques MetricBase et bien d'autres), de récupérer des informations auprès de cette base de données et d'y exécuter des transformations.
Pour obtenir une liste des REST APIs disponibles, consultez la référence de REST API.
https://<instancename>.service-now.com/syslog_transaction_list.do?sysparm_query=sys_created_onONToday%40javascript%3Ags.beginningOfToday()%40javascript%3Ags.endOfToday()%5Etype%3Drest
Format de l'URI REST et paramètres disponibles
Les REST APIs ServiceNow suivent le protocole de REST API standard. Elles fournissent également des paramètres d'URI et de requête « personnalisés » pour garantir la rétrocompatibilité et fournir des fonctionnalités supplémentaires telles que la pagination de longues listes de résultats. Consultez les sections suivantes pour découvrir la fonctionnalité qui sous-tend ces paramètres personnalisés (tous facultatifs).
Gestion des versions des REST APIs
Les URI des REST APIs ServiceNow peuvent inclure un numéro de version, par exemple /api/now/v1/table/{tableName}. Les numéros de version identifient la version du point de terminaison à laquelle un URI accède. Pour vous assurer que les futures mises à jour des REST APIs n'ont pas d'impact négatif sur votre intégration, spécifiez un numéro de version dans vos URI.
Les URI sans numéro de version, tels que /api/now/table/{tableName}, utilisent le dernier point de terminaison REST qui correspond à la version de votre instance.
Méthodes de demande HTTP prises en charge
- GET
- DELETE
- CHEF
- PATCH
- POST
- PUT
Pour en savoir plus sur ces méthodes, consultez le document RFC-2616 Hypertext Transfer Protocol.
- Vous pouvez utiliser les méthodes HEAD au lieu des méthodes GET pour renvoyer une réponse sans corps de réponse.
- Vous ne pouvez pas transmettre plusieurs enregistrements dans les opérations POST, PUT et PATCH. Si vous le faites, seul le premier enregistrement est traité, les autres sont ignorés.
- Vous ne pouvez pas utiliser POST, PUT et PATCH pour insérer ou mettre à jour des enregistrements dans une vue de base de données, car les vues de bases de données sont en lecture seule.
En-têtes de format de données
Les REST APIs nécessitent les en-têtes de demande Accept et Content-Type pour assurer un formatage correct des données pour les demandes contenant un corps de demande ou un corps de réponse. Vous devez fournir les deux en-têtes pour les opérations POST, PUT, PATCH et DELETE. Les opérations GET et HEAD nécessitent uniquement l'en-tête Accept. Si vous ne fournissez pas les en-têtes requis, une erreur 400 Demande incorrecte est renvoyée.
Pour la plupart des REST APIs ServiceNow, ces en-têtes de demande prennent en charge les valeurs suivantes :
- Accepter : application/json, application/xml
- Type de contenu : application/json, application/xml
Pour obtenir la liste des valeurs spécifiques prises en charge par chaque point de terminaison, consultez la référence de REST API.
Autres en-têtes
Toutes les demandes peuvent contenir un en-tête d'authentification qui spécifie les informations d'identification de l'utilisateur à utiliser pour l'authentification.
Vous pouvez également remplacer les méthodes HTTP, telles que GET ou POST, en définissant l'en-tête X-http-method-override.
Gestion spécifique des données
Dans la section suivante, nous vous présentons certaines des nuances de gestion des données au sein de la REST API.
- Mode d'effacement d'un champ de données : à l'exception des champs de sélection, vous pouvez transmettre une valeur vide dans le paramètre pour effacer la valeur dans la base de données. Par exemple, l'envoi de
{"short description":""}efface le champ short_description de l'enregistrement spécifié. - Mode de gestion des champs de devise : les valeurs de devise renvoyées sont converties en devise locale conformément aux paramètres régionaux de l'utilisateur. Lors de l'insertion de données, aucune conversion n'est effectuée. Ce comportement s'applique aux champs de types
CurrencyouPrice.Par exemple, si un utilisateur doté de paramètres régionaux du Royaume-Uni interroge des enregistrements avec des valeurs de devise en USD, les valeurs renvoyées sont converties en GBP. Toutefois, si cet utilisateur ajoute un nouvel enregistrement dont la valeur du champ de devise est en GBP, la valeur est stockée en GBP sans être convertie en USD. Cette valeur GBP apparaît en USD si un utilisateur interroge l'enregistrement correspondant dans les paramètres régionaux des États-Unis.
- Affichage des données de l'interface utilisateur par rapport aux valeurs transmises dans un point de terminaison REST : l'interface utilisateur indique la valeur d'affichage de la base de données, c'est-à-dire des données manipulées. Par défaut, un point de terminaison REST insère et met à jour les valeurs réelles, qui peuvent différer de la valeur d'affichage. Vous pouvez forcer un point de terminaison REST à traiter les valeurs transmises en tant que valeurs d'affichage en définissant le paramètre sysparm_input_display_value sur true.
Paramètres de requête personnalisés
Les REST APIs ServiceNow utilisent les paramètres de requête suivants sur de nombreuses API disponibles, en vue de garantir un comportement cohérent entre les API. Utilisez ces paramètres pour paginer des jeux d'enregistrements volumineux, filtrer les résultats et restreindre le nombre d'enregistrements renvoyés dans une seule requête.
| sysparm_limit | 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. Cette limite est appliquée avant l'évaluation de l'ACL. Si aucun enregistrement n'est renvoyé (notamment ceux auxquels vous avez accès), réorganisez l'ordre des enregistrements pour que ceux auxquels vous avez accès soient renvoyés en premier. Remarque : Des valeurs sysparm_limit anormalement élevées peuvent avoir un impact sur les performances du système. Type de données : nombre Par défaut : 10 000 |
| sysparm_fields | Liste des champs séparés par des virgules à envoyer dans la réponse. Type de données : chaîne |
| sysparm_input_display_value | Marqueur indiquant si les valeurs de champ doivent être définies à l'aide de la valeur d'affichage ou de la valeur réelle. Selon les différents types de champs, le point de terminaison peut manipuler les valeurs d'affichage transmises pour stocker les valeurs appropriées dans la base de données. Par exemple, si vous envoyez le nom d'affichage pour un champ de référence, le point de terminaison stocke le sys_id pour cette valeur dans la base de données. Pour les champs de date et d'heure, lorsque ce paramètre est défini sur true, la valeur de date et d'heure est ajustée pour le fuseau horaire de l'utilisateur actuel. Lorsque la valeur est définie sur false, la valeur de date et d’heure est insérée à l’aide du fuseau horaire GMT. Valeurs valides :
Type de données : booléennes Valeur par défaut : false. Cela correspond au type de données renvoyé lors de la récupération des données (méthodes GET), c'est-à-dire les valeurs réelles. Remarque : Pour définir la valeur d'un champ chiffré, définissez ce paramètre sur true. Sinon, les valeurs soumises aux champs chiffrés ne sont pas enregistrées. En outre, l'utilisateur à l'origine de la demande doit disposer du contexte de chiffrement approprié avant de soumettre la demande. Les champs chiffrés sont masqués pour les utilisateurs qui ne disposent pas du contexte de chiffrement approprié. Pour plus d’informations sur le chiffrement de champ, reportez-vous à la section Column Level Encryption. |
| sysparm_offset | 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 Type de données : nombre Par défaut : 0 |
| sysparm_query | Requête codée utilisée pour filtrer l’ensemble de résultats. Vous pouvez utiliser un filtre d'interface utilisateur pour obtenir une requête codée correctement. Syntaxe : sysparm_query=<col_name><operator><value>.
Tous les paramètres sont sensibles à la casse. Les requêtes peuvent contenir plusieurs entrées, telles que sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>]. Par exemple :
Les requêtes codées prennent également en charge le classement par fonctionnalité. Pour trier les réponses en fonction de certains champs, utilisez les clauses Syntaxe :
Par exemple : Cette requête filtre tous les enregistrements actifs et classe les résultats par ordre croissant, par nombre, puis dans l'ordre décroissant des catégories. Si une partie de la requête n'est pas valide (par exemple, un nom de champ non valide a été spécifié), l'instance ignore la partie non valide. Puis, elle renvoie les lignes en utilisant uniquement la partie valide de la requête. Vous pouvez contrôler ce comportement à l'aide de la propriété glide.invalid_query.returns_no_rows. Définissez cette propriété sur true pour ne renvoyer aucune ligne dans une requête non valide. Remarque : La propriété glide.invalid_query.returns_no_rows contrôle le comportement de toutes les requêtes dans l'instance, par exemple dans les listes, les scripts (GlideRecord.query()) et les API de service Web. Type de données : chaîne |
| sysparm_view | Vue de l'interface utilisateur pour laquelle afficher les données. Détermine les champs renvoyés dans la réponse. Valeurs valides :
Si vous spécifiez également le paramètre sysparm_fields, il est prioritaire. Type de données : chaîne |
Remontée pas à pas dans les demandes de REST APIs
Vous pouvez utiliser la remontée pas à pas lorsque vous spécifiez les paramètres sysparm_query ou sysparm_fields dans les demandes aux REST APIs qui prennent en charge ces paramètres.
Remontée pas à pas dans sysparm_query
Vous pouvez filtrer les requêtes à l'aide des valeurs d'enregistrement connexes par remontée pas à pas dans le paramètre sysparm_query. Par exemple, vous pouvez récupérer tous les enregistrements d'incident dont l'incident Société a une valeur de Code mnémonique spécifique.
https://<instance>.service-now.com/api/now/table/incident?sysparm_query=company.stock_symbol=NYX
Remontée pas à pas dans sysparm_fields
Vous pouvez afficher les valeurs de champs de plusieurs tables en effectuant une remontée pas à pas dans le paramètre sysparm_fields. Par exemple, vous pouvez récupérer le nom, le Sys_id et le service de chaque utilisateur qui dispose de certains rôles, ainsi que le nom du rôle.
La demande s'exécute sur la table Rôles d'utilisateur [sys_user_has_role] qui définit une relation plusieurs à plusieurs entre les utilisateurs et les rôles. La réponse inclut les valeurs de champs des tables Utilisateur [sys_user] et Rôles [sys_user_role].
https://<instance>.service-now.com/api/now/table/sys_user_has_role?sysparm_fields=role%2Crole.name%2Cuser%2Cuser.name%2Cuser.sys_id%2Cuser.department&sysparm_query=role%3D3d43716d0f6002003a2d47bce1050e0d%5EORrole%3Dac73b52d0f6002003a2d47bce1050eec&sysparm_display_value=true
{
"result": [
{
"user.name": "Fred Johnson",
"user.sys_id": "f5a3716d0f6002003a2d47bce1050ed4",
"role.name": "support",
"user.department": {
"display_value": "Accounting",
"link": "https://<instance>.service-now.com/api/now/table/cmn_department/5b3b13530f58c2003a2d47bce1050e96"
},
"role": {
"display_value": "support",
"link": "https://<instance>.service-now.com/api/now/table/sys_user_role/3d43716d0f6002003a2d47bce1050e0d"
},
"user": {
"display_value": "Fred Johnson",
"link": "https://<instance>.service-now.com/api/now/table/sys_user/f5a3716d0f6002003a2d47bce1050ed4"
}
},
{
"user.name": "Fred Johnson",
"user.sys_id": "f5a3716d0f6002003a2d47bce1050ed4",
"role.name": "asset_mgmt",
"user.department": {
"display_value": "Accounting",
"link": "https://<instance>.service-now.com/api/now/table/cmn_department/5b3b13530f58c2003a2d47bce1050e96"
},
"role": {
"display_value": "asset_mgmt",
"link": "https://<instance>.service-now.com/api/now/table/sys_user_role/ac73b52d0f6002003a2d47bce1050eec"
},
"user": {
"display_value": "Fred Johnson",
"link": "https://<instance>.service-now.com/api/now/table/sys_user/f5a3716d0f6002003a2d47bce1050ed4"
}
}
]
}Codes de réponse HTTP des REST APIs
Les appels effectués aux points de terminaison REST renvoient des codes de réponse HTTP. Vous pouvez utiliser ces codes de réponse pour vérifier que la REST API s'exécute correctement. Si ce n'est pas le cas, le point de terminaison renvoie un code de réponse d'erreur. Utilisez les informations contenues dans la réponse d'erreur pour résoudre les problèmes relatifs au format de votre appel. Pour obtenir la liste des codes de réponse standard qu'un point de terminaison peut renvoyer, consultez la rubrique Codes de réponse HTTP des REST APIs. Pour connaître la liste des codes de réponse renvoyés par une REST API ServiceNow spécifique, consultez la référence de REST API.
Sécurité des REST APIs
Par défaut, les REST APIs ServiceNow utilisent l'authentification de base ou OAuth pour autoriser l'accès des utilisateurs aux API/points de terminaison REST. Vous pouvez également configurer votre instance pour utiliser l'authentification multifacteur pour accéder aux REST APIs.
L'ID d'utilisateur que vous spécifiez dans un appel de point de terminaison REST est soumis au contrôle d'accès de la même manière qu'un utilisateur interactif. Chaque demande nécessite les informations d'authentification appropriées, telles que le nom d'utilisateur et le mot de passe. Assurez-vous que chaque demande de point de terminaison comprend un en-tête d'autorisation avec les informations d'identification suffisantes pour accéder au point de terminaison.
Les REST APIs ServiceNow prennent également en charge les cookies qui permettent la liaison à la session existante.
Pour utiliser le certificat permettant d'appeler l'API et les informations sur l'authentification réciproque, consultez la rubrique Authentification basée sur certificat.
Les politiques d'accès aux REST APIs avec les critères de filtre tels que l'adresse IP, le rôle, le groupe et la restriction du champ d'application de l'API, vous permettent d'utiliser le REST API Auth Scope. Pour en savoir plus sur la politique d'accès des REST APIs, consultez la rubrique Politiques d'accès des REST APIs.
Vous pouvez créer une seule politique pour bloquer la demande entrante, à un niveau global de la REST API, à l'aide de la politique d'accès des REST APIs d'un réseau externe approuvé et à un niveau d'authentification REST de base.
Rôles des REST APIs
Outre l'authentification utilisateur, chaque point de terminaison REST peut avoir des exigences différentes en fonction des rôles requis pour accéder au point de terminaison. Certains nécessitent le rôle d'administrateur, d'autres des rôles propres à l'API. Les exigences des rôles sont spécifiées dans la liste de contrôle d'accès (ACL) associée à la REST API/au point de terminaison. Pour obtenir des détails sur les rôles valides pour chaque REST API/point de terminaison, consultez la référence de REST API ou recherchez l'ACL associée à l'API/au point de terminaison dans une instance via System Security > Contrôle d'accès (ACL).
Listes de contrôle d'accès des REST APIs
Les ACL des REST APIs définissent divers critères, notamment les rôles nécessaires et les conditions qu'un utilisateur doit remplir pour accéder à une REST API ou à un point de terminaison ServiceNow. Il est possible de définir une seule ACL pour l'ensemble d'une REST API, comme les ACL de l'API de table et de l'API de pièce jointe, ou pour un point de terminaison individuel, comme l'ACL clotho_rest_put qui s'applique uniquement aux méthodes PUT MetricBase.
Les ACL des REST APIs ServiceNow suivantes sont disponibles dans le système de base, mais sont désactivées par défaut. Toutes les autres ACL des REST APIs ServiceNow sont actives par défaut.
- API de table
- API d'agrégat
- API de jeu d'importation
- API de pièce jointe
Pour en savoir plus sur les ACL, consultez la rubrique Règles relatives aux listes de contrôle d'accès.
Accéder à la REST API de table
Par défaut, toutes les tables, y compris les tables système de base, les tables globales et les tables incluses dans le champ d'application, sont accessibles via des services Web. Vous devez répondre à toutes les exigences de sécurité des services Web, telles que l'authentification de base et les ACL pour accéder aux tables via des services Web. Les champs pour lesquels l'entité appelante n'a pas de droits en raison des ACL ne sont pas renvoyés dans une réponse de requête REST.
Pour autoriser l'accès aux tables sans aucune authentification ni autorisation, ajoutez le nom de la table à la table Pages publiques [sys_public] avec l'état Actif. L'interface REST applique systématiquement toutes les ACL définies sur les tables associées. Si l’application des ACL n’est pas le comportement souhaité, vous devez désactiver les ACL sur les tables. Toutefois, il n’est pas suggéré de rendre vos API publiques, car cela permet au public d’accéder à la mise à jour des données dans l’instance.
Vous pouvez également contrôler l'accès du service Web direct aux tables à l'aide de la case à cocher Autoriser l'interaction de services Web dans les paramètres d'accès à l'application de table. Vous devez cocher cette case pour activer l'interaction des services Web avec la table.
Authentification multifacteur pour les demandes REST entrantes
Lorsque l'authentification multifacteur est activée pour un compte d'utilisateur, vous devez soumettre un jeton MFA avec des informations d'authentification de base lors de la création de demandes REST en tant qu'utilisateur.
Pour envoyer un jeton MFA avec une demande REST, ajoutez le jeton à la fin du mot de passe de l'utilisateur dans la chaîne nom d'utilisateur:mot de passe d'authentification de base, telle que joe.employee:password62161147. Codez la chaîne complète, y compris le jeton MFA, à l'aide du codage en base 64, puis envoyez la chaîne codée dans l'en-tête Autorisation.
Réponses des demandes REST d'authentification multifacteur
La réponse à une demande d'authentification MFA varie en fonction de la validité des informations d'identification et du jeton MFA fournis.
| Résultat | Description |
|---|---|
| Les identifiants d'authentification de base et le jeton MFA sont valides | L'utilisateur est authentifié et la session est créée. La demande est traitée normalement. |
| Les informations d'identification de base sont valides, mais le jeton MFA n'est pas valide ou est manquant | La réponse renvoie l'erreur 401. La réponse inclut l'en-tête X-MFA_TOKEN dont la valeur est non valide. |
| Les informations d'identification de base ne sont pas valides | La réponse renvoie l'erreur 401. L'en-tête X-MFA_TOKEN n'est pas inclus dans la réponse. |
Support CORS des REST APIs
La REST API prend en charge la sécurité du partage des ressources interorigines (CORS). Le support CORS vous permet de définir les domaines pouvant accéder à chaque REST API. En définissant une règle CORS pour un domaine, vous pouvez autoriser les demandes interorigines de ce domaine. Il est impossible d'effectuer des demandes interorigines à partir de domaines sans règle CORS.
Vous pouvez configurer CORS pour limiter l'accès à certains points de terminaison/API, méthodes HTTP et en-têtes d'autres domaines. Par exemple, vous pouvez limiter les demandes à l'API de table à partir d'un domaine spécifique pour autoriser uniquement les opérations GET.
Pour afficher les règles CORS définies sur votre instance, accédez à .
Vous pouvez désactiver le support CORS pour une instance en définissant la propriété glide.rest.cors.enabled sur false. Si la valeur est définie sur false, aucune évaluation CORS n'est effectuée sur les demandes REST entrantes. Cette propriété est par défaut définie sur true.
Explorateur d'API REST
L'explorateur d'API REST est un outil ServiceNow qui utilise les informations de votre instance pour fournir une liste de points de terminaison, de méthodes et de variables, que vous pouvez utiliser pour créer et envoyer des demandes REST.
Après avoir créé la demande, l'explorateur d'API REST fournit des exemples de code dans plusieurs langages de programmation afin que vous puissiez les utiliser pour lancer la demande, ainsi que des informations détaillées sur la demande et la réponse.
Pour accéder à l’Explorateur d’API REST, dans votre instance, naviguez vers . Vous devez disposer du rôle rest_api_explorer pour accéder à l'explorateur d'API REST. Pour en savoir plus, consultez la rubrique Utiliser l'explorateur d'API REST.
Prise en charge d'Automated Test Framework
Automated Test Framework (ATF) prend en charge les étapes de test des REST APIs entrantes. Vous pouvez créer des tests automatisés pour les REST APIs entrantes personnalisées que vous créez. La création de tests pour vos REST APIs personnalisées simplifie les tests de mise à niveau et permet de vérifier la rétrocompatibilité des modifications apportées à une REST API.
Exemple d'applications client REST
Plusieurs exemples d'applications client REST et de code source sont disponibles pour démontrer les intégrations à l'aide des services Web REST. Les exemples d'applications client REST montrent comment utiliser la REST API ServiceNow avec une application externe, notamment une application NodeJS ou iOS.
Les exemples sont Open Source et disponibles pour la communauté. Vous pouvez utiliser ces exemples d'applications pour vous familiariser avec la fonctionnalité REST, ou les utiliser comme point de départ pour créer vos propres applications clientes REST.
Les utilisateurs disposant du rôle rest_api_explorer peuvent accéder à la liste des applications clientes disponibles en naviguant vers .
Lors de l'affichage de la liste d'applications, cliquez sur une application pour afficher le code source et la documentation supplémentaire hébergée sur GitHub.
Formation pour les développeurs
Sur le ServiceNow® Site Developer, vous pouvez accéder aux formations Intégrations REST entrantes et Intégrations REST sortantes.
Informations supplémentaires
Les autres sections de la rubrique REST API contiennent des procédures détaillées sur des implémentations spécifiques à l'aide de la REST API ServiceNow et fournissent des informations de référence qui décrivent divers éléments de données utilisés par la REST API ServiceNow.