fournit ServiceNow AI Platform diverses API REST, qui sont actives par défaut. Ces API offrent la possibilité d’interagir avec diverses ServiceNow fonctionnalités de votre application. Ces fonctionnalités incluent la possibilité d’effectuer des opérations créer, lire, mettre à jour et supprimer (CRUD) sur des tables existantes (API de table ), d’insérer des données, de récupérer des informations et d’exécuter des transformations sur une base de données MetricBase (API de séries chronologiques MetricBase , et bien d’autres).

Pour obtenir la liste des API REST disponibles, consultez la référence des API REST.

Format URI REST et paramètres disponibles

ServiceNow Les API REST suivent le protocole API REST standard. Ils fournissent également des paramètres d’URI et de requête « personnalisés » pour assurer la rétrocompatibilité et fournir des fonctionnalités supplémentaires telles que la pagination de longues listes de résultats. Les sections suivantes décrivent la fonctionnalité derrière ces paramètres personnalisés, qui sont tous facultatifs.

Gestion des versions d’API REST

ServiceNow Les URI d’API REST peuvent inclure un numéro de version, tel que /api/now/v1/table/{tableName}. Les numéros de version identifient la version du point de terminaison à laquelle un URI accède. En spécifiant un numéro de version dans vos URI, vous pouvez vous assurer que les futures mises à jour de REST API n’ont pas d’impact négatif sur votre intégration.

Les URI qui ne spécifient pas de numéro de version dans l’URI, tel que /api/now/table/{tableName}, utilisent le dernier point de terminaison REST pour votre version d’instance.

Méthodes de demande HTTP prises en charge

Pour plus de détails sur ces méthodes, reportez-vous au document RFC-2616 Hypertext Transfer Protocol .

En-têtes du format de données

Les API REST requièrent les en-têtes de demande and Content-Type pour une Accept mise en forme correcte des données pour les demandes qui contiennent un corps de demande ou de réponse. Les opérations POST, PUT, PATCH et DELETE nécessitent que vous fournissiez les deux en-têtes. Les opérations GET et HEAD ne nécessitent que l’en-tête Accept . Si vous ne fournissez pas les en-têtes requis, vous obtenez une erreur 400 Bad Request .

Pour la plupart ServiceNow des API REST, 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 l’API REST.

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éciale des données

La section suivante décrit certaines des nuances de gestion des données dans l’API REST.

• Comment effacer un champ de données : à l’exception des champs de choix, vous pouvez passer 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 short_description champ de l’enregistrement spécifié.
• Comment les champs de devise sont gérés : les valeurs de devise renvoyées sont converties dans la devise locale en fonction des 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 des types Devise ou Prix.

  Par exemple, si un utilisateur au Royaume-Uni interroge des enregistrements avec des valeurs monétaires en USD, les valeurs renvoyées sont converties en GBP. Toutefois, si cet utilisateur ajoute un nouvel enregistrement avec la valeur du champ de devise en GBP, la valeur est stockée en GBP sans être convertie en USD. Cette valeur GBP apparaît en USD si elle est interrogée par un utilisateur 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 affiche la valeur d’affichage de la base de données, qui est des données manipulées. Par défaut, un point de terminaison REST insère et met à jour les valeurs réelles, qui peuvent être différentes de la valeur d’affichage. Vous pouvez forcer un point de terminaison REST à traiter les valeurs transmises comme des valeurs d’affichage en définissant le paramètre de demande de sysparm_input_display_value sur vrai.

Paramètres de requêtes personnalisées

Les ServiceNow API REST utilisent les paramètres de requête suivants sur la plupart des API disponibles, fournissant un comportement cohérent entre les API. Utilisez ces paramètres pour paginer les jeux d’enregistrements volumineux, filtrer les résultats et limiter le nombre d’enregistrements renvoyés en une seule requête.

Remontée pas à pas dans les demandes REST API

Vous pouvez utiliser la remontée pas à pas lors de la spécification des sysparm_query paramètres ou sysparm_fields dans les demandes adressées aux API REST qui prennent en charge ces paramètres.

Remontée pas à pas dans sysparm_query

Vous pouvez filtrer les requêtes à l’aide de valeurs d’enregistrement connexes en remontée pas à pas dans le sysparm_query paramètre. Par exemple, vous pouvez récupérer tous les enregistrements d’incidents où la société de l’incident a une valeur de symbole boursier 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 champ de plusieurs tables en remontée pas à pas dans le sysparm_fields paramètre. Par exemple, vous pouvez récupérer le nom, le Sys_id et le département de chaque utilisateur disposant de certains rôles, ainsi que le nom du rôle.

