API REST scriptée : ServiceNow Fluent
L’API REST scriptée définit les points de terminaison, les paramètres de requête et les en-têtes d’un service REST scripté [sys_ws_definition].
Pour des informations générales sur les services REST scriptés, reportez-vous à la section Scripted REST APIs.
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. Lorsque vous créez l’application, cet ID est haché en une sys_id unique. Pour en savoir plus, consultez ServiceNow Fluent Constructions linguistiques. Format : |
| nom | Chaîne | Requis. Nom de l’API, qui est utilisé dans la documentation relative à l’API. |
| serviceId | Chaîne | Requis. Identificateur d’API utilisé pour distinguer cette API dans les chemins d’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 |
| shortDescription | 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 consommer. Par défaut : application/json,application/xml,text/xml |
| lien doc | Chaîne | URL qui établit un lien vers la documentation statique relative à l’API. |
| enforceAcl | Tableau | Liste des identificateurs de variables des objets ACL ou des sys_ids d’ACL à appliquer lors de l’accès aux 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 ( Valeur par défaut : REST externe scripté Par défaut |
| produit | Chaîne | 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 | Politique régissant la protection des fichiers d’application lors du téléchargement ou de l’installation. Valeurs valides :
|
| versions | Tableau | Liste des versions [sys_ws_version] de l’API. Pour plus d'informations, consultez Objet de 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, la version par défaut ou déconseillées. |
| $meta | Objet | Métadonnées pour les métadonnées de l’application. Avec la propriété installMethod , vous pouvez mapper les métadonnées d’application à un répertoire de sortie qui ne se charge que dans des circonstances spécifiques. Valeurs valides pour installMethod :
|
import { RestApi } from '@servicenow/sdk/core'
import { process } from '../server/handler.js'
RestApi({
$id: Now.ID['rest1'],
name: 'customAPI',
serviceId: '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' }],
enforceAcl: [acl],
version: 1,
},
],
enforceAcl: [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,
adminOverrides: 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. Lorsque vous créez l’application, cet ID est haché en une sys_id unique. Pour en savoir plus, consultez ServiceNow Fluent Constructions linguistiques. Format : |
| nom | Chaîne | Nom de la ressource d’API, qui est utilisé dans la documentation relative à l’API. Par défaut : valeur de la propriété path |
| script | Script | Requis. Le script personnalisé définit la façon dont l’opération analyse les demandes et y répond. Cette propriété prend en charge une fonction d’un module JavaScript, une référence à un autre fichier dans l’application qui contient un script ou JavaScript en ligne. Format :
|
| paramètres | Tableau | Une liste des paramètres de requête [sys_ws_query_parameter] pour l’itinéraire. Pour plus d'informations, consultez Objets de paramètres et d’en-têtes. |
| en-têtes | Tableau | Une liste d’en-têtes [sys_ws_header] pour l’itinéraire. Pour plus d'informations, consultez Objets de paramètres et d’en-têtes. |
| 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}'.Par défaut : / |
| shortDescription | Chaîne | Brève description de la ressource, utilisée dans la documentation relative à l’API. |
| Consomme | Chaîne | Liste des 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é Consumes dans l’objet RestAPI |
| enforceAcl | Tableau | Liste des identificateurs de variables des objets ACL ou des sys_ids d’ACL à appliquer lors de l’accès aux 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 ( Valeur par défaut : REST externe scripté Par défaut |
| produit | Chaîne | Liste des types de médias que la ressource peut produire. Par défaut : valeur de la propriété produce dans l’objet RestApi |
| requestExample | 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 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 |
| Rôle interne | Booléen | Marqueur indiquant si le routage nécessite le rôle snc_internal. Cette propriété n’est prise en charge que si le module d’extension Rôles explicites (com.glide.explicit_roles) est activé. Valeurs valides :
Par défaut : true |
| policy | Chaîne | Politique régissant la 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, 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 les changements sans impact sur les intégrations existantes. |
| $meta | Objet | Métadonnées pour les métadonnées de l’application. Avec la propriété installMethod , vous pouvez mapper les métadonnées d’application à un répertoire de sortie qui ne se charge que dans des circonstances spécifiques. Valeurs valides pour installMethod :
|
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' }],
enforceAcl: [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. Lorsque vous créez l’application, cet ID est haché en une sys_id unique. Pour en savoir plus, consultez ServiceNow Fluent Constructions linguistiques. Format : |
| nom | Chaîne | Requis. Nom du paramètre ou de l’en-tête, qui est utilisé dans la documentation de 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 |
| ExampleValue | Chaîne | Exemple d’une valeur valide pour le paramètre ou l’en-tête, utilisée dans la documentation relative à l’API. |
| shortDescription | Chaîne | Brève description du paramètre ou de l’en-tête, qui est utilisé dans la documentation de l’API. |
| $meta | Objet | Métadonnées pour les métadonnées de l’application. Avec la propriété installMethod , vous pouvez mapper les métadonnées d’application à un répertoire de sortie qui ne se charge que dans des circonstances spécifiques. Valeurs valides pour installMethod :
|
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. Lorsque vous créez l’application, cet ID est haché en une sys_id unique. Pour en savoir plus, consultez ServiceNow Fluent Constructions linguistiques. Format : |
| version | Numéro | Requis. 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 |
| shortDescription | Chaîne | Brève description de la version de l’API REST, qui s’affiche dans la documentation de l’API. |
| isDefault | 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 |
| $meta | Objet | Métadonnées pour les métadonnées de l’application. Avec la propriété installMethod , vous pouvez mapper les métadonnées d’application à un répertoire de sortie qui ne se charge que dans des circonstances spécifiques. Valeurs valides pour installMethod :
|
versions: [
{
$id: Now.ID['v1'],
version: 1,
},
],