Scripted REST API – ServiceNow Fluent

Die Scripted REST API enthält Objekte, die die Endpunkte, Abfrageparameter und Header für einen geskripteten REST-Service definieren [sys_ws_definition].

RestApi-Objekt

Erstellen Sie eine REST API mit Skript [sys_ws_definition], um Webservice-Endpunkte zu definieren.

Tabelle : 1. Eigenschaften

Name	Typ	Beschreibung
$ID	Zeichenfolge oder Zahl	Erforderlich. Eine eindeutige ID für das Metadatenobjekt, die im folgenden Format bereitgestellt wird: wobei<value> ist eine Zeichenfolge oder Zahl. $id: Now.ID[<value>] Wenn Sie die Anwendung erstellen, wird diese ID in eine eindeutige sys_ID gehasht.
Name	Zeichenfolge	Erforderlich. Der Name der API, die in der API-Dokumentation verwendet wird.
service_id	Zeichenfolge	Erforderlich. Der API-Bezeichner, der zur Unterscheidung dieser API in URI-Pfaden verwendet wird. Er muss innerhalb des API-Namespace eindeutig sein.
aktiv	Boolean	Kennzeichnung, die angibt, ob die API Anforderungen verarbeiten kann. Gültige Werte: „wahr“: Die API kann Anforderungen verarbeiten. „falsch“: Die API kann keine Anforderungen verarbeiten. Standardwert: true
short_description	Zeichenfolge	Kurze Beschreibung der API, die in der API-Dokumentation verwendet wird.
verbraucht	Zeichenfolge	Eine Liste der Medientypen, die Ressourcen der API verbrauchen können. Standard: application/json,application/xml,text/xml
doc_link	Zeichenfolge	Eine URL mit einer Verknüpfung zur statischen Dokumentation über die API.
erzwingen_acl	Array	Eine Liste von Variablenbezeichnern von ACL -Objekten oder sys_ids von ACLs, die beim Zugriff auf Ressourcen erzwungen werden sollen [sys_security_acl]. Weitere Informationen finden Sie unter Zugriffssteuerungslisten-API – ServiceNow Fluent. Um ACLs nicht zu erzwingen, legen Sie diese Eigenschaft auf ein leeres Array ([]) fest. enforce_acl: ['sys_id', acl_variable_identifier] Standard: Geskripteter externer REST-Standard
erzeugt	Zeichenfolge	Eine Liste der Medientypen, die von Ressourcen der API erzeugt werden können. Standard: application/json,application/xml,text/xml
Routen	Array	Die Ressourcen [sys_ws_operation] für die API. Weitere Informationen finden Sie unter Routenobjekt.
policy	Zeichenfolge	Die Richtlinie für den Schutz von Anwendungsdateien bei Download oder Installation. Gültige Werte: lesen: Dateien können nur angezeigt werden. geschützt: Benutzer mit Passwortberechtigungen können die Dateien bearbeiten.
versions	Array	Eine Liste der Versionen [sys_ws_version] für die API. Weitere Informationen finden Sie unter Versionsobjekt. Durch die Angabe von Versionen können Sie verschiedene Versionen einer API und deren Status verwalten, z. B. ob sie aktiv, die Standardversion oder veraltet sind.

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

Die referenzierte ACL wird mithilfe des ACL- Objekts definiert:

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

Routenobjekt

Erstellen Sie eine geskriptete REST-Ressource [sys_ws_operation], um die HTTP-Methode und das Verarbeitungsskript zu definieren und Einstellungen aus dem übergeordneten Service zu überschreiben.

Verwenden Sie das Routenobjekt innerhalb des RestApi- Objekts.

Tabelle : 2. Eigenschaften

