API REST basées sur un script

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 2024
  • 6 minutes de lecture

    • La fonctionnalité d’API REST scriptée permet aux développeurs d’applications de créer des API de service Web personnalisées.

    Vous pouvez définir des points de terminaison de service, des paramètres de requête et des en-têtes pour une API REST scriptée, ainsi que des scripts pour gérer la demande et la réponse.

    Les API REST basées sur un script suivent généralement l’architecture REST, mais vous pouvez les personnaliser pour utiliser différentes conventions. Vous définissez des API REST scriptées à l’aide du formulaire Service REST scripté disponible sous Services Web scriptés → API REST scriptées.

    Figure 1. Formulaire Service REST scripté
    Formulaire Service REST scripté
    Les vidéos suivantes offrent des informations supplémentaires sur les API REST scriptées :

    URI d’API REST scriptés

    Les URI Scripted REST API ont le format suivant :

    https://<instance.service-now.com>/api/<name_space>/<version>/<api_id>/<relative_path>

    Dans cet URI :
    • <instance.service-now.com>: chemin d’accès à l’instance ServiceNow où les utilisateurs accèdent à l’API REST scriptée.
    • <name_space>: pour les services Web dans le champ d’application global, l’espace de noms est la valeur de la propriété glide.appcreator.company.code. Pour les services Web d’une application incluse dans le périmètre, l’espace de noms est le nom du périmètre, tel que x_company_appname. Pour plus d’informations sur les espaces de noms, voir Périmètre de l’application.
    • <version>:Optionnel. Version du point de terminaison à accéder si l’API utilise la gestion des versions, telle que v1. Vous pouvez accéder à la version par défaut d’une API avec version en spécifiant l’URI sans numéro de version.
    • <api_id>: valeur du champ ID API sur le formulaire Service REST scripté. Par défaut, cette valeur est basée sur le nom du service.
    • <relative_path>: chemin d’accès relatif défini pour la ressource dans le formulaire Service REST scripté. Spécifier un chemin d’accès de ressource relative vous permet d’avoir plusieurs ressources utilisant la même méthode HTTP, telle que GET, dans un seul service Web. Par exemple, une ressource peut spécifier le chemin /{id} lorsque le service Web n’a qu’une seule ressource GET, ou /user/{id} et /message/{id} lorsque le service Web dispose de ressources différentes pour demander des enregistrements d’utilisateur et de message.

    Gestion des versions scriptées de l’API REST

    Les URI scriptés de REST API peuvent inclure un numéro de version, tel que /api/management/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 tester et déployer les changements sans impact sur les intégrations existantes.

    Version d’API par défaut

    Une version peut être marquée comme valeur par défaut. Spécifier une version par défaut permet aux utilisateurs d’accéder à cette version à l’aide d’un point de terminaison REST scripté sans numéro de version. Si aucune version n’est marquée comme valeur par défaut, la version la plus récente est utilisée comme version par défaut.

    Ressources de l’API REST scriptée

    Une ressource d’API REST scriptée est équivalente à un point de terminaison REST. Elle définit la méthode HTTP à exécuter, le script de traitement et tous les paramètres de remplacement de l’API parente. Vous pouvez définir une ou plusieurs ressources par API.

    Paramètres de requêtes de l’API REST scriptés

    Les paramètres de requête définissent les valeurs que les utilisateurs demandeurs peuvent transmettre dans une demande. Lors de la création d’une Scripted REST API, vous pouvez spécifier les paramètres disponibles et obligatoires pour chaque demande. Vous pouvez également associer un paramètre de requête à plusieurs ressources.

    Accédez aux paramètres de demande dans les scripts à l’aide du champ queryParams de l’objet de demande.

    Rôles Scripted REST API

    Pour utiliser des API REST scriptées, vous devez disposer du rôle administrateur de service Web [web_service_admin]. Les utilisateurs disposant de ce rôle peuvent lire, créer, modifier et supprimer des API REST scriptées et des ressources de service Web.
    Remarque :
    Ces rôles ne sont pas nécessaires pour accéder à un point de terminaison d’API REST scripté.

    Formats de demande et de réponse

    Par défaut, toutes les ressources d'une API prennent en charge les formats de demande et de réponse suivants : application/json, application/xml et texte/xml. Vous pouvez remplacer les formats par défaut au niveau de l’API. Les nouveaux formats s’appliquent à toutes les ressources appartenant à l’API, sauf si une ressource individuelle remplace les valeurs par défaut.

    Sécurité scriptée de l’API REST

    Vous pouvez configurer vos API REST scriptées avec le niveau de sécurité nécessaire. Des API/points de terminaison publics qui ne nécessitent aucune sécurité aux API/points de terminaison hautement sécurisés qui nécessitent une authentification de l’utilisateur avec un contrôle d’accès strict à toutes les ressources.

    Utilisez la fonctionnalité de politique d’accès API pour contrôler la méthode d’authentification des API. Pour plus d'informations, consultez API access policy.

    Contrôles d’accès scriptés de l’API REST

    Les listes de contrôle d’accès (ACL) définissent divers critères, tels que les rôles nécessaires et les conditions qu’un utilisateur doit remplir pour accéder à une API REST scriptée ou à un point de terminaison. Un utilisateur demandeur doit satisfaire au moins une des ACL. Il n’est pas nécessaire de satisfaire toutes les ACL sélectionnées. Vous pouvez définir une seule ACL pour l’ensemble d’une REST API ou pour un point de terminaison individuel.

    Remarque :
    Par défaut, les API REST basées sur un script contiennent une ACL qui interdit aux utilisateurs disposant du rôle snc_external de faire des demandes à l’API.

    Lors de la définition d’une ACL d’API REST scriptée, la valeur Type doit être REST_Endpoint.

    Pour plus d’informations sur les ACL, reportez-vous aux rubriques Règles relatives aux listes de contrôle d’accès et Configurer une ressource d’API REST scriptée pour exiger une ACL.

    Matrice de sécurité Scripted REST API

    Plusieurs configurations de sécurité sont possibles pour les API REST scriptées. Utilisez cette table pour identifier la configuration scriptée de sécurité des REST API qui correspond le mieux à vos besoins, ainsi que les valeurs de champ pour implémenter cette configuration.

    Tableau 1. Sécurité scriptée de l’API REST
    Configuration API REST scriptée Ressource REST scriptée
    ACL par défaut Requiert une authentification Requiert une autorisation d'ACL ACL
    La ressource est publique. Aucune authentification ou ACL n’est requise. N’importe quelle valeur Faux N’importe quelle valeur N’importe quelle valeur
    La ressource nécessite une authentification de base uniquement. Aucune ACL n’est requise. N’importe quelle valeur Vrai Faux N’importe quelle valeur
    La ressource nécessite une authentification de base uniquement. ACL est requis. Aucune ACL sélectionnée Vrai Vrai Aucune ACL sélectionnée
    Une ACL sélectionnée dans l’enregistrement de ressource est requise. N’importe quelle valeur Vrai Vrai Une ou plusieurs ACL sélectionnées
    Un ACL sélectionné dans l’enregistrement de l’API REST scripté est requis. Une ou plusieurs ACL sélectionnées Vrai Vrai Aucune ACL sélectionnée

    Objets d’erreur de l’API REST scriptée

    Les Scripted REST APIs incluent des objets d’erreur qui vous permettent de répondre à une demande avec un message d’erreur HTTP standard lorsqu’une erreur se produit pendant le traitement de la demande. Vous pouvez utiliser des objets d’erreur dans les ressources scriptées de l’API REST pour alerter les clients demandeurs de leurs erreurs. Utilisez des objets d’erreur pour répondre aux demandes entrantes, et non pour intercepter les erreurs dans votre code côté serveur.

    Format de réponse d’erreur

    Le type de contenu de la réponse dépend de l’en-tête Accepter la demande. Si l’en-tête Accepter spécifie un format non pris en charge, tel que image/jpeg, la réponse d’erreur utilise JSON.

    Les réponses d’erreur suivent le format suivant :
    {
  "error": {
    "message": "My error message",
    "detail": "My details"  
  },  
  "status": "failure"
}
    Le code d’état numérique, tel que 404, est inclus dans l’en-tête du code d’état de la réponse, et non dans le corps de la réponse.

    Prise en charge d'Automated Test Framework

    Automated Test Framework (ATF) prend en charge les étapes de test des REST 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. Reportez-vous aux sections Administration des configurations d’étapes de test REST et des configurations d’étapes de test REST ATF.

    Formation pour les développeurs

    Dans la , vous pouvez trouver une formation pour les ServiceNow® Site DeveloperAPI REST scriptées.