API par lots
L’API Batch fournit des points de terminaison pour envoyer une seule demande contenant plusieurs appels d’API REST et renvoie un flux de charges utiles de réponse.
Cette API REST permet aux intégrateurs :
- Réduisez le temps nécessaire à l’envoi des demandes d’API en les regroupant et réduisez les frais généraux en limitant l’authentification, la configuration de session et le trafic aller-retour à une seule étape.
- Créez un code plus efficace pour les intégrations côté client.
- Mélangez les formats d’éléments par lots et incluez-les dans une demande par lots unique. Par exemple, un lot peut inclure une demande codée Bases64 au format XML à envoyer à un point de terminaison et une demande codée Base64 au format JSON à envoyer à un point de terminaison différent.
- Recevez un flux de charges utiles de réponse en retour.
- Appliquez les ACL existantes à chaque appel d’API dans le lot.
Vous pouvez inclure n’importe quelle API disponible sur l’instance dans un appel d’API Batch . Pour des raisons de performance, évitez d’inclure des requêtes de longue durée et des requêtes qui récupèrent de grandes quantités de données.
Important :
L’API Batch présente les mêmes caractéristiques de performance que les demandes d’API individuelles, mais évite la surcharge de plusieurs requêtes client-serveur. L’API Batch n’est pas destinée au traitement des transactions parallèles et les demandes d’API de longue durée peuvent entraîner un dépassement du temps de transaction maximal et entraîner un échec.
Taille et limites de traitement
Les charges utiles respectent les limites de taille suivantes :
- Chaque élément de la demande : 5 Mo. Vous pouvez modifier cette valeur par défaut en mettant à jour la glide.rest.batch.max.inputSize propriété système. Valeur maximale : 10 Mo.
- Chaque élément de la réponse : 10 Mo. Vous pouvez modifier cette valeur par défaut en mettant à jour la glide.rest.batch.max.outputSize propriété système ou en ajoutant l’en-tête X-BATCHREQUEST-MAX-OUTPUT-SIZE à votre demande. La X-BATCHREQUEST-MAX-OUTPUT-SIZE valeur de l’en-tête ne peut pas dépasser la valeur de la propriété système.
Remarque :
Si une demande s’exécute pendant plus de 30 secondes, la règle de quota de REST Batch API request timeout transaction met fin à la transaction. L’augmentation de la valeur de cette règle de quota de transaction peut entraîner des problèmes de performances.
Lorsqu’une demande par lots atteint une limite de taille ou de traitement, le système annule la transaction et renvoie les demandes non traitées dans le tableau JSON non traité de la réponse.
Lot : POST /now/batch
Envoie plusieurs demandes d’API REST en un seul appel.
Vous pouvez inclure n’importe quelle API disponible sur l’instance dans un appel d’API Batch . Pour des raisons de performance, évitez d’inclure des requêtes de longue durée et des requêtes qui récupèrent de grandes quantités de données.
Format d'URL
URL versionnée : /api/now/{api_version}/batch
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| api_version | Facultatif. Version du point de terminaison auquel accéder. Exemple : v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière. Type de données : chaîne |
| Nom | Description |
|---|---|
| Néant |
| Nom | Description |
|---|---|
| batch_request_id | ID qui identifie le lot de demandes. Type de données : chaîne |
| rest_requests | Requis. Liste des objets de demande à inclure dans la demande par lots. Type de données : tableau |
| rest_requests.corps | Corps codé en base64 de la demande. S’applique uniquement aux méthodes qui nécessitent un corps, par exemple POST. Avant l’encodage, le corps peut être dans n’importe quel format. Par exemple, XML ou JSON. Type de données : chaîne |
| rest_requests.exclude_response_headers | Marqueur indiquant si les en-têtes de réponse doivent être exclus de la réponse. Valeurs valides :
Type de données : booléennes Valeur par défaut : false |
| rest_requests.en-têtes | Liste des objets d’en-tête de demande à envoyer au point de terminaison. Type de données : tableau |
| rest_requests.en-têtes.nom | Nom de l’en-tête. Type de données : chaîne |
| rest_requests.en-têtes.valeur | Valeur de l’en-tête. Type de données : chaîne |
| rest_requests.id | Requis. ID de chaque élément du lot. Type de données : chaîne |
| rest_requests.méthode | Requis. Méthode d’appel pour le point de terminaison associé. Type de données : chaîne |
| rest_requests.url | Requis. Chemin d’accès relatif du point de terminaison auquel envoyer la requête. Inclut les paramètres de requête. Type de données : chaîne |
En-têtes
Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir une liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Prend uniquement en charge application/json. |
| Type de contenu | Format de données du corps de la demande. Prend uniquement en charge application/json. |
| X-BATCHREQUEST-MAX-OUTPUT-SIZE | Limite de taille pour chaque élément de la réponse par lots. Ajoutez cet en-tête pour fournir une limite de taille inférieure à la valeur par défaut définie par la glide.rest.batch.max.outputSize propriété système. Vous ne pouvez pas définir une valeur supérieure à la valeur de la propriété système. Valeur par défaut : 10 Mo. |
| En-tête | Description |
|---|---|
| Aucun |
Codes d'état
Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir une liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été correctement traitée. |
| 401 | Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises. |
| 500 | Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur. |
Paramètres de corps de réponse (JSON)
| Nom | Description |
|---|---|
| batch_request_id | ID du lot qui correspond au batch_request_id paramètre dans la demande. Type de données : chaîne |
| serviced_requests | Liste des objets de réponse de la demande par lots. Type de données : tableau |
| serviced_requests.corps | Corps codé en base64 de la réponse. Pour obtenir la valeur du corps, décodez en base64 le contenu de ce paramètre. Type de données : chaîne |
| serviced_requests.message_d’erreur | S’ils sont présents, les messages d’erreur. Type de données : chaîne |
| serviced_requests.execution_time | Temps nécessaire à l’exécution de la demande d’élément par lots. Type de données : nombre Unité : millisecondes |
| serviced_requests.en-têtes | En-têtes pour l’élément de lot. Type de données : tableau |
| serviced_requests.en-têtes.name | Nom de l’en-tête. Type de données : chaîne |
| serviced_requests.en-têtes.valeur | Valeur de l’en-tête. Type de données : chaîne |
| serviced_requests.id | ID de l’élément de lot qui correspond au rest_requests.id paramètre dans la demande. Type de données : chaîne |
| serviced_requests.redirect_url | Si elle est présente, l’URL de redirection. Type de données : chaîne |
| serviced_requests.code_état | Code d’état de l’élément par lots. Type de données : nombre |
| serviced_requests.texte_état | Texte du code d’état de l’élément de lot. Type de données : chaîne |
| unserviced_requests | ID des demandes qui n’ont pas été traitées, car la demande par lots a atteint une taille ou une limite de traitement. Type de données : tableau |
Demande cURL
Cette demande par lots envoie deux demandes GET à l’instance et une demande POST à la table d’incidents. Le corps de la demande POST est codé en Base64.
curl "https://instance.servicenow.com/api/now/v1/batch" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user "username":"password"\
--data "{
\"batch_request_id\":\"1\",
\"rest_requests\":[
{
\"id\":\"11\",
\"headers\":[
{
\"name\":\"Content-Type\",
\"value\":\"application/xml\"
},
{
\"name\":\"Accept\",
\"value\":\"application/xml\"
}
],
\"url\":\"/api/global/user_role_inheritance\",
\"method\":\"GET\"
},
{
\"id\":\"12\",
\"exclude_response_headers\":true,
\"headers\":[
{
\"name\":\"Content-Type\",
\"value\":\"application/json\"
},
{
\"name\":\"Accept\",
\"value\":\"application/json\"
}
],
\"url\":\"/api/now/table/incident?sysparm_limit=1\",
\"method\":\"GET\"
},
{
\"id\":\"13\",
\"exclude_response_headers\":true,
\"headers\":[
{
\"name\":\"Content-Type\",
\"value\":\"application/json\"
},
{
\"name\":\"Accept\",
\"value\":\"application/json\"
}
],
\"url\": \"/api/now/table/incident\",
\"method\":\"POST\",
\"body\": \"eyd1cmdlbmN5JzonMScsICdzaG9ydF9kZXNjcmlwdGlvbic6J015IGNvbXB1dGVyIG
Jyb2tlJywgJ2NvbW1lbnRzJzonRWxldmF0aW5nIHVyZ2VuY3ksIHRoaXMgaXMgYSBibG9ja2luZyBpc3N1ZSd9\"
}
]
}" \{
"batch_request_id": "1",
"serviced_requests": [
{
"id": "11",
"body": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cmVzcG9uc2U+PHJlc3VsdD48dX
Nlcl9uYW1lLz48L3Jlc3VsdD48L3Jlc3BvbnNlPg==",
"status_code": 200,
"status_text": "OK",
"headers": [
{
"name": "Pragma",
"value": "no-store,no-cache"
},
{
"name": "Expires",
"value": "0"
},
{
"name": "Content-Length",
"value": "88"
},
{
"name": "Content-Type",
"value": "application/xml; charset=UTF-8"
},
{
"name": "Cache-control",
"value": "no-cache,no-store,must-revalidate,max-age=-1"
}
],
"execution_time": 5
},
{
"id": "12",
"body": "eyJyZXN1bHQiOlt7InBhcmVudCI6IiIsIm1hZGVfc2xhIjoidHJ1ZSIsImNhdXNlZF9
ieSI6IiIsIndhdGNoX2xpc3QiOiIiLCJ1cG9uX3JlamVjdCI6ImNhbmNlbCIsInN5c191cGRhdGV
kX29uIjoiMjAxNi0xMi0xNCAwMjo0Njo0NCIsImNoaWxkX2luY2lkZW50cyI6IjAiLCJob2xkX3J
lYXNvbiI6IiIsInRhc2tfZWZmZWN0aXZlX251bWJlciI6IklOQzAwMDAwNjAiLCJhcHByb3ZhbF9
oaXN0b3J5IjoiIiwibnVtYmVyIjoiSU5DMDAwMDA2MCIsInJlc29sdmVkX2J5Ijp7ImxpbmsiOiJ
odHRwczovL2s4czAwNjc5Nzgtbm9kZTEudGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGk
vbm93L3RhYmxlL3N5c191c2VyLzUxMzcxNTNjYzYxMTIyN2MwMDBiYmQxYmQ4Y2QyMDA3IiwidmF
sdWUiOiI1MTM3MTUzY2M2MTEyMjdjMDAwYmJkMWJkOGNkMjAwNyJ9LCJzeXNfdXBkYXRlZF9ieSI
6ImVtcGxveWVlIiwib3BlbmVkX2J5Ijp7ImxpbmsiOiJodHRwczovL2s4czAwNjc5Nzgtbm9kZTE
udGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGkvbm93L3RhYmxlL3N5c191c2VyLzY4MWN
jYWY5YzBhODAxNjQwMGI5OGEwNjgxOGQ1N2M3IiwidmFsdWUiOiI2ODFjY2FmOWMwYTgwMTY0MDB
iOThhMDY4MThkNTdjNyJ9LCJ1c2VyX2lucHV0IjoiIiwic3lzX2NyZWF0ZWRfb24iOiIyMDE2LTE
yLTEyIDE1OjE5OjU3Iiwic3lzX2RvbWFpbiI6eyJsaW5rIjoiaHR0cHM6Ly9rOHMwMDY3OTc4LW5
vZGUxLnRodW5kZXIubGFiMy5zZXJ2aWNlLW5vdy5jb20vYXBpL25vdy90YWJsZS9zeXNfdXNlcl9
ncm91cC9nbG9iYWwiLCJ2YWx1ZSI6Imdsb2JhbCJ9LCJzdGF0ZSI6IjciLCJyb3V0ZV9yZWFzb24
iOiIiLCJzeXNfY3JlYXRlZF9ieSI6ImVtcGxveWVlIiwia25vd2xlZGdlIjoiZmFsc2UiLCJvcmR
lciI6IiIsImNhbGVuZGFyX3N0YyI6IjEwMjE5NyIsImNsb3NlZF9hdCI6IjIwMTYtMTItMTQgMDI",
"status_code": 200,
"status_text": "OK",
"headers": [],
"execution_time": 8
},
{
"id": "13",
"body": "eyJyZXN1bHQiOnsicGFyZW50IjoiIiwibWFkZV9zbGEiOiJ0cnVlIiwiY2F1c2VkX2J
5IjoiIiwid2F0Y2hfbGlzdCI6IiIsInVwb25fcmVqZWN0IjoiY2FuY2VsIiwic3lzX3VwZGF0ZWR
fb24iOiIyMDIwLTA1LTEyIDAxOjQ0OjM1IiwiY2hpbGRfaW5jaWRlbnRzIjoiMCIsImhvbGRfcmV
hc29uIjoiIiwidGFza19lZmZlY3RpdmVfbnVtYmVyIjoiSU5DMDAxMDAwNCIsImFwcHJvdmFsX2h
pc3RvcnkiOiIiLCJudW1iZXIiOiJJTkMwMDEwMDA0IiwicmVzb2x2ZWRfYnkiOiIiLCJzeXNfdXB
kYXRlZF9ieSI6ImFkbWluIiwib3BlbmVkX2J5Ijp7ImxpbmsiOiJodHRwczovL2s4czAwNjc5Nzg
tbm9kZTEudGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGkvbm93L3RhYmxlL3N5c191c2V
yLzY4MTZmNzljYzBhODAxNjQwMWM1YTMzYmUwNGJlNDQxIiwidmFsdWUiOiI2ODE2Zjc5Y2MwYTg
wMTY0MDFjNWEzM2JlMDRiZTQ0MSJ9LCJ1c2VyX2lucHV0IjoiIiwic3lzX2NyZWF0ZWRfb24iOiI
yMDIwLTA1LTEyIDAxOjQ0OjM1Iiwic3lzX2RvbWFpbiI6eyJsaW5rIjoiaHR0cHM6Ly9rOHMwMDY
3OTc4LW5vZGUxLnRodW5kZXIubGFiMy5zZXJ2aWNlLW5vdy5jb20vYXBpL25vdy90YWJsZS9zeXN
fdXNlcl9ncm91cC9nbG9iYWwiLCJ2YWx1ZSI6Imdsb2JhbCJ9LCJzdGF0ZSI6IjEiLCJyb3V0ZV9
yZWFzb24iOiIiLCJzeXNfY3JlYXRlZF9ieSI6ImFkbWluIiwia25vd2xlZGdlIjoiZmFsc2UiLCJ",
"status_code": 201,
"status_text": "Created",
"headers": [],
"execution_time": 2638
}
],
"unserviced_requests": []
}