API REST scriptée : ServiceNow Fluent
L’API REST scriptée inclut des objets qui définissent les points de terminaison, les paramètres de requête et les en-têtes d’un service REST scripté [sys_ws_definition].
Objet RestAPI
Créez une API REST scriptée [sys_ws_definition] pour définir les points de terminaison de service web.
| Nom | Type | Description |
|---|---|---|
| $id | Chaîne ou numéro | Requis. ID unique pour l’objet de métadonnées fourni au format suivant, où < valeur > est une chaîne ou un numéro.Lorsque vous créez l’application, cet ID est haché en une sys_ID unique. |
| nom | Chaîne | Requis. Nom de l’API, utilisé dans la documentation relative à l’API. |
| service_id | Chaîne | Requis. Identificateur d’API utilisé pour distinguer cette API dans les chemins d’accès à l’URI. Il doit être unique dans l’espace de noms de l’API. |
| actif | Booléen | Marqueur indiquant si l’API peut prendre en charge des demandes. Valeurs valides :
Par défaut : true |
| short_description | Chaîne | Brève description de l’API, utilisée dans la documentation relative à l’API. |
| Consomme | Chaîne | Une liste des types de médias que les ressources de l’API peuvent utiliser. Par défaut : application/json,application/xml,text/xml |
| doc_link | Chaîne | URL qui établit un lien vers la documentation statique relative à l’API. |
| enforce_acl | Tableau | Une liste des identificateurs de variables d’objets ACL ou des sys_ids d’ACL à appliquer lors de l’accès à des ressources [sys_security_acl]. Pour plus d'informations, consultez API de la liste de contrôles d’accès : ServiceNow Fluent. Pour ne pas appliquer d’ACL, définissez cette propriété sur un tableau vide ( Par défaut : REST scripté externe Par défaut |
| Produit | Chaîne | Une liste des types de médias que les ressources de l’API peuvent produire. Par défaut : application/json,application/xml,text/xml |
| acheminements | Tableau | Ressources [sys_ws_operation] pour l’API. Pour plus d'informations, consultez Objet d’itinéraires. |
| policy | Chaîne | La politique de protection des fichiers d’application lors du téléchargement ou de l’installation. Valeurs valides :
|
| versions | Tableau | Une liste de versions [sys_ws_version] de l’API. Pour plus d'informations, consultez Objet de versions. La spécification des versions vous permet de gérer différentes versions d’une API et leurs états, par exemple si elles sont actives, la version par défaut ou déconseillées. |
import { RestApi } from '@servicenow/sdk/core'
import { process } from '../server/handler.js'
RestApi({
$id: Now.ID['rest1'],
name: 'customAPI',
service_id: 'custom_api',
consumes: 'application/json',
routes: [
{
$id: Now.ID['route1'],
path: '/home/{id}',
script: process,
parameters: [{ $id: Now.ID['param1'], name: 'n_param' }],
headers: [{ $id: Now.ID['header1'], name: 'n_token' }],
enforce_acl: [acl],
version: 1,
},
],
enforce_acl: [acl],
versions: [
{
$id: Now.ID['v1'],
version: 1,
},
],
})
import { Acl } from "@servicenow/sdk/core";
const acl = Acl({
name: 'My random ACL',
type: 'rest_endpoint',
script: `answer = (Math.random() > 0.5)`,
active: true,
admin_overrides: false,
operations: ['execute'],
})Objet d’itinéraires
Créez une ressource REST scriptée [sys_ws_operation] pour définir la méthode HTTP, le script de traitement et pour remplacer les paramètres du service parent.
Utilisez l’objet routes dans l’objet RestAPI .
| Nom | Type | Description |
|---|---|---|
| $id | Chaîne ou numéro | Requis. ID unique pour l’objet de métadonnées fourni au format suivant, où < valeur > est une chaîne ou un numéro.Lorsque vous créez l’application, cet ID est haché en une sys_ID unique. |
| nom | Chaîne | Nom de la ressource d’API, utilisé dans la documentation relative à l’API. Par défaut : valeur de la propriété path |
| script | Script | Requis. Fonction ou script en ligne précédé d’une balise de script . Le script personnalisé définit la manière dont l’opération analyse les demandes et y répond.Pour les fonctions, utilisez le nom d’une fonction, d’une expression de fonction ou d’une fonction par défaut exportée à partir d’un module JavaScript et importée dans le fichier .now.ts . Pour plus d’informations sur les modules JavaScript, reportez-vous à la section Modules JavaScript et bibliothèques tierces. Les scripts en ligne utilisent la balise de script au format suivant : |
| actif | Booléen | Marqueur indiquant si la ressource est utilisée. Valeurs valides :
Par défaut : true |
| chemin d'accès | Chaîne | Chemin d’accès de la ressource par rapport au chemin de l’API de base. L’URI relative peut contenir des paramètres de chemin tels que '/abc/{id}'.Faire défaut:/ |
| short_description | Chaîne | Brève description de la ressource, utilisée dans la documentation relative à l’API. |
| Consomme | Chaîne | Une liste de types de médias que la ressource peut utiliser. Cette propriété peut être remplacée par les méthodes PUT, PATCH ou POST. Par défaut : valeur de la propriété consommer dans l’objet RestAPI |
| enforce_acl | Tableau | Une liste des identificateurs de variables d’objets ACL ou des sys_ids d’ACL à appliquer lors de l’accès à des ressources [sys_security_acl]. Pour plus d'informations, consultez API de la liste de contrôles d’accès : ServiceNow Fluent. Pour ne pas appliquer d’ACL, définissez cette propriété sur un tableau vide ( Par défaut : REST scripté externe Par défaut |
| Produit | Chaîne | Une liste de types de médias que la ressource peut produire. Par défaut : valeur de la propriété produce dans l’objet RestAPI |
| request_example | Chaîne | Exemple valide de charge utile de corps de demande pour la ressource, utilisée dans la documentation relative à l’API. |
| method | Chaîne | Méthode HTTP que la ressource implémente. Valeurs valides : GET, POST, PUT, PATCH, DELETE Valeur par défaut : GET |
| autorisation | Booléen | Marqueur indiquant si les utilisateurs doivent être authentifiés pour accéder à la ressource. Valeurs valides :
Par défaut : true |
| authentification | Booléen | Marqueur indiquant si les ACL sont appliquées lors de l’accès à la ressource. Valeurs valides :
Par défaut : true |
| internalRole | Booléen | Marqueur indiquant si l’itinéraire nécessite le rôle snc_internal. Cette propriété n’est prise en charge que si le module d’extension Explicit Roles (com.glide.explicit_roles) est activé. Valeurs valides :
Par défaut : true |
| policy | Chaîne | La politique de protection des fichiers d’application lors du téléchargement ou de l’installation. Valeurs valides :
|
| version | Numéro | Version de l’API. Cette propriété est requise si la propriété versions est utilisée dans l’objet RestAPI . La version spécifiée avec cette propriété est utilisée pour générer automatiquement un URI avec une 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, vous pouvez tester et déployer des changements sans impact sur les intégrations existantes. |
routes: [
{
$id: Now.ID['route1'],
path: '/home/{id}',
script: process,
parameters: [{ $id: Now.ID['param1'], name: 'n_param' }],
headers: [{ $id: Now.ID['header1'], name: 'n_token' }],
enforce_acl: [acl],
version: 1,
},
],Objets de paramètres et d’en-têtes
Créez des paramètres de requête [sys_ws_query_parameter] et des en-têtes [sys_ws_header] pour les itinéraires dans une API REST scriptée. Les paramètres de requête contrôlent les valeurs qu’un utilisateur demandeur peut transmettre dans l’URI de demande. Les en-têtes spécifient ce que l’API accepte et ce à quoi elle peut répondre.
Utilisez les objets paramètres et en-têtes dans l’objet routes .
| Nom | Type | Description |
|---|---|---|
| $id | Chaîne ou numéro | Requis. ID unique pour l’objet de métadonnées fourni au format suivant, où < valeur > est une chaîne ou un numéro.Lorsque vous créez l’application, cet ID est haché en une sys_ID unique. |
| nom | Chaîne | Requis. Nom du paramètre ou de l’en-tête utilisé dans la documentation relative à l’API. |
| obligatoire | Booléen | Marqueur indiquant si le paramètre ou l’en-tête est requis. Valeurs valides :
Valeur par défaut : false |
| example_value | Chaîne | Exemple d’une valeur valide pour le paramètre ou l’en-tête, utilisée dans la documentation relative à l’API. |
| short_description | Chaîne | Brève description du paramètre ou de l’en-tête, qui est utilisé dans la documentation de l’API. |
parameters: [{ $id: Now.ID['param1'], name: 'n_param' }],
headers: [{ $id: Now.ID['header1'], name: 'n_token' }],Objet de versions
Créez des versions pour une API REST scriptée [sys_ws_version] afin de définir des points de terminaison de service web.
Utilisez l’objet versions dans l’objet RestAPI .
| Nom | Type | Description |
|---|---|---|
| $id | Chaîne ou numéro | Requis. ID unique pour l’objet de métadonnées fourni au format suivant, où < valeur > est une chaîne ou un numéro.Lorsque vous créez l’application, cet ID est haché en une sys_ID unique. |
| version | Numéro | Requis. Une version de l’API REST. |
| actif | Booléen | Marqueur indiquant si la version de l’API REST peut prendre en charge des demandes. Valeurs valides :
Par défaut : true |
| déconseillé | Booléen | Marqueur indiquant si la version de l’API REST est déconseillée. Les ressources appartenant à des versions déconseillées peuvent prendre en charge des demandes, mais sont identifiées comme déconseillées dans la documentation. Valeurs valides :
Valeur par défaut : false |
| short_description | Chaîne | Une brève description de la version de l’API REST, qui s’affiche dans la documentation de l’API. |
| is_default | Booléen | Marqueur indiquant si la version de l’API REST est la version par défaut. Les clients peuvent accéder à la version par défaut en utilisant le chemin d’URI avec version ou sans version. Valeurs valides :
Valeur par défaut : false |
versions: [
{
$id: Now.ID['v1'],
version: 1,
},
],