Scripted REST APIs

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 5 Minuten Lesedauer

    • Mit der Funktion „Scripted REST APIs“ können Anwendungsentwickler benutzerdefinierte Webservice-APIs erstellen.

    Sie können Serviceendpunkte, Abfrageparameter und Kopfzeilen für eine geskriptete REST-API sowie Skripts definieren, um die Anforderung und Antwort zu verwalten.

    Scripted REST APIs folgen im Allgemeinen der REST-Architektur, Sie können sie jedoch anpassen, um andere Konventionen zu verwenden. Geskriptete REST-APIs definieren Sie mit dem Formular „Geskripteter REST-Service“, das sich unter Geskriptete Webservices → Geskriptete REST-APIs befindet.

    Abbildung : 1. Geskriptetes Formular für REST-Service
    Geskriptetes Formular für REST-Service
    Die folgenden Videos bieten zusätzliche Informationen zu geskripteten REST-APIs:

    Scripted REST API-URIs

    Scripted REST API-URIs haben das folgende Format:

    https://<instance.service-now.com> /api/<name_space> /<version> /<api_id> /<relative_path>

    In diesem URI:
    • <instance.service-now.com>: Pfad zur Instanz ServiceNow, in der Benutzer auf die geskriptete REST-API zugreifen.
    • <name_space>: Für Webservices im globalen Bereich ist der Namespace 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 Namespaces 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 des Felds API-ID 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 /{id} angeben, wenn der Webservice nur über eine GET-Ressource verfügt, oder /user/{id} und /message/{id} angeben, wenn der Webservice über unterschiedliche Ressourcen zum Anfordern von Benutzer- und Nachrichtendatensätzen verfügt .

    Versionsverwaltung für Scripted REST APIs

    Scripted 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 die vorhandenen Integrationen zu beeinträchtigen.

    Standard-API-Version

    Eine Version kann als Standard markiert sein. Durch die Angabe einer Standardversion können Benutzer ü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.

    Scripted REST API-Ressourcen

    Eine geskriptete REST-API-Ressource entspricht einem REST-Endpunkt. Sie definiert die auszuführende HTTP-Methode, das Verarbeitungsskript und alle Überschreibungseinstellungen der übergeordneten API. Sie können eine oder mehrere Ressourcen pro API definieren.

    Abfrageparameter für Scripted REST APIs

    Abfrageparameter definieren Werte, die anfordernde Benutzer in einer Anforderung übergeben können. Beim Erstellen einer geskripteten REST-API können Sie angeben, welche Parameter verfügbar sind und welche für jede Anforderung obligatorisch sind. Sie können einen Abfrageparameter auch mehreren Ressourcen zuordnen.

    Greifen Sie über das Anforderungsobjekt im Feld queryParams auf Anforderungsparameter in Skripts zu.

    Scripted REST API-Rollen

    Um mit geskripteten REST-APIs arbeiten zu können, benötigen Sie die Rolle „Webservice-Administrator“ [web_service_admin]. Benutzer mit dieser Rolle können geskriptete REST-APIs und Webservice-Ressourcen lesen, erstellen, ändern und löschen.
    Hinweis:
    Diese Rollen sind nicht erforderlich, um auf einen geskripteten REST-API-Endpunkt zuzugreifen.

    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, die Standardwerte werden durch eine einzelne Ressource überschrieben.

    Sicherheit für Scripted REST APIs

    Sie können Ihre geskripteten REST-APIs mit der erforderlichen Sicherheitsstufe konfigurieren. Von öffentlichen APIs/Endpunkten, die keine Sicherheit erfordern, bis hin zu hochsicheren APIs/Endpunkten, die eine Benutzerauthentifizierung mit strenger Zugriffskontrolle 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

    Zugriffskontrolllisten (ACLs) definieren Kriterien, z. B. die erforderlichen Rollen und Bedingungen, die ein Benutzer 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.

    Hinweis:
    Standardmäßig enthalten Scripted REST APIs eine ACL, die Benutzern mit der Rolle „snc_external“ untersagt, Anforderungen an die API zu stellen.

    Beim Definieren einer geskripteten REST-API-ACL muss diese den TypwertREST_Endpointhaben.

    Weitere Informationen zu ACLs finden Sie unter Zugriffskontrolllistenregeln 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.

    Tabelle : 1. Sicherheit für Scripted REST APIs
    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.

    Fehlerantworten folgen diesem Format:
    {
  "error": {
    "message": "My error message",
    "detail": "My details"  
  },  
  "status": "failure"
}
    Der numerische Statuscode wie 404 ist im Antwortstatuscode-Header enthalten, nicht im Antworttext.

    Unterstützung von Automated Test Framework

    Das 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

    Unter ServiceNow® Developer Sitefinden Sie Schulungen für Scripted REST APIs.