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 an verschiedene Konventionen anpassen. Sie definieren geskriptete REST-APIs mit dem Formular „Geskripteter REST-Service“ unter Geskriptete Webservices → Geskriptete REST-APIs .
Scripted 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 ServiceNow Instanz, in der Anwender auf die geskriptete REST-API zugreifen.
- <name_space>: Für Webservices im globalen Bereich ist der Namensbereich der Wert der Eigenschaft glide.appcreator.company.code. Für Webservices in einer bereichsbezogenen Anwendung ist der Namespace 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. Durch die Angabe eines relativen Ressourcenpfads 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.
Versionsverwaltung für Scripted REST APIs
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 Changes testen und bereitstellen, ohne sich auf vorhandene Integrationen auszuwirken.
Standard-API-Version
Eine Version kann als Standard markiert sein. Wenn Sie eine Standardversion angeben, können Anwender mit einem 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.
Abfrageparameter für Scripted REST APIs
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 in Skripts auf Anforderungsparameter zu QueryParams Feld.
Scripted 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.
Sicherheit für Scripted REST APIs
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.
Zugriffskontrollen für Scripted REST APIs
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 anfragender Benutzer muss mindestens eine der ACLs erfüllen. Es ist nicht notwendig, 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 Geskriptete REST-API-Ressourcen so konfigurieren, dass eine ACL erforderlich ist.
Sicherheitsmatrix für Scripted REST APIs
Es gibt mehrere mögliche Sicherheitskonfigurationen für Scripted REST APIs. Verwenden Sie diese Tabelle, um die Sicherheitskonfiguration für Scripted REST APIs zu ermitteln, die Ihren Anforderungen am besten entspricht, und die Feldwerte, um diese Konfiguration zu implementieren.
| Konfiguration | Scripted REST-API | Geskriptete REST-Ressource | ||
|---|---|---|---|---|
| Standard-ACLs | Erfordert Authentifizierung | Erfordert ACL-Autorisierung | ACLs | |
| Die Ressource ist öffentlich. Es ist keine Authentifizierung oder ACL erforderlich. | Beliebiger Wert | False | Beliebiger Wert | Beliebiger Wert |
| Die Ressource erfordert nur eine Basic Authentication. Es ist keine ACL erforderlich. | Beliebiger Wert | True | False | Beliebiger Wert |
| Die Ressource erfordert nur eine Basic Authentication. ACL ist erforderlich. | Keine ACL ausgewählt | True | True | Keine ACL ausgewählt |
| Eine im Ressourcendatensatz ausgewählte ACL ist erforderlich. | Beliebiger Wert | True | True | Eine oder mehrere ACLs ausgewählt |
| Eine im geskripteten REST-API-Datensatz ausgewählte ACL ist erforderlich. | Eine oder mehrere ACLs ausgewählt | True | True | Keine ACL ausgewählt |
Fehlerobjekte bei Scripted REST APIs
Scripted REST APIs enthalten Fehlerobjekte, mit denen Sie auf eine Anforderung mit einer HTTP-Standardfehlermeldung 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 hinzuweisen. Verwenden Sie Fehlerobjekte, um auf eingehende Anforderungen zu antworten, nicht um Fehler in Ihrem serverseitigen Code zu erfassen.
Fehlerantwortformat
Der Content-Typ der Antwort hängt von der Accept-Kopfzeile der Anforderung ab. Wenn die Accept-Kopfzeile ein nicht unterstütztes Format angibt, wie z. B. „image/jpeg“, wird in der Fehlerantwort JSON verwendet.
{
"error": {
"message": "My error message",
"detail": "My details"
},
"status": "failure"
}Unterstützung von Automated Test Framework
Die Automated Test Framework (ATF) unterstützt eingehende REST-Testschritte. Sie können automatisierte Tests für benutzerdefinierte Inbound-REST-APIs, die Sie erstellen, einrichten. Das Erstellen von Tests für Ihre benutzerdefinierten REST APIs vereinfacht das Testen von Upgrades und ermöglicht die Überprüfung, ob Änderungen an einer REST API abwärtskompatibel sind. Siehe REST-Testschrittkonfigurationen konfigurieren und ATF-REST-Testschrittkonfigurationen.
Entwicklerschulungen
In ServiceNow® Developer Site, Finden Sie Schulungen für Geskriptete REST-APIs .