Exemple d’API REST scriptée : diffusion en continu et sérialisation d’objets
Ces exemples montrent comment envoyer une réponse JSON à l’aide de la diffusion en continu et de la sérialisation d’objets par défaut.
Streaming vs sérialisation d’objets
Lors de l’envoi d’une réponse, vous pouvez envoyer une réponse sous forme de flux ou sérialiser un objet. L’une ou l’autre approche présente des avantages et des inconvénients. Choisissez une technique en fonction des besoins de votre intégration.
En général, si l’objet de réponse est simple, qu’il peut être représenté au format XML ou JSON et qu’il est de taille constante, utilisez la sérialisation d’objet. Si vous utilisez un format autre que XML ou JSON ou si la taille de la réponse varie, utilisez la diffusion en continu.
Diffusion de la réponse
L’utilisation de réponses en continu offre des avantages en termes de temps de réponse, de performances de l’instance et de flexibilité du contenu, mais ajoute une complexité supplémentaire au script. Lorsque vous utilisez la diffusion en continu, vous êtes responsable du formatage de la réponse, de la définition de l’état de la réponse et de la définition de l’en-tête Content-Type. Lors de la diffusion d’une réponse, l’utilisateur demandeur reçoit une réponse rapidement, car il n’est pas nécessaire de créer la réponse complète avant de commencer la diffusion.
L’exemple suivant montre un script de ressource REST scripté qui renvoie un tableau d’enregistrements d’incidents à l’aide de la diffusion en continu.
/**
* Sample Scripted REST Resource that returns custom JSON objects with properties from Incident GlideRecords
* This sample uses ServiceNow JavaScript API to query incident records
* and then iterates over those records to build and stream a custom JSON object that
* includes some values from the incidents
*/
(function runOperation(/*RESTServiceRequest*/ request, /*RESTServiceResult*/ response) {
var writer = response.getStreamWriter(),
hdrs = {},
table = 'incident',
record_limit = 100,
gr = new GlideRecord(table);
hdrs['Content-Type'] = 'application/json';
response.setStatus(200);
response.setHeaders(hdrs);
gr.setLimit(record_limit);
gr.query();
// start building response object
writer.writeString("{\"results\":[");
// iterate over incident records and build JSON representations to be streamed out.
while (gr.next()) {
var incidentObj = {};
incidentObj.number = gr.number + '';
incidentObj.short_description = gr.short_description + '';
writer.writeString(global.JSON.stringify(incidentObj));
if (gr.hasNext()) {
writer.writeString(",");
}
}
// close the response object
writer.writeString("]}");
})(request, response);
Une demande adressée à cette ressource renvoie la réponse suivante.
// sample response
/*
HTTP/1.1 200 OK
Content-Type: application/json
Server: ServiceNow
// sample response number of records returned has been truncated for this example
{
"results": [
{
"number": "INC0011301",
"short_description": "lorem ipsum short description 0 my new incident"
},
{
"number": "INC0011302",
"short_description": "lorem ipsum short description 1 my new incident"
},
{
"number": "INC0011303",
"short_description": "lorem ipsum short description 2 my new incident"
},
{
"number": "INC0011304",
"short_description": "lorem ipsum short description 3 my new incident"
},
{
"number": "INC0011309",
"short_description": "lorem ipsum short description 8 my new incident"
},
{
"number": "INC0011310",
"short_description": "lorem ipsum short description 9 my new incident"
},
{
"number": "INC0011311",
"short_description": "lorem ipsum short description 0 my new incident"
},
{
"number": "INC0011312",
"short_description": "lorem ipsum short description 1 my new incident"
},
{
"number": "INC0011313",
"short_description": "lorem ipsum short description 2 my new incident"
},
{
"number": "INC0011314",
"short_description": "lorem ipsum short description 3 my new incident"
},
{
"number": "INC0011315",
"short_description": "lorem ipsum short description 4 my new incident"
},
{
"number": "INC0011326",
"short_description": "lorem ipsum short description 15 my new incident"
}
]
}
*/
Pagination de diffusion
Pour paginer des tables volumineuses afin d’envoyer uniquement un nombre limité d’enregistrements par requête, utilisez la GlideRecord dans le champ d’application/global : chooseWindow(Number firstRow, Number lastRow, Boolean forceCount) méthode. L’article de la communauté Paginated Glide Record + Expanded GR Method Support illustre comment utiliser chooseWindow() pour réaliser la pagination, que vous pouvez adapter à votre cas d’utilisation particulier.
Création d’un objet
L’utilisation de la sérialisation d’objets vous permet de tirer parti de la sérialisation et de la négociation de contenu fournies par ServiceNow. Lors de la sérialisation d’un objet au lieu d’une diffusion, l’objet entier doit être créé et sérialisé avant que le client ne reçoive une réponse. Cela peut retarder la réponse ou nécessiter une grande quantité de ressources système si l’objet de réponse est très volumineux. La sérialisation d’objets n’est disponible que pour les réponses XML ou JSON. Les réponses utilisant un format différent doivent utiliser la diffusion en continu.
Cet exemple renvoie les mêmes données d’incident que l’exemple de diffusion en continu, mais collecte toutes les données de réponse dans un tableau avant d’envoyer la réponse.
/**
* Sample Scripted REST Resource returns an array of custom JSON objects that include 2 incident properties.
* This sample uses ServiceNow JavaScript API to query incident records and then iterates
* over those records building a custom JSON object that includes 2 values from the incident records.
* note that because we are returning a simple JSON object we can rely on built in serialization
* to set the content-type header as well as response status. The 'result_arr' object will not be returned
* until it has been completely built and stored
*/
(function runOperation(/*RESTServiceRequest*/ request, /*RESTServiceResult*/ response) {
var table = 'incident',
record_limit = 100,
result_arr = [],
gr = new GlideRecord(table);
gr.setLimit(record_limit);
gr.query();
// iterate over incident records and build JSON representations to be streamed out.
while (gr.next()) {
var incidentObj = {};
incidentObj.number = gr.number + '';
incidentObj.short_description = gr.short_description + '';
result_arr.push(incidentObj);
}
return result_arr;
})(request, response);
Une demande adressée à cette ressource renvoie la réponse suivante.
/*
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Server: ServiceNow
// sample response number of records returned has been truncated for this example
{
"result": [{
"short_description": "lorem ipsum short description 0 my new incident",
"number": "INC0011301"
}, {
"short_description": "lorem ipsum short description 1 my new incident",
"number": "INC0011302"
}, {
"short_description": "lorem ipsum short description 2 my new incident",
"number": "INC0011303"
}, {
"short_description": "lorem ipsum short description 3 my new incident",
"number": "INC0011304"
}, {
"short_description": "lorem ipsum short description 4 my new incident",
"number": "INC0011305"
}, {
"short_description": "lorem ipsum short description 5 my new incident",
"number": "INC0011306"
}, {
"short_description": "lorem ipsum short description 6 my new incident",
"number": "INC0011307"
}, {
"short_description": "lorem ipsum short description 7 my new incident",
"number": "INC0011308"
}, {
"short_description": "lorem ipsum short description 8 my new incident",
"number": "INC0011309"
}, {
"short_description": "lorem ipsum short description 9 my new incident",
"number": "INC0011310"
}]
}
*/