La demande s’exécute sur la table User Roles (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 champ 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 de l’API REST

Les appels passés aux points de terminaison REST renvoient des codes de réponse HTTP. Vous pouvez utiliser ces codes de réponse pour vous assurer que l’API REST 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 à l’erreur pour résoudre les problèmes liés à votre format d’appel. Pour obtenir la liste des codes de réponse standard qu’un point de terminaison peut renvoyer, reportez-vous à la section Codes de réponse HTTP de l’API REST. Pour obtenir la liste des codes de réponse renvoyés par une API REST spécifique ServiceNow , consultez la référence de l’API REST.

Sécurité de REST API

Par défaut, ServiceNow les API REST utilisent l’authentification de base ou OAuth pour autoriser l’accès de l’utilisateur aux API/points de terminaison REST. Vous pouvez également configurer votre instance pour qu’elle utilise l’authentification multifacteur afin d’accéder aux API REST.

L’ID 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 inclut un en-tête d’autorisation avec des informations d’identification suffisantes pour accéder au point de terminaison.

ServiceNow Les API REST prennent également en charge les cookies qui permettent la liaison à la session existante.

Pour utiliser le certificat pour appeler l’API et des informations sur l’authentification réciproque, consultez Authentification basée sur certificat.

Politiques d’accès API REST avec des critères de filtrage tels que l’adresse IP, le rôle, le groupe et la restriction du périmètre de l’API, vous pouvez utiliser le REST API Auth Scope. Pour en savoir plus sur la politique d’accès API REST, consultez Politiques d’accès API REST.

Vous pouvez élaborer une seule politique pour bloquer la demande entrante, au niveau global de l’API REST à l’aide de la politique d’accès REST API provenant d’un réseau de confiance externe et à des niveaux d’authentification REST de base.

Rôles d’API REST

Outre l’authentification utilisateur, chaque point de terminaison REST peut avoir des exigences différentes pour les rôles requis pour accéder au point de terminaison. Certains nécessitent le rôle admin et d’autres nécessitent des rôles spécifiques à l’API. Les exigences de rôle sont spécifiées dans la liste de contrôle d’accès (ACL) associée à l’API/point de terminaison REST. Pour plus de détails sur les rôles valides pour chaque API/point de terminaison REST, consultez la référence de l’API REST ou localisez l’ACL associée pour l’API/le point de terminaison au sein d’une instance via la sécurité de système > le contrôle d’accès (ACL).

ACL REST API

Les ACL d’API REST définissent des critères, tels que les rôles requis et les conditions qu’un utilisateur doit remplir pour accéder à une API REST ou à un ServiceNow point de terminaison. Une seule ACL peut être définie pour l’ensemble d’une API REST, telle que l’API de table et les ACL d’API d’attachement, ou pour un point de terminaison individuel, tel que l’ACL clotho_rest_put, qui ne s’applique qu’aux MetricBase méthodes PUT.

Les ACL d’API REST suivantes ServiceNow sont disponibles dans le système de base, mais sont désactivées par défaut. Toutes les autres ACL d’API ServiceNow REST sont actives par défaut.

• Table API
• API d’agrégat
• API de jeu d’importation
• API de pièce jointe

Pour plus d’informations sur les ACL, consultez Règles de liste de contrôle d’accès.

Accès aux tables de l’API REST

Par défaut, toutes les tables, y compris les tables système de base, les tables globales et les tables dans le champ d’application, sont accessibles via les services Web. Vous devez répondre à tous les besoins de sécurité des services Web, tels 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 retourné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 toujours 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 recommandé 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 direct au service Web aux tables à l’aide de la case à cocher Autoriser l’accès à cette table via des services Web dans les paramètres d’accès à l’application de table. Vous devez cocher cette case pour activer l’interaction du service Web avec la table.

Authentification multifacteur pour le REST entrant

À partir de la version Yokohama, l’authentification multifacteur (MFA) n’est pas requise par défaut pour l’authentification API REST à l’aide de l’authentification de base. Pour en savoir plus, consultez cet article de la base de connaissances.

Réponses 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.

API REST Prise en charge de CORS

L’API REST prend en charge la sécurité CORS (Cross-Origin Resource Sharing). La prise en charge CORS vous permet de définir les domaines pouvant accéder à chaque API REST. En définissant une règle CORS pour un domaine, vous pouvez autoriser les demandes d’origines croisées provenant de ce domaine. Les demandes d’origines croisées ne peuvent pas être effectuées à partir de domaines sans règle CORS.

Vous pouvez configurer CORS pour autoriser l’accès uniquement à certaines API/points de terminaison, 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 à Services web système > Règles CORS.

Vous pouvez désactiver la prise en charge CORS pour une instance en définissant la glide.rest.cors.enabled propriété sur faux. Si la valeur est définie sur faux, aucune évaluation CORS n’est effectuée sur les demandes REST entrantes. Cette propriété est vraie par défaut.

Explorateur d'API REST

L’Explorateur d’API REST est un ServiceNow outil 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.

Une fois la demande créée, l’explorateur d’API REST fournit des exemples de code dans plusieurs langages de programmation que vous pouvez 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, accédez à votre instance. Services web système > Explorateur d'API REST. Vous devez disposer du rôle rest_api_explorer pour accéder à l’explorateur d’API REST. Pour plus d’informations, consultez Utiliser l’explorateur d’API REST.

Support de Framework de tests automatisés

Framework de tests automatisés (ATF) prend en charge les étapes de test REST entrantes. Vous pouvez créer des tests automatisés pour les API REST entrantes personnalisées que vous créez. La création de tests pour vos API REST personnalisées simplifie les tests de mise à niveau et permet de vérifier que les modifications apportées à une API REST sont rétrocompatibles.

Exemple d’applications clientes REST

Plusieurs exemples d’applications clientes REST et de code source sont disponibles pour illustrer les intégrations à l’aide des services Web REST. Les exemples d’applications clientes REST montrent comment utiliser l’API ServiceNow REST avec une application externe, telle qu’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 accédant à Services web système > REST > Exemples d’applications client.

Lors de l’affichage de la liste des applications, cliquez sur une application pour afficher le code source et la documentation supplémentaire hébergés sur GitHub.

Formation pour les développeurs

ServiceNow® Site Developer Le , vous pouvez obtenir une formation sur les intégrations REST entrantes et sortantes.

Information supplémentaire

Le reste de la section API REST contient des rubriques « comment faire » qui décrivent des implémentations spécifiques à l’aide de l’API ServiceNow REST et fournit des informations de référence décrivant divers éléments de données utilisés par l’API ServiceNow REST.