SyntheticsAsyncBulkCreate API
L’API SyntheticsAsyncBulkCreate fournit des points de terminaison pour gérer la création asynchrone de moniteurs synthétiques.
Utilisez cette API pour créer jusqu’à 5 000 moniteurs par demande. Pour les opérations par lots plus petites où une validation et des résultats immédiats sont requis, ou pour lier les moniteurs aux incidents, utilisez l’API SyntheticsBulkCreate qui prend en charge la création de jusqu’à 50 moniteurs par demande.
Les moniteurs peuvent être créés à l’aide de données au format JSON ou CSV. Pour plus d’informations sur l’utilisation de fichiers JSON ou CSV avec Postman ou Terminal, reportez-vous à la Guide du développeur sur la surveillance synthétique section .
Cette API nécessite l’application Synthetic monitoring (com.snc.uib.sow_synthetics), qui est disponible sur le ServiceNow Store. 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).
SyntheticsAsyncBulkCreate : GET /sn_sow_synthetics/synthetics_async_bulk_create/{job_id}
Vérifie la progression d’une tâche de création de moniteur en bloc.
Pour appeler ce point de terminaison, l’utilisateur doit avoir le rôle x_snc_sow_synthetics.synthetics_viewer.
Format d'URL
URL versionnée : /api/sn_sow_synthetics/{api_version}/synthetics_async_bulk_create/{job_id}
URL par défaut : /api/sn_sow_synthetics/synthetics_async_bulk_create/{job_id}
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 |
| job_id | ID de la tâche de création du moniteur. Table : tâche en bloc synthétique [sn_sow_synthetics_bulk_job] Colonne : ID de tâche Type de données : chaîne |
| Nom | Description |
|---|---|
| Néant |
| Nom | Description |
|---|---|
| Néant |
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 : |
| En-tête | Description |
|---|---|
| Néant |
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 |
|---|---|
| 202 | Accepté. État de la tâche récupéré avec succès. |
| 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_viewer pour vérifier l’état de la tâche. |
| 404 | Introuvable. Aucune tâche avec l’ID fourni n’a été trouvée dans la table Tâche synthétique en bloc [sn_sow_synthetics_bulk_job]. |
| 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 |
|---|---|
| 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 |
| résultat | Objet contenant des informations sur l’état de la tâche de création du moniteur. Type de données : objet |
| result.job_id | ID de la tâche de création du moniteur. Table : tâche en bloc synthétique [sn_sow_synthetics_bulk_job] Colonne : ID de tâche Type de données : chaîne |
| résultat.message | Message sur l’état de la tâche de création du moniteur. Type de données : chaîne |
| résultat.état | Statut de la tâche de création du moniteur. Valeurs possibles :
Type de données : chaîne |
| résultat.résumé | Données récapitulatives actuelles pour la tâche de création du moniteur. Type de données : objet |
| Résultat.Résumé.Créé | Nombre de moniteurs créés avec succès. Type de données : nombre |
| Résultat.Résumé.Échec | Nombre de moniteurs qui n’ont pas pu être créés ou mis à jour. Type de données : nombre |
| Résultat.Résumé.Traité | Nombre de moniteurs traités par la tâche. Type de données : nombre |
| Résultat.Résumé.Réussi | Nombre de moniteurs créés ou mis à jour avec succès. Type de données : nombre |
| result.summary.total | Nombre total de moniteurs inclus dans la tâche. Type de données : nombre |
| résultat.résumé.mis à jour | Nombre de moniteurs mis à jour avec succès. Type de données : nombre |
| résultat.erreurs | Informations relatives à l’erreur des moniteurs défaillants. Type de données : tableau |
| result.errors.check_number | Ordre du moniteur dans le checks tableau fourni dans le corps de la demande pour POST /sn_sow_synthetics/synthetics_async_bulk_create. Type de données : nombre |
| result.errors.error_code | Code d’erreur. Valeurs possibles :
Type de données : chaîne |
| result.errors.error_message | Message d’erreur. Type de données : chaîne |
| result.errors.name | Nom du moniteur. Type de données : chaîne |
Demande cURL
Cet exemple vérifie l’état d’une tâche de création de moniteur.
curl "https://instance.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create/BCJ-1776889518281-0baf339f" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'
Corps de la réponse : traitement de la tâche.
{
"result": {
"job_id": "BCJ-1776889518281-0baf339f",
"status": "processing",
"message": "Processing in progress: 150/500 (30%)",
"summary": {
"total": 500,
"processed": 150,
"successful": 148,
"created": 145,
"updated": 3,
"failed": 2
}
}
}
Corps de réponse : tâche terminée avec succès.
{
"result": {
"job_id": "BCJ-1776889518281-0baf339f",
"status": "completed",
"message": "Job completed successfully. 497 monitors created, 3 updated, 0 failed out of 500 total.",
"summary": {
"total": 500,
"processed": 500,
"successful": 500,
"created": 497,
"updated": 3,
"failed": 0
}
}
}
Corps de la réponse : tâche terminée avec des erreurs.
{
"result": {
"job_id": "BCJ-1776889518281-0baf339f",
"status": "completed",
"message": "Job completed. 98 monitors created, 0 updated, 2 failed out of 100 total.",
"summary": {
"total": 100,
"processed": 100,
"successful": 98,
"created": 98,
"updated": 0,
"failed": 2
},
"errors": [
{
"check_number": 23,
"name": "Invalid Monitor",
"error_code": "CREATE_FAILED",
"error_message": "cmdb_ci is required"
},
{
"check_number": 45,
"name": "Bad Location Monitor",
"error_code": "CREATE_FAILED",
"error_message": "Location not found: invalid_sys_id"
}
]
}
}
SyntheticsAsyncBulkCreate - POST /sn_sow_synthetics/synthetics_async_bulk_create
Crée plusieurs moniteurs synthétiques en une seule opération asynchrone.
Ce point de terminaison prend en charge la création d’un maximum de 5 000 moniteurs par demande, avec une taille de charge utile maximale de 10 Mo. L’appel de ce point de terminaison soumet une tâche pour créer les moniteurs de manière asynchrone par lots de 500. Vérifiez l’état de la tâche en appelant le point de terminaison GET /sn_sow_synthetics/v1/synthetics_async_bulk_create/{job_id}.
Pour appeler ce point de terminaison, l’utilisateur doit avoir le rôle x_snc_sow_synthetics.synthetics_editor.
Format d'URL
URL avec version : /api/sn_sow_synthetics/{api_version}/synthetics_async_bulk_create
URL par défaut : /api/sn_sow_synthetics/synthetics_async_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 |
|---|---|
| Checks (Vérification | Requis. Tableau d’objets de configuration de point de terminaison pour lesquels créer des moniteurs. Ce tableau peut contenir un maximum de 5 000 objets par demande d’API. Type de données : tableau |
| checks.alert_severity | Niveau de gravité des alertes créées pour les tests de surveillance ayant échoué. N’utilisez ce paramètre que si checks.should_create_alert la valeur est définie sur vrai.Valeurs valides :
Par défaut : 1 Type de données : nombre |
| checks.alert_tags | Balises personnalisées à utiliser pour les alertes créées pour les tests de surveillance ayant échoué. N’utilisez ce paramètre que si checks.should_create_alert la valeur est définie sur vrai.Les éléments contenus dans cet objet varient en fonction des balises utilisées. Par exemple, les balises peuvent être utilisées pour l’environnement ou l’équipe, comme indiqué ci-dessous. Par défaut : objet vide Type de données : objet |
| checks.body | 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.Valeur par défaut : nul Type de données : chaîne |
| checks.body_condition | Validation du corps de la réponse. Type de données : objet |
| checks.body_condition.expression | Expression par rapport à laquelle vérifier le corps de la réponse. L’expression peut être n’importe quelle valeur de chaîne, y compris la prise en charge de regex, JSONPath et XPath. Valeur par défaut : nul Type de données : chaîne |
| checks.body_condition.type | Type de validation utilisé pour évaluer le corps de la réponse par rapport checks.body_condition.expressionà . Valeurs valides (sensibles à la casse) :
Valeur par défaut : nul Type de données : chaîne |
| checks.cmdb_ci | 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 |
| vérifications.informations d’identification | Sys_id des informations d’identification du moniteur à inclure dans la demande de point de terminaison. Table : Valeur par défaut : nul Type de données : chaîne |
| vérification.description | Description du moniteur. Type de données : chaîne |
| checks.enabled | 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 |
| Vérifications.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) |
| checks.headers.name | Nom de l’en-tête HTTP, tel que Authorization ou Content-Type.Type de données : chaîne |
| vérification.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 |
| checks.interval | Requis. 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 exemple, une valeur de Type de données : nombre |
| vérifications.emplacements | Requis. Liste des sys_ids d’emplacements Serveur MID à utiliser pour le moniteur. Table : emplacement synthétique [sn_sow_synthetics_location] Type de données : chaîne |
| checks.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 |
| Vérification.Méthode | Requis. Méthode HTTP à utiliser. Valeurs valides (insensibles à la casse) :
Type de données : chaîne |
| checks.name | Requis. Nom d’affichage du moniteur. Longueur maximale : 100 caractères Type de données : chaîne |
| checks.parent_service_sys_id | Requis. 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] Type de données : chaîne |
| checks.query_string | Paramètres de requête pour le moniteur à inclure dans la demande de point de terminaison. Valeur par défaut : nul Type de données : chaîne |
| checks.should_create_alert | Marqueur indiquant si le moniteur crée une alerte en cas d’échec d’un test. Valeurs valides :
Valeur par défaut : false Type de données : booléennes |
| checks.single_api_check_sys_id | Sys_id du moniteur pour le point de terminaison. Utilisez ce paramètre pour mettre à jour un moniteur existant. Table : API unique [sn_sow_synthetics_check_single_api] Valeur par défaut : nul Type de données : chaîne |
| checks.support_group_sys_id | Requis. 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] Type de données : chaîne |
| checks.valid_http_code | Codes d’état HTTP attendus pour une réponse réussie. Formats valides :
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. Valeur par défaut : nul Type de données : chaîne |
| checks.valid_http_code_type | Type de validation utilisé pour vérifier le code d’état HTTP à partir d’une réponse. Valeurs valides (sensibles à la casse) :
Valeur par défaut : nul 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. Types pris en charge : application/json ou text/csv. Valeur par défaut : application/json |
| En-tête | Description |
|---|---|
| Néant |
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 |
|---|---|
| 202 | Accepté. Une tâche de création de moniteur en bloc a été envoyée. |
| 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. |
| 413 | Charge utile trop importante. Le corps de la demande dépasse la limite de 10 Mo. |
| 415 | Type de média non pris en charge. La charge utile doit être au format JSON ou CSV. |
| 429 | Trop de demandes ou trop de tâches de création de moniteurs actives. Patientez et réessayez. Vérifiez error.code et error.message dans le corps de la réponse pour plus d’informations. Limites des taux :
|
| 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 |
|---|---|
| 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 |
| résultat | Objet contenant des informations sur la tâche de création du moniteur. Type de données : objet |
| result.job_id | ID de la tâche de création du moniteur. Table : tâche en bloc synthétique [sn_sow_synthetics_bulk_job] Colonne : ID de tâche Type de données : chaîne |
| result.job_sys_id | Sys_id de la tâche de création du moniteur. Table : tâche en bloc synthétique [sn_sow_synthetics_bulk_job] Type de données : chaîne |
| résultat.message | Message sur l’état de la tâche de création du moniteur. Type de données : chaîne |
| résultat.état | Statut de la tâche de création du moniteur. Pour une demande d’API réussie (code d’état Type de données : chaîne |
| result.status_check_url | Point de terminaison pour le suivi de l’état actuel de la tâche de création du moniteur. Pour plus d’informations, consultez GET /sn_sow_synthetics/v1/synthetics_async_bulk_create/{job_id}. Type de données : chaîne |
Demande cURL
Cet exemple soumet une tâche pour créer des moniteurs pour deux points de terminaison d’API.
curl "https://instance.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"checks": [
{
"name": "Production API Health Check",
"method": "GET",
"description": "Monitors the main API health endpoint",
"interval": 5,
"cmdb_ci": "21d4073087807610f13cbbf7cebb3500",
"enabled": true,
"should_create_alert": true,
"alert_severity": 1,
"locations": [
"0fd0279b87003210f13cbbf7cebb3552",
"2244a48d87cc7610f13cbbf7cebb3554"
],
"headers": [
{
"name": "Accept",
"value": "application/json"
}
],
"query_string": null,
"credential": "",
"body": null,
"parent_service_sys_id": "6731133c87c07610f13cbbf7cebb35d8",
"support_group_sys_id": "019ad92ec7230010393d265c95c260dd",
"alert_tags": {
"environment": "production",
"team": "platform"
},
"valid_http_code_type": "equals",
"valid_http_code": "200",
"max_latency_ms": 5000,
"body_condition": {
"type": "jsonpath",
"expression": "$.status == 'ok'"
}
},
{
"name": "User Service POST Test",
"method": "POST",
"description": "Tests user creation endpoint",
"interval": 10,
"cmdb_ci": "21d4073087807610f13cbbf7cebb3503",
"enabled": true,
"should_create_alert": true,
"alert_severity": 2,
"locations": [
"2244a48d87cc7610f13cbbf7cebb3554"
],
"headers": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"body": "{\"test\": true}",
"parent_service_sys_id": "6731133c87c07610f13cbbf7cebb35e1",
"support_group_sys_id": "0762d92db72422103a858bbb4e11a928",
"valid_http_code_type": "in_range",
"valid_http_code": "200-201",
"max_latency_ms": 3000
}
]
}" \
--user 'username':'password'
Corps de la réponse : tâche créée avec succès.
{
"result": {
"job_id": "BCJ-1706789123456-a1b2c3d4",
"job_sys_id": "abc123def456abc123def456",
"status": "pending",
"message": "Job created successfully. File uploaded. Processing will begin shortly.",
"status_check_url": "/api/sn_sow_synthetics/v1/synthetics_async_bulk_create/BCJ-1706789123456-a1b2c3d4"
}
}
Corps de la réponse : erreur de limite de tâche de création de moniteur simultané.
{
"error": {
"code": "CONCURRENT_JOB_LIMIT",
"message": "Maximum concurrent jobs exceeded. Please wait for existing jobs to complete."
}
}
Corps de la réponse : erreur de limite de taux.
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Please try again later.",
"details": {
"remaining_per_minute": 0,
"remaining_per_hour": 5,
"remaining_per_day": 100
}
}
}