Name	Typ	Beschreibung
$ID	Zeichenfolge oder Zahl	Erforderlich. Eine eindeutige ID für das Metadatenobjekt, die im folgenden Format bereitgestellt wird: wobei<value> ist eine Zeichenfolge oder Zahl. $id: Now.ID[<value>] Wenn Sie die Anwendung erstellen, wird diese ID in eine eindeutige sys_ID gehasht.
Name	Zeichenfolge	Der Name der API-Ressource, die in der API-Dokumentation verwendet wird. Standard: der Wert der Pfadeigenschaft
Skript	Skript	Erforderlich. Eine Funktion oder ein Inline-Skript, dem ein Skript -Tag vorangestellt ist. Das anwenderdefinierte Skript definiert, wie der Vorgang Anforderungen analysiert und beantwortet. Verwenden Sie für Funktionen den Namen einer Funktion, eines Funktionsausdrucks oder einer Standardfunktion, die aus einem JavaScript-Modul exportiert und in die .now.ts -Datei importiert wurde. Informationen zu JavaScript-Modulen finden Sie unter JavaScript-Module und Bibliotheken von Drittparteien. Inline-Skripts verwenden das Skript -Tag im folgenden Format: script: script`gs.info('info')`,
aktiv	Boolean	Kennzeichnung, die angibt, ob die Ressource verwendet wird. Gültige Werte: wahr: Die Ressource wird verwendet. „falsch“: Die Ressource wird nicht verwendet. Standardwert: true
path	Zeichenfolge	Der Pfad der Ressource relativ zum API-Basispfad. Der relative URI kann Pfadparameter wie „/abc/{id}“enthalten. Standard: /
short_description	Zeichenfolge	Eine kurze Beschreibung der Ressource, die in der API-Dokumentation verwendet wird.
verbraucht	Zeichenfolge	Eine Liste der Medientypen, die die Ressource verbrauchen kann. Diese Eigenschaft kann mit den Methoden PUT, PATCH oder POST überschrieben werden. Standard: Der Wert der Eigenschaft „ verbraucht “ im RestApi- Objekt
erzwingen_acl	Array	Eine Liste von Variablenbezeichnern von ACL -Objekten oder sys_ids von ACLs, die beim Zugriff auf Ressourcen erzwungen werden sollen [sys_security_acl]. Weitere Informationen finden Sie unter Zugriffssteuerungslisten-API – ServiceNow Fluent. Um ACLs nicht zu erzwingen, legen Sie diese Eigenschaft auf ein leeres Array ([]) fest. enforce_acl: ['sys_id', acl_variable_identifier] Standard: Geskripteter externer REST-Standard
erzeugt	Zeichenfolge	Eine Liste der Medientypen, die die Ressource produzieren kann. Standard: Der Wert der Eigenschaft „ Erzeugt “ im RestApi- Objekt
request_example	Zeichenfolge	Eine gültige Beispielnutzlast des Anforderungstexts für die Ressource, die in der API-Dokumentation verwendet wird.
method	Zeichenfolge	Die HTTP-Methode, die die Ressource implementiert. Gültige Werte: GET, POST, PUT, PATCH, DELETE Standard: GET
Autorisierung	Boolean	Kennzeichnung, die angibt, ob Anwender für den Zugriff auf die Ressource authentifiziert werden müssen. Gültige Werte: wahr: Anwender müssen authentifiziert werden, um auf die Ressource zugreifen zu können. „falsch“: Für den Zugriff auf die Ressource ist keine Authentifizierung erforderlich. Standardwert: true
-Authentifizierung	Boolean	Kennzeichnung, die angibt, ob ACLs beim Zugriff auf die Ressource erzwungen werden. Gültige Werte: „wahr“: ACLs werden beim Zugriff auf die Ressource erzwungen. „falsch“: ACLs werden beim Zugriff auf die Ressource nicht erzwungen. Standardwert: true
internalRole	Boolean	Kennzeichnung, die angibt, ob für die Route die Rolle „snc_internal“ erforderlich ist. Diese Eigenschaft wird nur unterstützt, wenn das Plugin „Explicit Roles“ (com.glide.explicit_roles) aktiviert ist. Gültige Werte: „wahr“: Die Route erfordert die Rolle „snc_internal“. „falsch“: Für die Route ist die Rolle „snc_internal“ nicht erforderlich. Standardwert: true
policy	Zeichenfolge	Die Richtlinie für den Schutz von Anwendungsdateien bei Download oder Installation. Gültige Werte: lesen: Dateien können nur angezeigt werden. geschützt: Benutzer mit Passwortberechtigungen können die Dateien bearbeiten.
Version	Nummer	Die Version der API. Diese Eigenschaft ist erforderlich, wenn die Eigenschaft „ versions “ im RestApi- Objekt verwendet wird. Die mit dieser Eigenschaft angegebene Version wird verwendet, um automatisch einen URI mit einer Version zu generieren, z. B. /api/management/v1/table/{tableName}. Versionsnummern identifizieren die Endpunktversion, auf die ein URI zugreift. Durch Angabe einer Versionsnummer können Sie Änderungen testen und bereitstellen, ohne dass sich dies auf vorhandene Integrationen auswirkt.

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

