SyntheticsBulkCreate API
L’API SyntheticsBulkCreate fournit un point de terminaison permettant de créer plusieurs moniteurs synthétiques en une seule opération synchrone.
- Surveillance post-incident : après la résolution d’un incident, créez des moniteurs pour les points de terminaison découverts afin d’éviter qu’il ne se reproduise.
- Intégration de service : établissez rapidement une surveillance de base de référence pour les nouveaux services ou applications.
- Fermeture de lacunes : créer des moniteurs pour les points de terminaison critiques non surveillés identifiés lors de la découverte.
- Workflows automatisés : intégrez-les aux workflows de gestion des incidents ou de découverte pour automatiser la mise en service du moniteur.
Utilisez cette API pour créer jusqu’à 50 moniteurs par demande. Pour créer plus de 50 moniteurs par demande, utilisez l’API SyntheticsAsyncBulkCreate .
Cette API nécessite l’application Synthetic monitoring (com.snc.uib.sow_synthetics), qui est disponible sur le ServiceNow Store. L’utilisateur appelant doit avoir le rôle x_snc_sow_synthetics.synthetics_editor. Avant d’appeler cette API, au moins un Serveur MID emplacement doit être configuré pour la surveillance synthétique. Pour obtenir des instructions, consultez Create synthetic monitoring locations. En outre, les éléments de configuration (CI) pour les points de terminaison surveillés doivent exister dans le Configuration Management Database (CMDB).
SyntheticsBulkCreate - POST /sn_sow_synthetics/synthetics_bulk_create
Crée plusieurs moniteurs synthétiques en une seule opération synchrone.
Utilisez ce point de terminaison pour les workflows pilotés par les incidents et les opérations par lots plus petits où une validation et des résultats immédiats sont requis. Ce point de terminaison prend en charge la création d’un maximum de 50 moniteurs par demande, avec une taille de charge utile maximale de 10 Mo.
Ce point de terminaison relie les moniteurs aux incidents pour l’observabilité post-incident et permet la sélection automatique Serveur MID d’un emplacement. Les points de terminaison sont évalués selon un processus en six phases : correspondance exacte de l’URL, points de terminaison du même hôte, points de terminaison du même sous-réseau, points de terminaison de la même région, tout emplacement disponible et retour aux valeurs par défaut. Cela garantit une couverture de surveillance optimale sans nécessiter d’affectation manuelle d’emplacement.
Format d'URL
URL avec version : /api/sn_sow_synthetics/{api_version}/synthetics_bulk_create
URL par défaut : /api/sn_sow_synthetics/synthetics_bulk_create
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| api_version | Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison autre que la plus récente. Type de données : chaîne |
| Nom | Description |
|---|---|
| Néant |
| Nom | Description |
|---|---|
| correlation_id | Requis. Identificateur de corrélation pour le suivi et la télémétrie qui relie tous les moniteurs créés dans la même demande. Vous pouvez utiliser gs.generateGUID() pour générer l’ID. Longueur maximale : 200 caractères Type de données : chaîne |
| Points de terminaison | Requis. Tableau d’objets de configuration de point de terminaison pour lesquels créer des moniteurs. Ce tableau peut contenir un maximum de 50 objets par demande d’API. Type de données : tableau |
| points de terminaison.corps | Corps de la demande pour les points de terminaison POST, PUT ou PATCH. Il doit s’agir d’une chaîne JSON ou XML valide selon l’en-tête du type de contenu . La taille maximale est de 10 Ko.Type de données : chaîne |
| points de terminaison.activé | Marqueur indiquant si le moniteur commencera à s’exécuter immédiatement après sa création. Valeurs valides :
Par défaut : true Type de données : booléennes |
| endpoints.endpoint_id | Requis. Sys_id de l’élément de configuration (CI) du CMDB point de terminaison. Table : Point de terminaison HTTP [cmdb_ci_endpoint_http] Type de données : chaîne |
| Points de terminaison.En-têtes | Tableau d’en-têtes HTTP que le moniteur doit inclure dans la demande de point de terminaison. Type de données : tableau Par défaut : tableau vide (pas d’en-tête) |
| endpoints.headers.name | Nom de l’en-tête HTTP, tel que Authorization ou Content-Type.Type de données : chaîne |
| points de terminaison.en-têtes.valeur | Valeur de l’en-tête HTTP, telle que jeton de porteur ou application/json.Type de données : chaîne |
| points de terminaison.intervalle | Fréquence d’exécution de la surveillance en minutes. ServiceNow Les emplacements hébergés sont limités à 6 tests par minute et par moniteur. Valeurs valides : 1-60 Par défaut : 5 (s’exécute une fois toutes les cinq minutes) Type de données : nombre |
| endpoints.max_latence_ms | Délai de réponse acceptable maximal en millisecondes. La directive générale est de 500 à 5000 ms selon le type de point final. Le moniteur vérifie cette valeur lors du test, et le test échoue si le délai de réponse dépasse cette valeur. Valeur par défaut : nul (aucun seuil de latence) Type de données : nombre |
| points de terminaison.méthode | Méthode HTTP à utiliser. Valeurs valides (insensibles à la casse) :
Par défaut : GET Type de données : chaîne |
| endpoints.name | Nom d’affichage du moniteur. Pour la création de moniteur pilotée par incident, un exemple de format est [INC{number}] {endpoint_name} - {service_name}.Longueur maximale : 100 caractères Par défaut : le nom du moniteur est automatiquement généré à partir du nom du point de terminaison. Type de données : chaîne |
| endpoints.parent_service_sys_id | Sys_id du service d’entreprise pris en charge par ce point de terminaison. Utilisé pour la génération de rapports sur le niveau de service et l’analyse de l’impact. Table : Service d’entreprise [cmdb_ci_service] Valeur par défaut : null Type de données : chaîne |
| endpoints.support_group_sys_id | Sys_id du groupe de support responsable de ce point de terminaison. Utilisé pour l’acheminement et l’affectation des alertes. Table : Groupe [sys_user_group] Valeur par défaut : null Type de données : chaîne |
| points de terminaison.url | Requis. URL HTTP ou HTTPS complète à surveiller. Doit commencer par http:// ou https://. Par exemple, https://api.example.com/health.Longueur maximale : 2048 caractères Type de données : chaîne |
| endpoints.valid_http_code | Codes d’état HTTP attendus pour une réponse réussie, fournis sous forme de valeur unique ou de liste séparée par des virgules, telle que « 200,201,204 ». Le moniteur vérifie ces valeurs lors du test, et le test échoue si le code d’état réel ne correspond pas à une valeur de la liste. Par défaut : 200 Type de données : chaîne |
| idempotency_key | Requis. Identificateur unique (clé) pour éviter la création d’un moniteur en double si la même demande API est soumise plusieurs fois. Les clés sont conservées dans le système pendant 24 heures. Format : n’importe quelle chaîne jusqu’à 200 caractères, comme le correlation_id ou le motif Type de données : chaîne |
| incident_id | Sys_id de l’incident qui a déclenché la création du moniteur. Utilisé pour le suivi et la corrélation dans l’analyse post-incident. S’ils sont fournis, les moniteurs créés sont liés à cet incident. Table : Incident [incident] Type de données : chaîne |
En-têtes
Les en-têtes de demande et de réponse suivants s’appliquent uniquement à cette action HTTP ou s’appliquent à cette action d’une manière distincte. Pour obtenir la 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. |
| Autorisation | Authentification de base HTTP ou jeton de porteur OAuth. Format d’authentification de base : Format OAuth : |
| Type de contenu | Format des données du corps de la demande. Prend uniquement en charge application/json. |
| En-tête | Description |
|---|---|
| Type de contenu | Format de données du corps de la réponse. Prend uniquement en charge application/json. |
| Recommencer après | Renvoyé avec le code de statut 503 . Nombre de secondes à attendre avant de réessayer la demande. |
| ID de demande X | Identificateur unique pour la demande d’API. Utilisé pour le dépannage et la corrélation des journaux. |
Codes d'état
Les codes d’état suivants s’appliquent à cette action HTTP. Pour obtenir la 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. Tous les moniteurs ou certains d’entre eux ont été créés. Vérifiez results le corps de la réponse pour connaître l’état de la création d’un moniteur individuel. |
| 400 | Demande incorrecte. Échec de la validation de la demande. Vérifiez error.code et error.message dans le corps de la réponse pour plus de détails sur l’erreur. Causes courantes :
|
| 401 | Non autorisé. Les informations d’identification de l’utilisateur sont incorrectes ou n’ont pas été transmises. |
| 403 | Interdit. L’utilisateur doit disposer du rôle x_snc_sow_synthetics.synthetics_editor pour créer des moniteurs. |
| 404 | Introuvable. Le chemin d’accès du point de terminaison de l’API est incorrect ou le module d’extension Surveillance synthétique n’est pas installé ou activé. |
| 413 | Charge utile trop importante. Le corps de la demande dépasse la limite de 10 Mo. Réduisez le nombre d’objets dans le tableau ou supprimez le contenu volumineux du corps de la endpoints demande. |
| 429 | Trop de demandes. Limite des taux dépassée, patientez et réessayez. Vérifiez error.details.retry_after_seconds le corps de la réponse pendant le nombre de secondes avant la réinitialisation de la fenêtre de limite de taux. L’utilisateur a dépassé l’un des éléments suivants :
|
| 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. |
| 503 | Service non disponible. Surveillance synthétique Service temporairement indisponible en raison d’une maintenance ou d’une charge élevée. Réessayez la demande après le délai indiqué dans l’en-tête Réessayer-après . |
Paramètres de corps de réponse (JSON)
| Nom | Description |
|---|---|
| erreur | Objet renvoyé en cas d’échec de la demande d’API. Type de données : objet |
| code.erreur | Code d’erreur. Valeurs possibles :
Type de données : chaîne |
| erreur.détails | Détails supplémentaires sur l’erreur. Les éléments inclus dans cet objet varient en fonction du type d’erreur. Type de données : objet |
| message.erreur | Message d’erreur. Type de données : chaîne |
| message | Message sur le résultat de la demande d’API. Type de données : chaîne |
| résultats | Tableau d’objets contenant le résultat de la création du moniteur pour chaque point de terminaison. Les résultats des points de terminaison sont répertoriés dans le même ordre que celui fourni dans le endpoints tableau du corps de la demande. Type de données : tableau |
| results.endpoint_id | Sys_id de l’élément de configuration (CI) du CMDB point de terminaison. Table : Point de terminaison HTTP [cmdb_ci_endpoint_http] Type de données : chaîne |
| results.error_code | Code d’erreur en cas d’échec de la création status du moniteur.Valeurs possibles :
Type de données : chaîne |
| results.error_message | Message d’erreur si la création status du moniteur a échoué.Type de données : chaîne |
| résultats.emplacement | Serveur MID Emplacement sélectionné pour le moniteur. Type de données : objet |
| results.location.name | Nom de l’emplacement Serveur MID . Type de données : chaîne |
| results.location.selection_phase | Numéro de phase utilisé pour sélectionner l’emplacement Serveur MID . Chaque point de terminaison est évalué par rapport aux phases suivantes, en commençant par la phase Valeurs possibles :
Type de données : nombre |
| results.location.sys_id | Sys_id de l’emplacement Serveur MID . Table : emplacement synthétique [sn_sow_synthetics_location] Type de données : chaîne |
| results.monitor_name | Nom d’affichage du moniteur créé. Type de données : chaîne |
| results.monitor_sys_id | Sys_id du moniteur créé. Table : Vérifier [sn_sow_synthetics_check] Type de données : chaîne |
| résultats.état | Surveillez l’état de création du point de terminaison. Valeurs possibles :
Type de données : chaîne |
| réussite | Marqueur indiquant si la demande d’API a réussi. Valeur possible : Remarque :
Ce paramètre n’est inclus que lorsque le code d’état de la réponse est 200 , cette valeur est donc toujours vraie.Type de données : booléennes |
| résumé | Objet résumant le résultat de la demande d’API. Type de données : objet |
| Résumé.Échec | Nombre de moniteurs qui n’ont pas pu être créés. Type de données : nombre |
| Résumé.Réussi | Nombre de moniteurs créés. Type de données : nombre |
| summary.total_requested | Nombre total de points de terminaison inclus dans la demande d’API. Type de données : nombre |
Demande cURL
Cet exemple crée des moniteurs pour trois points de terminaison HTTP détectés à partir d’un incident résolu.
curl -X POST 'https://instance.service-now.com/api/sn_sow_synthetics/bulk_create' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-u 'username:password' \
-d '{
"incident_id": "a1b2c3d4e5f6789012345678",
"idempotency_key": "INC-INC0012345-20260401T120000",
"correlation_id": "550e8400-e29b-41d4-a716-446655440000",
"endpoints": [
{
"endpoint_id": "e1f2g3h4i5j6789012345678",
"name": "[INC0012345] Payment API Health - Payment Gateway",
"url": "https://api.payment.example.com/health",
"method": "GET",
"interval": 2,
"enabled": true,
"parent_service_sys_id": "s1t2u3v4w5x6789012345678",
"support_group_sys_id": "g1h2i3j4k5l6789012345678",
"valid_http_code": "200",
"max_latency_ms": 500
},
{
"endpoint_id": "k1l2m3n4o5p6789012345678",
"name": "[INC0012345] Payment Transaction API - Payment Gateway",
"url": "https://api.payment.example.com/v2/transactions",
"method": "POST",
"interval": 5,
"enabled": true,
"parent_service_sys_id": "s1t2u3v4w5x6789012345678",
"support_group_sys_id": "g1h2i3j4k5l6789012345678",
"valid_http_code": "200,201",
"max_latency_ms": 1000,
"headers": [
{
"name": "Authorization",
"value": "Bearer test-token"
},
{
"name": "Content-Type",
"value": "application/json"
}
],
"body": "{\"amount\": 100, \"currency\": \"USD\"}"
},
{
"endpoint_id": "q1r2s3t4u5v6789012345678",
"name": "[INC0012345] Customer Portal Status - Payment Gateway",
"url": "https://portal.payment.example.com/status",
"method": "GET",
"interval": 10,
"enabled": true,
"parent_service_sys_id": "s1t2u3v4w5x6789012345678",
"valid_http_code": "200"
}
]
}'Corps de la réponse : tous les moniteurs créés avec succès.
{
"success": true,
"message": "Bulk creation completed. 3 monitors created successfully, 0 failed validation.",
"summary": {
"total_requested": 3,
"successful": 3,
"failed": 0
},
"results": [
{
"endpoint_id": "e1f2g3h4i5j6789012345678",
"status": "created",
"monitor_sys_id": "m1n2o3p4q5r6789012345678",
"monitor_name": "[INC0012345] Payment API Health - Payment Gateway",
"location": {
"sys_id": "l1m2n3o4p5q6789012345678",
"name": "US-East-1 MID Server",
"selection_phase": 2
},
"error_message": null,
"error_code": null
},
{
"endpoint_id": "k1l2m3n4o5p6789012345678",
"status": "created",
"monitor_sys_id": "r1s2t3u4v5w6789012345678",
"monitor_name": "[INC0012345] Payment Transaction API - Payment Gateway",
"location": {
"sys_id": "l1m2n3o4p5q6789012345678",
"name": "US-East-1 MID Server",
"selection_phase": 2
},
"error_message": null,
"error_code": null
},
{
"endpoint_id": "q1r2s3t4u5v6789012345678",
"status": "created",
"monitor_sys_id": "x1y2z3a4b5c6789012345678",
"monitor_name": "[INC0012345] Customer Portal Status - Payment Gateway",
"location": {
"sys_id": "l1m2n3o4p5q6789012345678",
"name": "US-East-1 MID Server",
"selection_phase": 2
},
"error_message": null,
"error_code": null
}
]
}Corps de la réponse : réussite partielle.
{
"success": true,
"message": "Bulk creation completed. 2 monitors created successfully, 1 failed validation.",
"summary": {
"total_requested": 3,
"successful": 2,
"failed": 1
},
"results": [
{
"endpoint_id": "e1f2g3h4i5j6789012345678",
"status": "created",
"monitor_sys_id": "m1n2o3p4q5r6789012345678",
"monitor_name": "[INC0012345] Payment API Health - Payment Gateway",
"location": {
"sys_id": "l1m2n3o4p5q6789012345678",
"name": "US-East-1 MID Server",
"selection_phase": 2
},
"error_message": null,
"error_code": null
},
{
"endpoint_id": "invalid-endpoint-id",
"status": "failed",
"monitor_sys_id": null,
"monitor_name": null,
"location": null,
"error_message": "Invalid endpoint_id: No endpoint found with sys_id 'invalid-endpoint-id' in cmdb_ci_endpoint_http table.",
"error_code": "INVALID_ENDPOINT_ID"
},
{
"endpoint_id": "q1r2s3t4u5v6789012345678",
"status": "created",
"monitor_sys_id": "x1y2z3a4b5c6789012345678",
"monitor_name": "[INC0012345] Customer Portal Status - Payment Gateway",
"location": {
"sys_id": "w1x2y3z4a5b6789012345678",
"name": "EU-West-1 MID Server",
"selection_phase": 4
},
"error_message": null,
"error_code": null
}
]
}Corps de la réponse : erreur de limite de taux.
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. You have made 11 requests in the last minute. Limit is 10 requests per minute.",
"details": {
"limit": 10,
"window": "per_minute",
"retry_after_seconds": 45
}
}
}