Beispiel für Scripted REST APIs – Skriptbeispiele

Diese Beispiele zeigen, wie verschiedene Ressourcen-Skripts für eine geskriptete REST-API erstellt werden.

Beispiel für GET-Abfrageparameter

In diesem Beispiel wird veranschaulicht, wie Abfrageparameterwerte aus einer Anforderung abgerufen werden.

/**
 * GET - Sample Request API - Query Params
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var uri = request.uri;
    var url = request.url;
    var queryParams = request.queryParams;
    var customHeader = request.getHeader('X-Custom');

    return {
        "uri": uri,
        "url": url,
        "queryParams": queryParams,
        "customHeader": customHeader
    };

})(request, response);

Beispiel GET-Pfadparameter

In diesem Beispiel wird veranschaulicht, wie Pfadparameterwerte aus einer Anforderung abgerufen werden.

/**
 * GET - Sample Request API - Path Params
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var uri = request.uri;
    var url = request.url;
    var path = request.pathParams;

    return {
        "uri": uri,
        "url": url,
        "path_params": path,
        "path.id": path.id
    };
})(request, response);

Beispiel für GET-Skripteinbindung

In diesem Beispiel wird veranschaulicht, wie eine Skripteinbindung verwendet wird, um eine Antwort bereitzustellen. Durch die Verwendung einer Skripteinbindung können Sie allgemeinen Code wiederverwenden und die Lesbarkeit in den REST-Service-Skripts beibehalten.

/**
 * GET - Sample Request API - Script Include
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var responseObj = global.SampleDataUtil.getSampleJSON();
    return responseObj;
})(request, response);

Beispiel für POST-String

In diesem Beispiel wird veranschaulicht, wie eine POST-Nachricht mit einem Zeichenfolgentext analysiert wird, und basierend auf der Anforderung eine Antwort gesendet wird.

/**
 *  POST - Sample Request API - dataString
 *  sample usage:
 *  var requestBody = request.body;
 *  var requestString = requestBody.dataString;
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var requestBody = request.body;
    var requestString = requestBody.dataString;
    return {"requestString": requestString};
})(request, response);

Beispiel für binäres POST

In diesem Beispiel wird veranschaulicht, wie eine POST-Nachricht mit einem binären Hauptteil analysiert wird, und basierend auf der Anforderung eine Antwort gesendet wird.

/**
 * POST - Sample Request API - Body
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var body = request.body.data;
    //do any additional processing on the request body, such as inserting a new record.
    return {
        "body.id": body.id
    };
})(request, response);

Beispiel für inakzeptablen Fehler

Dieses Beispiel zeigt, wie Sie mit einem inakzeptablen Fehler antworten. Verwenden Sie diesen Fehlertyp, wenn der Accept-Kopfzeilenwert nicht vom Webservice unterstützt wird.

/**
 * Sample Not Acceptable Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    response.setError(new sn_ws_err.NotAcceptableError('sample error message'));
})(request, response);

Beispiel für fehlerhaften Anforderungsfehler

Dieses Beispiel zeigt, wie Sie mit einem fehlerhaften Anforderungsfehler antworten. Verwenden Sie diesen Fehlertyp, um einen Fehler in der Anforderungssyntax anzuzeigen.

/**
 * Bad Request Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    response.setError(new sn_ws_err.BadRequestError('sample error message'));
})(request, response);

Beispiel für Konfliktfehler

Dieses Beispiel zeigt, wie Sie mit einem Konfliktfehler antworten. Verwenden Sie diesen Fehlertyp bei mehreren in Konflikt stehenden Anforderungen, z. B. bei mehreren Aktualisierungen desselben Datensatzes.

/**
 * Error Response: Conflict Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    response.setError(new sn_ws_err.ConflictError('sample error message'));
})(request, response);

Beispiel für Fehler nicht gefunden

Dieses Beispiel zeigt, wie Sie mit einem nicht gefundenen Fehler antworten. Verwenden Sie diesen Fehlertyp, wenn die angeforderte Ressource nicht vorhanden oder nicht verfügbar ist.

/**
 * Error Response: Not Found Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    response.setError(new sn_ws_err.NotFoundError('sample error message'));
})(request, response);

Beispiel für nicht unterstützten Medientypfehler

In diesem Beispiel wird veranschaulicht, wie Sie mit einem nicht unterstützten Medientypfehler antworten. Verwenden Sie diesen Fehlertyp, um anzugeben, dass der Content Typ der Anforderung nicht unterstützt wird.

/**
 * Error Response: Unsupported Media Type Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    response.setError(new sn_ws_err.UnsupportedMediaTypeError('sample error message'));
})(request, response);

Beispiel für Servicefehler

In diesem Beispiel wird veranschaulicht, wie Sie mit einem generischen Servicefehler antworten. Mit dem Objekt „ServiceError“ können Sie Statuscode, Meldung und Fehlerdetail definieren. Verwenden Sie ein Objekt „ServiceError“, wenn die vordefinierten Fehlertypen Ihren Anforderungen nicht entsprechen.

/**
 * Error Response: Custom Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var myError = new sn_ws_err.ServiceError();
    myError.setStatus(418);
    myError.setMessage("I am a Teapot");
    myError.setDetail("Here are the details about this error");
    response.setError(myError);
})(request, response);

Beispiel für Fehler in Klammern für Funktion

Dieses Beispiel zeigt, dass ein Fehler auftritt, wenn eine Funktion nicht in Klammern eingeschlossen wird. Schließen Sie Klammern in alle Funktionen ein.

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
	gs.info("message: {0}", request.body.data.message);
})(request, response);

function test() {
	gs.info("test");
}(request, response);

Beispiel für einen Serialisierungsfehler

In diesem Beispiel wird veranschaulicht, dass ein Serialisierungsfehler auftreten kann, wenn die Anforderung als Textkörper für die Antwort festgelegt wird.

setBody_request:
    response.setBody(request);

In diesem Beispiel wird veranschaulicht, dass ein Serialisierungsfehler auftreten kann, wenn die Antwort als Textkörper für die Antwort festgelegt wird.

setBody_response:
    response.setBody(response);

In diesem Beispiel wird gezeigt, dass es zu einem Serialisierungsfehler kommen kann, wenn die Anforderung zurückgegeben wird.

return_request:
    return request;

In diesem Beispiel wird gezeigt, dass die Rückgabe der Antwort zu einem Serialisierungsfehler führen kann.

return_response:
    return response;

Beispiel für ein Skript für geskriptete REST-Ressourcen

Dieses Beispielskript für eine REST-API-Ressource analysiert die Werte name und id aus dem Anforderungstext und gibt diese Werte in der Antwort zurück.

/**
 * POST - Sample Request API - Body
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
var body = request.body.data,
id0,name0,id1,name1;
name0 = body[0].name; // 'user0'
id0 = body[0].id; // '1234'
name1 = body[1].name; // 'user1'
id1 = body[1].id; // '5678'

return {
"id": id0,
"name": name0,
"id1": id1,
"name1": name1
};
})(request, response);

Anforderungen

Die API kann sowohl XML- als auch JSON-Anforderungen verarbeiten.

Tabelle : 1. Anforderungen

JSON-Anforderung	XML-Anforderung
POST /api/sn_demo_api/v1/example/body HTTP/1.1 Content-Type: application/json Accept: application/json Host: <instance>.service-now.com Connection: close Content-Length: 91 [ { "name": "user0", "id": 1234 }, { "name": "user1", "id": 5678 } ]	POST /api/sn_demo_api/v1/example/body HTTP/1.1 Content-Type: application/xml Accept: application/json Host: <instance>.service-now.com Connection: close Content-Length: 152 <request><entry> <name>user0</name> <id>1234</id> </entry> <entry> <name>user1</name> <id>5678</id> </entry> </request>

Antworten

Beide Anforderungen geben „application/json“ als Accept-Kopfzeilenwert an. Dies bewirkt, dass beide Antworten die JSON-Formatierung verwenden, auch wenn der Anforderungs-Content-Typ „XML“ ist.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 04 Aug 2015 15:20:44 GMT
Server: ServiceNow
Connection: close
Set-Cookie: BIGipServerpool_<Instance>=880838154.47166.0000; path=/

{"result":{"id":1234,"id1":5678,"name":"user0","name1":"user1"}}