Parameter- und Header-Objekte

Erstellen Sie Abfrageparameter [sys_ws_query_parameter] und Header [sys_ws_header] für Routen in einer geskripteten REST API. Abfrageparameter steuern, welche Werte ein anfordernder Anwender im Anforderungs-URI übergeben kann. Header geben an, was die API akzeptiert und womit antworten kann.

Verwenden Sie die Parameter- und Headerobjekte innerhalb des Routenobjekts.

Tabelle : 3. Eigenschaften

Name	Typ	Beschreibung
$ID	Zeichenfolge oder Zahl	Erforderlich. Eine eindeutige ID für das Metadatenobjekt, die im folgenden Format bereitgestellt wird: wobei<value> ist eine Zeichenfolge oder Zahl. $id: Now.ID[<value>] Wenn Sie die Anwendung erstellen, wird diese ID in eine eindeutige sys_ID gehasht.
Name	Zeichenfolge	Erforderlich. Der Name des Parameters oder Headers, der in der API-Dokumentation verwendet wird.
erforderlich	Boolean	Kennzeichnung, die angibt, ob der Parameter oder Header erforderlich ist. Gültige Werte: „wahr“: Der Parameter oder Header ist erforderlich. „falsch“: Der Parameter oder Header ist nicht erforderlich. Standardwert: false
example_value	Zeichenfolge	Ein Beispiel für einen gültigen Wert für den Parameter oder Header, der in der API-Dokumentation verwendet wird.
short_description	Zeichenfolge	Eine kurze Beschreibung des Parameters oder Headers, der in der API-Dokumentation verwendet wird.

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

Versionsobjekt

Erstellen Sie Versionen für eine geskriptete REST API [sys_ws_version], um Webservice-Endpunkte zu definieren.

Verwenden Sie das Versionsobjekt innerhalb des RestApi- Objekts.

Tabelle : 4. Eigenschaften

Name	Typ	Beschreibung
$ID	Zeichenfolge oder Zahl	Erforderlich. Eine eindeutige ID für das Metadatenobjekt, die im folgenden Format bereitgestellt wird: wobei<value> ist eine Zeichenfolge oder Zahl. $id: Now.ID[<value>] Wenn Sie die Anwendung erstellen, wird diese ID in eine eindeutige sys_ID gehasht.
Version	Nummer	Erforderlich. Eine Version der REST API.
aktiv	Boolean	Kennzeichnung, die angibt, ob die Version der REST API Anforderungen verarbeiten kann. Gültige Werte: true: Die Version der API, die Anforderungen verarbeiten kann. „falsch“: Die Version der API kann keine Anforderungen verarbeiten. Standardwert: true
veraltet	Boolean	Kennzeichnung, die angibt, ob die Version der REST API veraltet ist. Ressourcen, die zu veralteten Versionen gehören, können Anforderungen verarbeiten, werden jedoch in der Dokumentation als veraltet gekennzeichnet. Gültige Werte: „wahr“: Die Version der API wird als veraltet identifiziert. „falsch“: Die Version der API wird nicht als veraltet identifiziert. Standardwert: false
short_description	Zeichenfolge	Kurze Beschreibung der Version der REST API, die in der API-Dokumentation angezeigt wird.
is_default	Boolean	Kennzeichnung, die angibt, ob die Version der REST API die Standardversion ist. Clients können über den URI-Pfad mit oder ohne Versionsdefinition auf die Standardversion zugreifen. Gültige Werte: wahr: Die Version der API ist die Standardversion. false: Die Version der API ist nicht die Standardversion. Standardwert: false

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