Exemple d’API REST scriptée : diffusion en continu par rapport à la 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.
Diffusion en continu et sérialisation d’objets
Lors de l’envoi d’une réponse, vous pouvez envoyer une réponse en tant que flux ou sérialiser un objet. Il y a des avantages et des inconvénients à l’une ou l’autre approche. Choisissez une technique en fonction des besoins de votre intégration.
En règle générale, si l’objet de réponse est simple, peut être représenté au format XML ou JSON et a une 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 d’instance et de flexibilité de 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 du type de contenu. 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 l’intégralité de la réponse avant de commencer la diffusion.
Cet exemple illustre un script de ressource REST scripté qui renvoie un tableau d’enregistrements d’incidents en utilisant 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 à 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 en continu
Pour paginer les tables volumineuses afin de n’envoyer qu’un nombre limité d’enregistrements par requête, utilisez la GlideRecord inclus dans le champ d’application : 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 obtenir la pagination, que vous pouvez adapter à votre propre 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 de la 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’objet 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, 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 à 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"
}]
}
*/