Scripted REST APIs
Mit der geskripteten REST-API-Funktion können Anwendungsentwickler anwenderdefinierte Webservice-APIs erstellen.
Sie können Serviceendpunkte, Abfrageparameter und Header für eine geskriptete REST-API sowie Skripts zur Verwaltung der Anforderung und Antwort definieren.
Geskriptete REST-APIs folgen im Allgemeinen der REST-Architektur, Sie können sie jedoch so anpassen, dass sie verschiedene Konventionen verwenden. Sie definieren geskriptete REST-APIs mithilfe des Formulars „Geskripteter REST-Service“ unter Geskriptete Webservices → Geskriptete REST-APIs .
Geskriptete REST-API-URIs
Geskriptete REST-API-URIs haben das folgende Format:
https://<instance.service-now.com>/api/<name_space>/<version>/<api_id>/<relative_path>
- <instance.service-now.com>: Pfad zu ServiceNowInstanz, in der Anwender auf die geskriptete REST-API zugreifen.
- <name_space>: Für Webservices im globalen Bereich ist das Namensfeld der Wert der Eigenschaft glide.appcreator.company.code. Für Webservices in einer bereichsbezogenen Anwendung ist der Namensplatz der Bereichsname, z. B. x_Company_appname. Weitere Informationen zu Namensräumen finden Sie unter Anwendungsbereich .
- <version>: Optional. Version des Endpunkts, auf den zugegriffen werden soll, wenn die API Versionsverwaltung verwendet, z. B. v1 . Sie können auf die Standardversion einer versionierten API zugreifen, indem Sie den URI ohne Versionsnummer angeben.
- <api_id>: Wert von API-ID Feld im Formular „Geskripteter REST-Service“. Standardmäßig basiert dieser Wert auf dem Servicenamen.
- <relative_path>: Relativer Pfad, der für die Ressource im Formular „Geskripteter REST-Service“ definiert ist. Wenn Sie einen relativen Ressourcenpfad angeben, können Sie mehrere Ressourcen mit derselben HTTP-Methode, z. B. GET, in einem Webservice verwenden. Beispielsweise kann eine Ressource den Pfad angeben
/{ID}Wenn der Webservice nur eine GET-Ressource hat, oder/User/{ID}Und/Message/{ID}Wenn der Webservice über verschiedene Ressourcen zum anfordern von Anwender- und Nachrichtendatensätzen verfügt.
Skriptbasierte REST-API-Versionsverwaltung
Geskriptete REST-API-URIs können eine Versionsnummer enthalten, z. B. /api/Management/v1/table/{tableName} . Versionsnummern identifizieren die Endpunktversion, auf die ein URI zugreift. Durch Angabe einer Versionsnummer in Ihren URIs können Sie Änderungen testen und bereitstellen, ohne vorhandene Integrationen zu beeinträchtigen.
Standard-API-Version
Eine Version kann als Standard markiert werden. Durch die Angabe einer Standardversion können Anwender über einen geskripteten REST-Endpunkt ohne Versionsnummer auf diese Version zugreifen. Wenn keine Version als Standard markiert ist, wird die neueste Version als Standard verwendet.
Geskriptete REST-API-Ressourcen
Eine geskriptete REST-API-Ressource entspricht einem REST-Endpunkt. Definiert die auszuführende HTTP-Methode, das Verarbeitungsskript und alle Überschreibungseinstellungen aus der übergeordneten API. Sie können eine oder mehrere Ressourcen pro API definieren.
Geskriptete REST-API-Abfrageparameter
Abfrageparameter definieren Werte, die anfordernde Anwender in einer Anforderung übergeben können. Beim Erstellen einer geskripteten REST-API können Sie angeben, welche Parameter für jede Anforderung verfügbar sind und welche obligatorisch sind. Sie können einen Abfrageparameter auch mehreren Ressourcen zuordnen.
Greifen Sie mithilfe des Anforderungsobjekts auf Anforderungsparameter in Skripts zu QueryParameter Feld.
Geskriptete REST-API-Rollen
Anforderungs- und Antwortformate
Standardmäßig unterstützen alle Ressourcen in einer API die folgenden Anforderungs- und Antwortformate: „application/json“, „application/xml“ und „text/xml“. Sie können die Standardformate auf API-Ebene überschreiben. Die neuen Formate gelten für alle Ressourcen, die zur API gehören, es sei denn, eine einzelne Ressource überschreibt die Standardwerte.
Geskriptete REST-API-Sicherheit
Sie können Ihre geskripteten REST-APIs mit dem erforderlichen Sicherheitsniveau konfigurieren. Von öffentlichen APIs/Endpunkten, die keine Sicherheit erfordern, bis zu hochsicheren APIs/Endpunkten, die Anwenderauthentifizierung mit enger Zugriffssteuerung für alle Ressourcen erfordern.
Verwenden Sie die API-Zugriffsrichtlinienfunktion, um die Authentifizierungsmethode für die APIs zu steuern. Weitere Informationen finden Sie unter API access policy.
Geskriptete REST-API-Zugriffssteuerungen
Zugriffssteuerungslisten (ACLs) definieren Kriterien, z. B. die erforderlichen Rollen und Bedingungen, die ein Anwender erfüllen muss, um auf eine geskriptete REST-API oder einen Endpunkt zuzugreifen. Ein anfordernder Anwender muss mindestens eine der ACLs erfüllen. Es ist nicht erforderlich, alle ausgewählten ACLs zu erfüllen. Sie können eine einzelne ACL für eine gesamte REST-API oder für einen einzelnen Endpunkt definieren.
Beim Definieren einer geskripteten REST-API-ACL muss sie über verfügen Typ Wert REST_Endpoint .
Weitere Informationen zu ACLs finden Sie unter Regeln für Zugriffssteuerungsliste Und Konfigurieren Sie eine geskriptete REST-API-Ressource, um eine ACL zu erfordern.
Geskriptete REST-API-Sicherheitsmatrix
Es gibt mehrere mögliche Sicherheitskonfigurationen für geskriptete REST-APIs. Verwenden Sie diese Tabelle, um die geskriptete REST-API-Sicherheitskonfiguration zu identifizieren, die Ihren Anforderungen am besten entspricht, und die Feldwerte zur Implementierung dieser Konfiguration.
| Konfiguration | Scripted REST API | Geskriptete REST-Ressource | ||
|---|---|---|---|---|
| Standard-ACLs | Erfordert Authentifizierung | Erfordert ACL-Autorisierung | ACLs | |
| Die Ressource ist öffentlich. Keine Authentifizierung oder ACL erforderlich. | Beliebiger Wert | Falsch | Beliebiger Wert | Beliebiger Wert |
| Die Ressource erfordert nur die Standardauthentifizierung. Es ist keine ACL erforderlich. | Beliebiger Wert | wahr | Falsch | Beliebiger Wert |
| Die Ressource erfordert nur die Standardauthentifizierung. ACL ist erforderlich. | Keine ACL ausgewählt | wahr | wahr | Keine ACL ausgewählt |
| Eine im Ressourcendatensatz ausgewählte ACL ist erforderlich. | Beliebiger Wert | wahr | wahr | Mindestens eine ACLs ausgewählt |
| Eine im geskripteten REST-API-Datensatz ausgewählte ACL ist erforderlich. | Mindestens eine ACLs ausgewählt | wahr | wahr | Keine ACL ausgewählt |
Geskriptete REST-API-Fehlerobjekte
Geskriptete REST-APIs enthalten Fehlerobjekte, mit denen Sie auf eine Anforderung mit einer standardmäßigen HTTP-Fehlermeldung antworten können, wenn während der Anforderungsverarbeitung ein Fehler auftritt. Sie können Fehlerobjekte in geskripteten REST-API-Ressourcen verwenden, um anfordernde Clients auf Fehler zu warnen. Verwenden Sie Fehlerobjekte, um auf eingehende Anforderungen zu reagieren, nicht um Fehler in Ihrem serverseitigen Code zu erfassen.
Fehlerantwortformat
Der Inhaltstyp der Antwort hängt vom Anforderungs-Akzeptanzheader ab. Wenn der Accept-Header ein nicht unterstütztes Format angibt, z. B. Image/JPEG, verwendet die Fehlerantwort JSON.
{
"error": {
"message": "My error message",
"detail": "My details"
},
"status": "failure"
}Unterstützung für automatisiertes Test-Framework
Die Automatisiertes Test-Framework (ATF) unterstützt eingehende REST-Testschritte. Sie können automatisierte Tests für anwenderdefinierte eingehende REST-APIs erstellen, die Sie erstellen. Das Erstellen von Tests für Ihre anwenderdefinierten REST-APIs vereinfacht Upgradetests und ermöglicht es, sicherzustellen, dass Änderungen an einer REST-API abwärtskompatibel sind. Siehe REST-Testschrittkonfigurationen werden verwaltet Und ATF-REST-Testschrittkonfigurationen .
Entwicklerschulungen
In ServiceNow® Developer Site, Finden Sie Schulungen für Geskriptete REST-APIs .