---
sourceDocument: Yokohama-API-Referenz
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/de-DE/yokohama/api-reference

 Release :

    - yokohama

ft:locale :

    - de-DE

ft:publication_title :

    - Yokohama-API-Referenz

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Scripted REST APIs

# Scripted REST APIs {#ariaid-title1}

* Freigeben Version: Yokohama
* 
* Aktualisiert 30. Januar 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 Minuten Lesedauer

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 .  
Abbildung : 1. Geskriptetes REST-Service-Formular  
Die folgenden Videos bieten zusätzliche Informationen zu geskripteten REST-APIs:

* [Geskriptete REST-APIs -- Design](https://www.youtube.com/watch?v=Tw70sHgDc-w)
* [Geskriptete REST-APIs: Implementierung](https://www.youtube.com/watch?v=LFHV-Qk1-Yk)
{#c_CustomWebServices__ul_bjx_c3b_vzb}

## Geskriptete REST-API-URIs {#c_CustomWebServices__section_upf_pn4_zhb}

Geskriptete 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 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](https://www.servicenow.com/docs/access?context=c_ApplicationScope&version=yokohama&pubname=yokohama-application-development&ft:locale=en-US).
* \<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.
{#c_CustomWebServices__ul_osv_kgc_lr}

## Skriptbasierte REST-API-Versionsverwaltung {#c_CustomWebServices__section_pnw_c44_zhb}

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 {#c_CustomWebServices__section_jgj_b44_zhb}

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 {#c_CustomWebServices__section_fhh_3nw_23b}

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 {#c_CustomWebServices__section_tfl_444_zhb}

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 {#c_CustomWebServices__section_y5m_xx4_zhb}

Um mit geskripteten REST-APIs zu arbeiten, müssen Sie über die Rolle „Webservice-Administrator" \[Web_Service_admin\] verfügen. Anwender 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 {#c_CustomWebServices__section_p3s_fkw_23b}

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 {#c_CustomWebServices__section_txq_hx4_zhb}

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](https://www.servicenow.com/docs/access?context=api-access-policy&version=yokohama&pubname=yokohama-platform-security&ft:locale=en-US).

## Geskriptete REST-API-Zugriffssteuerungen {#c_CustomWebServices__section_rbc_zz4_zhb}

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.  
Hinweis:  
Standardmäßig enthalten geskriptete REST-APIs eine ACL, die Anwender mit der Rolle „snc_external" daran hindert, Anforderungen an die API zu stellen.

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](https://www.servicenow.com/docs/access?context=access-control-rules&version=yokohama&pubname=yokohama-platform-security&ft:locale=en-US)Und [Konfigurieren Sie eine geskriptete REST-API-Ressource, um eine ACL zu erfordern](https://servicenow-prod.fluidtopics.net/Zq0E_bLHZNKD3XtvY0M2OA "Standardmäßig übernehmen API-Ressourcen/Endpunkte Sicherheitseinstellungen von der übergeordneten API. Definieren Sie anwenderdefinierte ACLs für eine bestimmte Ressource/einen bestimmten Endpunkt, um die geerbten Einstellungen zu überschreiben.").

## Geskriptete REST-API-Sicherheitsmatrix {#c_CustomWebServices__section_xww_cgp_zhb}

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.
{#c_CustomWebServices__table_r2p_vbt_tr__entry__3}{#c_CustomWebServices__table_r2p_vbt_tr__entry__8}

| 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 |
[Tabelle : 1. Geskriptete REST-API-Sicherheit]

{#c_CustomWebServices__table_r2p_vbt_tr}

## Geskriptete REST-API-Fehlerobjekte {#c_CustomWebServices__section_xkj_5gp_zhb}

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 {#c_CustomWebServices__section_f2v_1hp_zhb}

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.  
Fehlerantworten folgen diesem Format:

    {
      "error": {
        "message": "My error message",
        "detail": "My details"  
      },  
      "status": "failure"
    }

Der numerische Statuscode, z. B. 404, ist im Header des Antwortstatuscodes enthalten, nicht im Antworttext.

## Unterstützung für automatisiertes Test-Framework

Die [Automatisiertes Test-Framework](https://www.servicenow.com/docs/access?context=automated-test-framework&version=yokohama&pubname=yokohama-application-development&ft:locale=en-US)(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](https://www.servicenow.com/docs/access?context=atf-administer-rest&version=yokohama&pubname=yokohama-application-development&ft:locale=en-US)Und [ATF-REST-Testschrittkonfigurationen](https://www.servicenow.com/docs/access?context=rest-test-steps&version=yokohama&pubname=yokohama-application-development&ft:locale=en-US).

## Entwicklerschulungen {#c_CustomWebServices__section_dk2_2cc_2hb}

In ServiceNow® Developer Site, Finden Sie Schulungen für [Geskriptete REST-APIs](https://developer.servicenow.com/app.do#!/training/article/app_store_learnv2_rest_paris_scripted_rest_apis/app_store_learnv2_rest_paris_scripted_rest_api_objectives?v=paris).
* **[Erstellen Sie eine geskriptete REST-API](https://servicenow-prod.fluidtopics.net/_Wormt2wt3mGLDNj1Zy7jQ)**   
  Erstellen Sie eine geskriptete REST-API, um Webservice-Endpunkte zu definieren.
* **[Bewährte Praktiken für geskriptete REST-APIs](https://servicenow-prod.fluidtopics.net/GA333wXXEfiCxenwwzJ4AQ)**   
  Befolgen Sie diese Richtlinien beim Entwerfen und Implementieren geskripteter REST-APIs.
* **[Geskriptete REST-API-Beispiele](https://servicenow-prod.fluidtopics.net/hYtoE7oY3FVOLlrHCojx6w)**   
  Es sind mehrere Beispiele verfügbar, die demonstrieren, wie geskriptete REST-APIs erstellt und verwendet werden.

