Scripted REST APIs

  • Freigeben Version: Xanadu
  • Aktualisiert 1. August 2024
  • 5 Minuten Lesedauer

    • Mit der geskripteten REST-API-Funktion können Anwendungsentwickler benutzerdefinierte Webservice-APIs erstellen.

    Sie können Serviceendpunkte, Abfrageparameter und Header für eine geskriptete REST API sowie Skripts zum Verwalten der Anforderung und Antwort definieren.

    Geskriptete REST APIs folgen im Allgemeinen der REST-Architektur. Sie können sie jedoch anpassen, um andere Konventionen zu verwenden. REST APIs mit Skript definieren Sie mit dem Formular Scripted REST Service (Skriptbasierter REST-Service) unter Scripted Web Services (Skriptbasierte Webservices) Scripted REST APIs(Skriptbasierte REST APIs).

    Abbildung : 1. Geskriptetes Formular für REST-Service
    Geskriptetes Formular für REST-Service
    Die folgenden Videos enthalten zusätzliche Informationen über geskriptete REST APIs:

    Scripted REST API-URIs

    Geskriptete REST-API-URIs weisen das folgende Format auf:

    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 Anwender auf die geskriptete REST-API zugreifen.
    • <name_space>: Bei 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 für den Zugriff, wenn die API Versionsverwaltung verwendet, z. B. v1. Sie können auf die Standardversion einer API mit Versionsverwaltung 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 eine GET-Ressource hat, oder /user/{id} und /message/{id}, wenn der Webservice unterschiedliche Ressourcen zum Anfordern von Anwender- und Nachrichtendatensätzen hat .

    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 Änderungen testen und bereitstellen, ohne dass sich dies auf vorhandene Integrationen auswirkt.

    Standard-API-Version

    Eine Version kann als Standard markiert sein. Wenn Sie eine Standardversion angeben, können Benutzer mit einem geskripteten REST-Endpunkt ohne Versionsnummer auf diese Version zugreifen. Wenn keine Version als Standard markiert ist, wird die aktuelle Version als Standard verwendet.

    Geskriptete REST-API-Ressourcen

    Eine geskriptete REST-API-Ressource entspricht einem REST-Endpunkt. Sie definiert die auszuführende HTTP-Methode, das Verarbeitungsskript und alle Überschreibungseinstellungen von 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 und welche für jede Anforderung obligatorisch sind. Sie können einen Abfrageparameter auch mehreren Ressourcen zuordnen.

    Greifen Sie in Skripts über das Anforderungsobjektfeld „queryParams“ auf Anforderungsparameter zu.

    Scripted REST API-Rollen

    Zur Arbeit mit geskripteten REST APIs benötigen Sie die Rolle „Webservice-Administrator“ [web_service_admin]. Benutzer mit dieser Rolle können geskriptete REST APIs und Webserviceressourcen 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, eine einzelne Ressource überschreibt die Standardwerte.

    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 zu hochsicheren APIs/Endpunkten, die eine Anwenderauthentifizierung mit strenger Zugriffssteuerung auf alle Ressourcen erfordern.

    Verwenden Sie die Funktion „API-Zugriffsrichtlinie“, um die Authentifizierungsmethode für die APIs zu steuern. Weitere Informationen finden Sie unter API access policy.

    Zugriffskontrollen für Scripted REST APIs

    Zugriffssteuerungslisten (Access Control Lists, 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.

    Wenn Sie eine geskriptete REST-API-ACL definieren, muss der Typ den Wert REST_Endpoint aufweisen.

    Weitere Informationen zu ACLs finden Sie unter Regeln für Zugriffssteuerungslisten 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 geskriptete REST APIs.