Geskriptete REST-API – ServiceNow Fluent

Die geskriptete REST-API definiert die Endpunkte, Abfrageparameter und Header für einen geskripteten REST-Service [sys_WS_Definition].

Allgemeine Informationen zu geskripteten REST-Services finden Sie unter Scripted REST APIs.

Zugehörige Konzepte

• ServiceNow Fluent

RestApi-Objekt

Erstellen Sie eine geskriptete REST-API [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. Wenn Sie die Anwendung erstellen, wird diese ID in eine eindeutige sys_ID gehasht Weitere Informationen finden Sie unter ServiceNow Fluent Sprachkonstrukte. Format: Now.ID['Zeichenfolge' oder Zahl]
Name	Zeichenfolge	Erforderlich. Der Name der API, der in der API-Dokumentation verwendet wird.
serviceId	Zeichenfolge	Erforderlich. Der API-Bezeichner, der zur Unterscheidung dieser API in URI-Pfaden verwendet wird. Sie muss innerhalb des API-Namespace eindeutig sein.
aktiv	Boolean	Kennzeichnung, die angibt, ob die API Anforderungen bearbeiten kann. Gültige Werte: Wahr: Die API kann Anforderungen bearbeiten. Falsch: Die API kann keine Anforderungen bearbeiten. Standardwert: wahr
shortDescription	Zeichenfolge	Eine kurze Beschreibung der API, die in der API-Dokumentation verwendet wird.
Verbraucht	Zeichenfolge	Eine Liste von Medientypen, die Ressourcen der API verbrauchen können. Standard: Application/JSON,Application/xml,Text/xml
DocLink	Zeichenfolge	Eine URL, die auf die statische Dokumentation zur API verweist.
EnforceAcl	Array	Eine Liste von Variablenbezeichnern von ACL Objekte oder sys_IDs von ACLs, die beim Zugriff auf Ressourcen [sys_Security_acl] erzwungen werden sollen. Weitere Informationen finden Sie unter API der Zugriffssteuerungsliste – ServiceNow Fluent. Um ACLs nicht zu erzwingen, legen Sie diese Eigenschaft auf ein leeres Array fest ( [] ). Standard: Geskriptete REST Extern, Standard
Erstellt	Zeichenfolge	Eine Liste von Medientypen, die Ressourcen der API erzeugen 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.
Richtlinie	Zeichenfolge	Die Richtlinie für den Schutz von Anwendungsdateien beim Herunterladen oder Installieren. Gültige Werte: Lesen: Dateien können nur angezeigt werden. Geschützt: Anwender 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 das Angeben von Versionen können Sie verschiedene Versionen einer API und ihre Status verwalten, z. B. ob sie aktiv, die Standardversion oder veraltet sind.
$Meta	Objekt	Metadaten für die Anwendungsmetadaten. Mit InstallMethod Eigenschaft können Sie die Anwendungsmetadaten einem Ausgabeverzeichnis zuordnen, das nur unter bestimmten Umständen geladen wird. $meta: {       installMethod: 'String' } Gültige Werte für InstallMethod : Demo: Gibt die Anwendungsmetadaten an aus Metadaten/unload.demo Verzeichnis, das mit der Anwendung installiert werden soll, wenn Demodaten laden Option ist ausgewählt. Erste Installation: Gibt die Anwendungsmetadaten an aus Metadaten/Entladen Verzeichnis, das nur bei der ersten Installation einer Anwendung auf einer Instanz installiert werden soll.

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

Die referenzierte ACL wird mit definiert ACL Objekt:

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

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 Routen Objekt innerhalb von RestApi Objekt.

Tabelle : 2. Eigenschaften

Name	Typ	Beschreibung
$ID	Zeichenfolge oder Zahl	Erforderlich. Eine eindeutige ID für das Metadatenobjekt. Wenn Sie die Anwendung erstellen, wird diese ID in eine eindeutige sys_ID gehasht Weitere Informationen finden Sie unter ServiceNow Fluent Sprachkonstrukte. Format: Now.ID['Zeichenfolge' oder Zahl]
Name	Zeichenfolge	Der Name der API-Ressource, die in der API-Dokumentation verwendet wird. Standard: Der Wert von Pfad Eigenschaft
Skript	Skript	Erforderlich. Das anwenderdefinierte Skript definiert, wie der Vorgang Anforderungen analysiert und beantwortet. Diese Eigenschaft unterstützt eine Funktion aus einem JavaScript-Modul, einen Verweis auf eine andere Datei in der Anwendung, die ein Skript enthält, oder Inline-JavaScript. Format: Verwenden Sie für Funktionen den Namen einer Funktion, eines Funktionsausdrucks oder einer Standardfunktion, die aus einem JavaScript-Modul exportiert wurde, und importieren Sie sie in .Jetzt.TS Datei. Informationen zu JavaScript-Modulen finden Sie unter JavaScript-Module und Drittanbieterbibliotheken. Informationen zur Verwendung von Textinhalten aus einer anderen Datei finden Sie in einer Datei in der Anwendung im folgenden Format: Now.include('path/to/file') . Weitere Informationen finden Sie unter ServiceNow Fluent Sprachkonstrukte. Um ein Inline-Skript bereitzustellen, verwenden Sie Zeichenfolgenliterale oder Vorlagenliterale für mehrere Codezeilen: „Skript“ oder „Skript“ .
parameters	Array	Eine Liste von Abfrageparametern [sys_WS_query_Parameter] für die Route. Weitere Informationen finden Sie unter Parameter und Header-Objekte.
headers	Array	Eine Liste der Header [sys_WS_Header] für die Route. Weitere Informationen finden Sie unter Parameter und Header-Objekte.
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: wahr
path	Zeichenfolge	Der Pfad der Ressource relativ zum Basis-API-Pfad. Der relative URI kann Pfadparameter wie enthalten „/abc/{ID}“ . Standard: /
shortDescription	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 PUT-, PATCH- oder POST-Methoden überschrieben werden. Standard: Der Wert von Verbraucht Eigenschaft in RestApi Objekt
EnforceAcl	Array	Eine Liste von Variablenbezeichnern von ACL Objekte oder sys_IDs von ACLs, die beim Zugriff auf Ressourcen [sys_Security_acl] erzwungen werden sollen. Weitere Informationen finden Sie unter API der Zugriffssteuerungsliste – ServiceNow Fluent. Um ACLs nicht zu erzwingen, legen Sie diese Eigenschaft auf ein leeres Array fest ( [] ). Standard: Geskriptete REST Extern, Standard
Erstellt	Zeichenfolge	Eine Liste der Medientypen, die die Ressource erstellen kann. Standard: Der Wert von Erstellt Eigenschaft in RestApi Objekt
Anforderungsbeispiel	Zeichenfolge	Eine gültige Nutzlast des Beispielanforderungstexts 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: ABRUFEN
authorization	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 sein, um auf die Ressource zugreifen zu können. Falsch: Für den Zugriff auf die Ressource ist keine Authentifizierung erforderlich. Standardwert: wahr
Authentifizierung	Boolean	Kennzeichnung, die angibt, ob beim Zugriff auf die Ressource ACLs 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: wahr
InternalRole	Boolean	Kennzeichnung, die angibt, ob die Route die Rolle „snc_internal“ erfordert. Diese Eigenschaft wird nur unterstützt, wenn das Plugin „explizite Rollen“ (com.Glide.explizit_roles) aktiviert ist. Gültige Werte: Wahr: Die Route erfordert die Rolle „snc_internal“. Falsch: Die Route erfordert nicht die Rolle „snc_internal“. Standardwert: wahr
Richtlinie	Zeichenfolge	Die Richtlinie für den Schutz von Anwendungsdateien beim Herunterladen oder Installieren. Gültige Werte: Lesen: Dateien können nur angezeigt werden. Geschützt: Anwender mit Passwortberechtigungen können die Dateien bearbeiten.
Version	Nummer	Die Version der API. Diese Eigenschaft ist erforderlich, wenn Versionen Eigenschaft wird in verwendet RestApi Objekt. 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 sich auf vorhandene Integrationen auszuwirken.
$Meta	Objekt	Metadaten für die Anwendungsmetadaten. Mit InstallMethod Eigenschaft können Sie die Anwendungsmetadaten einem Ausgabeverzeichnis zuordnen, das nur unter bestimmten Umständen geladen wird. $meta: {       installMethod: 'String' } Gültige Werte für InstallMethod : Demo: Gibt die Anwendungsmetadaten an aus Metadaten/unload.demo Verzeichnis, das mit der Anwendung installiert werden soll, wenn Demodaten laden Option ist ausgewählt. Erste Installation: Gibt die Anwendungsmetadaten an aus Metadaten/Entladen Verzeichnis, das nur bei der ersten Installation einer Anwendung auf einer Instanz installiert werden soll.

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

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 darauf antworten kann.

Verwenden Sie Parameter Und Header Objekte in Routen Objekt.

Tabelle : 3. Eigenschaften

Name	Typ	Beschreibung
$ID	Zeichenfolge oder Zahl	Erforderlich. Eine eindeutige ID für das Metadatenobjekt. Wenn Sie die Anwendung erstellen, wird diese ID in eine eindeutige sys_ID gehasht Weitere Informationen finden Sie unter ServiceNow Fluent Sprachkonstrukte. Format: Now.ID['Zeichenfolge' oder Zahl]
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 der Header erforderlich ist. Gültige Werte: Wahr: Der Parameter oder Header ist erforderlich. Falsch: Der Parameter oder Header ist nicht erforderlich. Standardwert: false
Beispielwert	Zeichenfolge	Ein Beispiel für einen gültigen Wert für den Parameter oder Header, der in der API-Dokumentation verwendet wird.
shortDescription	Zeichenfolge	Eine kurze Beschreibung des Parameters oder Headers, der in der API-Dokumentation verwendet wird.
$Meta	Objekt	Metadaten für die Anwendungsmetadaten. Mit InstallMethod Eigenschaft können Sie die Anwendungsmetadaten einem Ausgabeverzeichnis zuordnen, das nur unter bestimmten Umständen geladen wird. $meta: {       installMethod: 'String' } Gültige Werte für InstallMethod : Demo: Gibt die Anwendungsmetadaten an aus Metadaten/unload.demo Verzeichnis, das mit der Anwendung installiert werden soll, wenn Demodaten laden Option ist ausgewählt. Erste Installation: Gibt die Anwendungsmetadaten an aus Metadaten/Entladen Verzeichnis, das nur bei der ersten Installation einer Anwendung auf einer Instanz installiert werden soll.

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 Versionen Objekt innerhalb von RestApi Objekt.

Tabelle : 4. Eigenschaften

Name	Typ	Beschreibung
$ID	Zeichenfolge oder Zahl	Erforderlich. Eine eindeutige ID für das Metadatenobjekt. Wenn Sie die Anwendung erstellen, wird diese ID in eine eindeutige sys_ID gehasht Weitere Informationen finden Sie unter ServiceNow Fluent Sprachkonstrukte. Format: Now.ID['Zeichenfolge' oder Zahl]
Version	Nummer	Erforderlich. Eine Version der REST-API.
aktiv	Boolean	Kennzeichnung, die angibt, ob die Version der REST-API Anforderungen bearbeiten kann. Gültige Werte: Wahr: Die Version der API kann Anforderungen bearbeiten. Falsch: Die Version der API kann keine Anforderungen verarbeiten. Standardwert: wahr
veraltet	Boolean	Kennzeichnung, die angibt, ob die Version der REST-API veraltet ist. Ressourcen, die zu veralteten Versionen gehören, können Anforderungen bearbeiten, werden jedoch in der Dokumentation als veraltet identifiziert. Gültige Werte: Wahr: Die Version der API wird als veraltet identifiziert. Falsch: Die Version der API wurde nicht als veraltet identifiziert. Standardwert: false
shortDescription	Zeichenfolge	Eine kurze Beschreibung der Version der REST-API, die in der API-Dokumentation angezeigt wird.
isDefault	Boolean	Kennzeichnung, die angibt, ob die Version der REST-API die Standardversion ist. Clients können entweder über den URI-Pfad mit oder ohne Versionssteuerung auf die Standardversion zugreifen. Gültige Werte: Wahr: Die API-Version ist die Standardversion. Falsch: Die API-Version ist nicht die Standardversion. Standardwert: false
$Meta	Objekt	Metadaten für die Anwendungsmetadaten. Mit InstallMethod Eigenschaft können Sie die Anwendungsmetadaten einem Ausgabeverzeichnis zuordnen, das nur unter bestimmten Umständen geladen wird. $meta: {       installMethod: 'String' } Gültige Werte für InstallMethod : Demo: Gibt die Anwendungsmetadaten an aus Metadaten/unload.demo Verzeichnis, das mit der Anwendung installiert werden soll, wenn Demodaten laden Option ist ausgewählt. Erste Installation: Gibt die Anwendungsmetadaten an aus Metadaten/Entladen Verzeichnis, das nur bei der ersten Installation einer Anwendung auf einer Instanz installiert werden soll.

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