API REST scriptée : ServiceNow Fluent

L’API REST scriptée comprend 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 des points de terminaison de service web.

Tableau 1. Propriétés

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 nombre. $id: Now.ID[<value>] Lorsque vous créez l’application, cet ID est haché dans un 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 les demandes. Valeurs valides : true : l’API peut prendre en charge des demandes. false : l’API ne peut pas prendre en charge les demandes. Valeur par défaut : true
short_description	Chaîne	Une brève description de l’API, qui est utilisée dans la documentation de 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 d’identificateurs de variables d’objets ACL ou de sys_ids d’ACL à appliquer lors de l’accès à des ressources [sys_security_acl]. Pour plus d'informations, consultez API de liste de contrôle d’accès : ServiceNow Fluent. Pour ne pas appliquer d’ACL, définissez cette propriété sur un tableau vide ([]). enforce_acl: ['sys_id', acl_variable_identifier] Par défaut : Scripté REST 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 de routages.
policy	Chaîne	Politique relative à la protection des fichiers d’application lors du téléchargement ou de l’installation. Valeurs valides : read : les fichiers sont visibles uniquement. Protégé : les utilisateurs disposant d’autorisations de mot de passe peuvent modifier les fichiers.
versions	Tableau	Une liste des versions [sys_ws_version] de l’API. Pour plus d'informations, consultez Objet des versions. Spécifier des versions vous permet de gérer différentes versions d’une API et leurs états, par exemple si elles sont actives, version par défaut ou obsolètes.

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,
        },
    ],
})

L’ACL référencée est définie à l’aide de l’objet ACL :

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 de routages

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 .

Tableau 2. Propriétés

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 nombre. $id: Now.ID[<value>] Lorsque vous créez l’application, cet ID est haché dans un sys_ID unique.
nom	Chaîne	Nom de la ressource d’API utilisé dans la documentation relative à l’API. Par défaut : la 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é à partir d’un module JavaScript et importé dans le fichier .now.ts . Pour en savoir plus sur les modules JavaScript, reportez-vous à la section Modules JavaScript et bibliothèques tierces. Les scripts inline utilisent la balise script au format suivant : script: script`gs.info('info')`,
Actif	Booléen	Marqueur indiquant si la ressource est utilisée. Valeurs valides : vrai : la ressource est utilisée. faux : la ressource n’est pas utilisée. Valeur 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 consommer. Cette propriété peut être remplacée par les méthodes PUT, PATCH ou POST. Par défaut : la valeur de la propriété consomme dans l’objet RestAPI
enforce_acl	Tableau	Une liste d’identificateurs de variables d’objets ACL ou de sys_ids d’ACL à appliquer lors de l’accès à des ressources [sys_security_acl]. Pour plus d'informations, consultez API de liste de contrôle d’accès : ServiceNow Fluent. Pour ne pas appliquer d’ACL, définissez cette propriété sur un tableau vide ([]). enforce_acl: ['sys_id', acl_variable_identifier] Par défaut : Scripté REST externe par défaut
Produit	Chaîne	Une liste de types de médias que la ressource peut produire. Par défaut : la valeur de la propriété produce dans l’objet RestAPI
request_example	Chaîne	Un exemple valide de charge utile du corps de la demande pour la ressource, utilisé dans la documentation relative à l’API.
method	Chaîne	Méthode HTTP que la ressource implémente. Valeurs valides : GET, POST, PUT, PATCH, DELETE Par défaut : GET
autorisation	Booléen	Marqueur indiquant si les utilisateurs doivent être authentifiés pour accéder à la ressource. Valeurs valides : vrai : les utilisateurs doivent être authentifiés pour accéder à la ressource. faux : aucune authentification n’est requise pour accéder à la ressource. Valeur par défaut : true
authentification	Booléen	Marqueur indiquant si les ACL sont appliquées lors de l’accès à la ressource. Valeurs valides : vrai : les ACL sont appliquées lors de l’accès à la ressource. faux : les ACL ne sont pas appliquées lors de l’accès à la ressource. Valeur par défaut : true
internalRole (Rôle interne)	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 : true : l’itinéraire nécessite le rôle snc_internal. false : l’itinéraire ne nécessite pas le rôle snc_internal. Valeur par défaut : true
policy	Chaîne	Politique relative à la protection des fichiers d’application lors du téléchargement ou de l’installation. Valeurs valides : read : les fichiers sont visibles uniquement. Protégé : les utilisateurs disposant d’autorisations de mot de passe peuvent modifier les fichiers.
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 telle 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, 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 .

Tableau 3. Propriétés

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 nombre. $id: Now.ID[<value>] Lorsque vous créez l’application, cet ID est haché dans un 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 : vrai : le paramètre ou l’en-tête est requis. false : le paramètre ou l’en-tête n’est pas obligatoire. 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, utilisé dans la documentation relative à l’API.

parameters: [{ $id: Now.ID['param1'],  name: 'n_param' }],
headers: [{ $id: Now.ID['header1'],  name: 'n_token' }],

Objet des versions

Créez des versions d’API REST scriptée [sys_ws_version] pour définir des points de terminaison de service web.

Utilisez l’objet versions dans l’objet RestApi .

Tableau 4. Propriétés

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 nombre. $id: Now.ID[<value>] Lorsque vous créez l’application, cet ID est haché dans un sys_ID unique.
version	Numéro	Requis. Version de REST API.
Actif	Booléen	Marqueur indiquant si la version de REST API peut prendre en charge des demandes. Valeurs valides : true : la version de l’API peut prendre en charge des demandes. false : la version de l’API ne peut pas prendre en charge les demandes. Valeur 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 : vrai : la version de l’API est identifiée comme déconseillée. false : la version de l’API n’est pas identifiée comme déconseillée. Valeur par défaut : false
short_description	Chaîne	Brève description de la version de l’API REST, qui s’affiche dans la documentation relative à 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 : true : la version de l’API est la version par défaut. false : la version de l’API n’est pas la version par défaut. Valeur par défaut : false

versions: [
 {
   $id: Now.ID['v1'],
   version: 1,
 },
],