--- sourceDocument: Référence de l’API Xanadu sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/fr-FR/xanadu/api-reference Release : - xanadu ft:locale : - fr-FR ft:publication_title : - Référence de l’API Xanadu ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # API REST basées sur un script # API REST basées sur un script {#ariaid-title1} * Rversion finale: Xanadu * * Mis à jour 1 août 2024 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 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 basées sur un script à l'aide du formulaire Service REST scripté disponible sous Services Web basés sur un script → API REST basées sur un script. Figure 1. Formulaire Service REST scripté Les vidéos suivantes fournissent des informations supplémentaires sur les API REST scriptées : * [API REST scriptées -- Conception](https://www.youtube.com/watch?v=Tw70sHgDc-w) * [API REST basées sur un script -- Implémentation](https://www.youtube.com/watch?v=LFHV-Qk1-Yk) {#c_CustomWebServices__ul_bjx_c3b_vzb} ## URI d'API REST scriptés {#c_CustomWebServices__section_upf_pn4_zhb} Les URI d'API REST scriptés ont le format suivant : https://\/api/\/\/\/\ Dans cet URI : * \: chemin d'accès à l'instance ServiceNow où les utilisateurs accèdent à l'API REST scriptée. * \: 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 dans 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, consultez [Périmètre de l'application](https://www.servicenow.com/docs/access?context=c_ApplicationScope&version=xanadu&pubname=xanadu-application-development&ft:locale=en-US). * \:Optionnel. Version du point de terminaison à laquelle 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. * \: valeur du champ ID d'API sur le formulaire Service REST scripté. Par défaut, cette valeur est basée sur le nom du service. * \: 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 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. {#c_CustomWebServices__ul_osv_kgc_lr} ## Gestion des versions de l'API REST scriptée {#c_CustomWebServices__section_pnw_c44_zhb} Les URI d'API REST scriptés peuvent inclure un numéro de version, par exemple /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 de l'API par défaut {#c_CustomWebServices__section_jgj_b44_zhb} 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 d'API REST scriptées {#c_CustomWebServices__section_fhh_3nw_23b} Une ressource d'API REST scriptée est équivalente à un point de terminaison REST. Il 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 {#c_CustomWebServices__section_tfl_444_zhb} 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 API REST scriptée, 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 de l'API REST scriptés {#c_CustomWebServices__section_y5m_xx4_zhb} Pour utiliser les API REST basées sur un script, vous devez disposer du rôle d'administrateur de service web \[web_service_admin\]. Les utilisateurs disposant de ce rôle peuvent lire, créer, modifier et supprimer des API REST et des ressources de service Web scriptées. Remarque : Ces rôles ne sont pas requis pour accéder à un point de terminaison d'API REST scripté. ## Formats de demande et de réponse {#c_CustomWebServices__section_p3s_fkw_23b} 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é de l'API REST scriptée {#c_CustomWebServices__section_txq_hx4_zhb} 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 utilisateur avec un contrôle d'accès strict à toutes les ressources. Utilisez la fonctionnalité de politique d'accès d'API pour contrôler la méthode d'authentification des API. Pour plus d'informations, consultez [API access policy](https://www.servicenow.com/docs/access?context=api-access-policy&version=xanadu&pubname=xanadu-platform-security&ft:locale=en-US). ## Contrôles d'accès à l'API REST scriptés {#c_CustomWebServices__section_rbc_zz4_zhb} Les listes de contrôle d'accès (ACL) 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 point de terminaison scripté. Un utilisateur demandeur doit satisfaire au moins une des ACL. Il n'est pas nécessaire de satisfaire tous les ACL sélectionnés. Vous pouvez définir une seule ACL pour une API REST entière 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 ayant le rôle snc_external d'effectuer des demandes auprès de l'API. Lors de la définition d'une ACL d'API REST scriptée, elle doit avoir la valeur TypeREST_Endpoint. Pour plus d'informations sur les ACL, reportez-vous aux [rubriques Règles de liste de contrôle d'accès](https://www.servicenow.com/docs/access?context=access-control-rules&version=xanadu&pubname=xanadu-platform-security&ft:locale=en-US) et [Configurer une ressource d'API REST scriptée pour exiger une ACL](https://servicenow-prod.fluidtopics.net/u9NA18iBsIFZJRHS8jikZw "Par défaut, les ressources/points de terminaison d’API héritent des paramètres de sécurité de l’API parente. Définissez des ACL personnalisées pour une ressource/un point de terminaison spécifique afin de remplacer les paramètres hérités."). ## Matrice de sécurité de l'API REST scriptée {#c_CustomWebServices__section_xww_cgp_zhb} Il existe plusieurs configurations de sécurité possibles pour les API REST scriptées. Utilisez cette table pour identifier la configuration de sécurité de l'API REST scriptée qui convient le mieux à vos besoins, ainsi que les valeurs de champ pour implémenter cette configuration. {#c_CustomWebServices__table_r2p_vbt_tr__entry__3}{#c_CustomWebServices__table_r2p_vbt_tr__entry__8} | 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 uniquement une authentification de base. Aucune ACL n'est requise. | N'importe quelle valeur | Vrai | Faux | N'importe quelle valeur | | La ressource nécessite uniquement une authentification de base. L'ACL est requise. | 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 | | Une ACL sélectionnée dans l'enregistrement d'API REST scripté est requise. | Une ou plusieurs ACL sélectionnées | Vrai | Vrai | Aucune ACL sélectionnée | [Tableau 1. Sécurité de l'API REST scriptée] {#c_CustomWebServices__table_r2p_vbt_tr} ## Objets d'erreur de l'API REST scriptés {#c_CustomWebServices__section_xkj_5gp_zhb} Les API REST basées sur un script 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 d'API REST scriptées pour alerter les clients demandeurs d'erreurs. Utilisez des objets d'erreur pour répondre aux demandes entrantes, et non pour détecter les erreurs dans votre code côté serveur. ## Format de réponse d'erreur {#c_CustomWebServices__section_f2v_1hp_zhb} 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 [Infrastructure de tests automatisés](https://www.servicenow.com/docs/access?context=automated-test-framework&version=xanadu&pubname=xanadu-application-development&ft:locale=en-US) (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 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 à la section Administration des configurations d'étapes de test REST et des configurations d'étapes](https://www.servicenow.com/docs/access?context=atf-administer-rest&version=xanadu&pubname=xanadu-application-development&ft:locale=en-US)[de test REST ATF](https://www.servicenow.com/docs/access?context=rest-test-steps&version=xanadu&pubname=xanadu-application-development&ft:locale=en-US). ## Formation pour les développeurs {#c_CustomWebServices__section_dk2_2cc_2hb} Dans le , vous ServiceNow® Site Developertrouverez une formation pour [les API REST scriptées](https://developer.servicenow.com/app.do#!/training/article/app_store_learnv2_rest_paris_scripted_rest_apis/app_store_learnv2_rest_paris_scripted_rest_api_objectives?v=paris). * **[Créer une API REST scriptée](https://servicenow-prod.fluidtopics.net/IesI4ehA76ZzrFTrhXGlog)** Créez une API REST scriptée pour définir des points de terminaison de service web. * **[Bonnes pratiques des API REST scriptées](https://servicenow-prod.fluidtopics.net/W79I4ySEqADrWZ7QZPa0TQ)** Suivez ces instructions lors de la conception et de l'implémentation des API REST scriptées. * **[Exemples d'API REST scriptées](https://servicenow-prod.fluidtopics.net/jbw1_lKZURcO1axzq3tw_Q)** Plusieurs exemples sont disponibles pour montrer comment créer et utiliser des API REST scriptées.