Guide du développeur sur la surveillance synthétique

  • Rversion finale: Australia
  • Mis à jour 29 avr. 2026
  • 12 minutes de lecture

    • Les API de surveillance synthétique permettent de créer plusieurs moniteurs synthétiques en une seule opération.

    Ce guide du développeur fournit des informations sur l’utilisation Synthetic monitoring des API pour créer en masse des moniteurs à partir de Postman ou de Terminal.

    Pour obtenir une documentation de référence complète sur les API de surveillance synthétique, consultez :

    Importer et créer des moniteurs synthétiques en masse à l’aide de l’API

    Créez plusieurs moniteurs synthétiques simultanément en important des fichiers JSON ou CSV bruts via l’API SyntheticsAsyncBulkCreate.

    Avant de commencer

    Rôle requis : sn_sow_synthetics.synthetics_admin ou sn_sow_synthetics.synthetics_editor
    • Informations d’identification de l’instance ServiceNow valides
    • Accès au point de terminaison Http
    • URL de base : https://<votre-instance>.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create
    • Fichier JSON ou CSV brut préparé avec les données de surveillance contenant les champs requis :
      • Nom du moniteur
      • sys_id de point de terminaison HTTP
      • Service parent sys_id
      • sys_id de l’emplacement
      • ID système du groupe de support
      • Intervalle (fréquence)
      • Méthode (« GET », « POST », « PUT », « DELETE », « PATCH », « HEAD »)
      • Champ d’assertion

    L’un des outils suivants : Terminal (avec commande curl), Postman ou environnement de script.

    Pourquoi et quand exécuter cette tâche

    L’API SyntheticsAsyncBulkCreate utilise un processus en deux étapes :
    1. Crée un ID de tâche en téléchargeant votre fichier de données de surveillance.
    2. Vérifie l’état de la tâche pour vérifier l’état de la création du moniteur.
    Vous pouvez accéder à cette API via l’une des méthodes suivantes :
    • Terminal utilisant des commandes curl
    • Application Postman
    • Scripts personnalisés
    L’API nécessite une authentification de base ou une authentification par jeton OAuth.
    • Authentification de base : 
      curl -u « nom d’utilisateur :mot de passe »
    • Jeton OAuth : 
      curl -H « Autorisation : porteur <votre-jeton-oauth> »

    Procédure

    1. Préparez votre fichier de données de surveillance au format JSON ou CSV brut.
    2. Choisissez votre méthode préférée (Terminal, Postman ou Script).
    3. Appelez le point de terminaison de l’API d’importation en bloc pour charger le fichier et générer un ID de tâche.
    4. Utilisez l’URL de vérification de l’état pour vérifier l’état de la création du moniteur.
    5. Examinez la réponse pour connaître la création réussie du moniteur ou les détails de l’erreur.
    6. Mettez à jour le fichier source avec des données correctes (en cas d’erreurs), puis soumettez à nouveau.

    Résultats

    Les moniteurs sont créés dans l’instance ServiceNow. La réponse API indique :
    • État du traitement (traitement/terminé)
    • Moniteurs créés avec succès
    • Moniteurs ayant échoué avec des détails sur l’erreur (champs obligatoires manquants, sys_ids non valides, entre autres)

    Créer des moniteurs en bloc à l’aide de Terminal

    Utilisez les commandes curl dans Terminal pour créer plusieurs moniteurs synthétiques simultanément en important des fichiers JSON ou CSV via l’API SyntheticsAsyncBulkCreate .

    Avant de commencer

    Rôle requis : sn_sow_synthetics.synthetics_admin ou sn_sow_synthetics.synthetics_editor
    • Informations d’identification de l’instance ServiceNow valides
    • Accès au point de terminaison Http
    • URL de base : https://<votre-instance>.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create
    • Fichier JSON ou CSV brut préparé avec les données de surveillance contenant les champs requis :
      • Nom du moniteur
      • sys_id de point de terminaison HTTP
      • Service parent sys_id
      • sys_id de l’emplacement
      • ID système du groupe de support
      • Intervalle (fréquence)
      • Méthode (« GET », « POST », « PUT », « DELETE », « PATCH », « HEAD »)
      • Champ d’assertion

    Pourquoi et quand exécuter cette tâche

    L’API SyntheticsAsyncBulkCreate utilise un processus en deux étapes lorsqu’elle est accessible via Terminal. Tout d’abord, chargez le fichier de données de votre moniteur à l’aide d’une commande curl pour générer un ID de tâche. Ensuite, vérifiez l’état de la tâche pour vérifier la création du moniteur. L’API traite les enregistrements de manière asynchrone et fournit des commentaires détaillés sur les créations réussies et les erreurs.

    Différentes commandes curl sont nécessaires selon que vous chargez un fichier JSON ou CSV.

    Procédure

    1. Ouvrez le terminal sur votre système.
    2. Accédez au répertoire contenant votre fichier de données de surveillance.
    3. Exécutez la commande curl appropriée pour charger votre fichier et créer un ID de tâche.

      Pour les fichiers JSON :

      curl -X POST "https://{your-instance}.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u "admin:password" \
  -d @{filename}.json

      Pour les fichiers CSV :

      curl -X POST "https://{your-instance}.service-now.com/api/sn_now_synthetics/v1/synthetics_async_bulk_create?filename=filename.csv" \
  -H "Content-Type: text/csv" \
  -H "Accept: application/json" \
  -u "admin:password" \
  --d "$(jq -Rs '{csv_content: .}'filename.csv"

      Remplacez les espaces réservés suivants :

      • {your-instance} : nom de votre instance ServiceNow
      • {filename} : le nom de votre fichier de données de surveillance

      L’API renvoie une réponse contenant un ID de tâche et une URL de vérification du statut.

      {
  "result": {
    "job_id": "abc123def456",
    "status": "processing",
    "status_check_url": "https://{your-instance}.service-now.com/api/now/synthetic/monitor/bulk/status/abc123def456"
  }
}
    4. Copiez l’URL de vérification de l’état à partir de la réponse.
    5. Exécutez la commande status check curl pour vérifier l’état de traitement de la tâche. 
      curl -X GET "https://{your-instance}.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create/{job_id}" \
  -H "Accept: application/json" \
  -u "{username}:{password}"

      L’API renvoie l’une des réponses d’état suivantes :

      État du traitement :

      {
  "result": {
    "job_id": "abc123def456",
    "status": "processing",
    "total_records": 10,
    "processed_records": 3
  }
}

      État complet (réussite) :

      {
  "result": {
    "job_id": "abc123def456",
    "status": "complete",
    "total_records": 10,
    "successful_records": 10,
    "failed_records": 0,
    "details": []
  }
}

      État complet (avec des erreurs) :

      {
  "result": {
    "job_id": "abc123def456",
    "status": "complete",
    "total_records": 10,
    "successful_records": 8,
    "failed_records": 2,
    "details": [
      {
        "name": "Monitor_API_001",
        "status": "failed",
        "error_code": "MISSING_REQUIRED_FIELD",
        "reason": "CMDB CI is required"
      },
      {
        "name": "Monitor_API_002",
        "status": "failed",
        "error_code": "INVALID_REFERENCE",
        "reason": "Location not found for this sys_id"
      }
    ]
  }
}
    6. Si l’état est « en cours de traitement », patientez quelques instants et répétez la commande de vérification de l’état.
      Le système traite les enregistrements de façon asynchrone. Continuez la vérification jusqu’à ce que l’état passe à « terminé ».
    7. Si des moniteurs n’ont pas pu être créés, passez en revue les détails de l’erreur dans la réponse.
      1. Identifiez le nom du moniteur défaillant à partir des détails compilés .
      2. Examinez le code d’erreur et le motif fournis.
      3. Mettez à jour votre fichier JSON ou CSV source pour corriger les problèmes de données.

        Les erreurs courantes incluent :

        • Champs obligatoires manquants (CI CMDB, emplacement, méthode)
        • Références sys_id non valides qui n’existent pas dans l’instance
        • Formats de données incorrects
      4. Renvoyez le fichier corrigé en répétant la commande upload curl.

    Résultats

    Les moniteurs sont créés dans votre instance ServiceNow. Les moniteurs créés avec succès sont immédiatement disponibles. Les moniteurs défaillants sont signalés avec des détails d’erreur spécifiques, ce qui vous permet de corriger les données et de les soumettre à nouveau.

    Terminer l’exemple de workflow

    Étape 1 : Charger un fichier JSON

    curl -X POST "https://myinstance.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u "admin:password123" \
  -d @monitor_data.json

    Réponse :

    {
  "result": {
    "job_id": "xyz789abc123",
    "status": "processing",
    "status_check_url": "https://myinstance.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create/status/xyz789abc123"
  }
}

    Étape 2 : vérifier l’état

    curl -X GET "https://myinstance.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create/status/xyz789abc123" \
  -H "Accept: application/json" \
  -u "admin:password123"

    Réponse finale :

    {
  "result": {
    "job_id": "xyz789abc123",
    "status": "complete",
    "total_records": 5,
    "successful_records": 5,
    "failed_records": 0
  }
}

    Que faire ensuite

    Une fois la création réussie, vérifiez vos moniteurs dans l’interface utilisateur ServiceNow en accédant à Surveillance synthétique > Surveillances. Vous pouvez configurer des paramètres de moniteur et des calendriers supplémentaires, selon vos besoins.

    Créer des moniteurs en masse à l’aide de Postman

    Utilisez Postman pour créer plusieurs moniteurs synthétiques simultanément en important des fichiers JSON ou CSV via l’API SyntheticsAsyncBulkCreate .

    Avant de commencer

    Rôle requis : sn_sow_synthetics.synthetics_admin ou sn_sow_synthetics.synthetics_editor
    • Informations d’identification de l’instance ServiceNow valides
    • Accès au point de terminaison Http
    • URL de base : https://<votre-instance>.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create
    • Fichier JSON ou CSV brut préparé avec les données de surveillance contenant les champs requis :
      • Nom du moniteur
      • sys_id de point de terminaison HTTP
      • Service parent sys_id
      • sys_id de l’emplacement
      • ID système du groupe de support
      • Intervalle (fréquence)
      • Méthode (« GET », « POST », « PUT », « DELETE », « PATCH », « HEAD »)
      • Champ d’assertion

    Pourquoi et quand exécuter cette tâche

    L’API SyntheticsAsyncBulkCreate utilise un processus en deux étapes lorsqu’elle est accessible via Postman. Tout d’abord, créez une requête POST pour télécharger votre fichier de données de surveillance et générer un ID de tâche. Ensuite, utilisez l’URL de vérification de l’état pour vérifier la création du moniteur. Postman fournit une interface conviviale pour tester l’API et afficher les réponses formatées.

    La même configuration Postman fonctionne pour les fichiers JSON et CSV, seule la sélection du format de fichier diffère.

    Procédure

    1. Ouvrez l’application Postman.
    2. Créer une nouvelle demande en sélectionnant le bouton + ou Nouveau > Demande HTTP.
    3. Définissez la méthode de demande sur POST dans le menu déroulant et saisissez l’URL de base du point de terminaison de l’API d’importation en bloc dans le champ URL de la demande.

      Remplacez {instance-name} dans l’URL de base par le nom de votre ServiceNow instance.

    4. Configurez les informations d’identification d’authentification.
      1. Sélectionnez l’onglet Autorisation sous le champ URL .
      2. Sélectionnez Authentification de base dans la liste déroulante Type .
      3. Entrez votre ServiceNow nom d’utilisateur dans le champ Nom d’utilisateur .
        Assurez-vous que cet utilisateur dispose du rôle d’administrateur synthétique.
      4. Entrez votre mot de passe dans le champ Mot de passe .
    5. Configurez le corps de la demande pour charger votre fichier de données de surveillance.
      1. Sélectionnez l'onglet Corps.
      2. Sélectionnez binaire comme type de corps.
      3. Sélectionnez le bouton Sélectionner un fichier , accédez à l’emplacement de votre fichier de données de surveillance et sélectionnez votre fichier JSON ou CSV.
        Si vous chargez un fichier CSV, assurez-vous qu’il est correctement formaté avec toutes les colonnes requises. Convertir un fichier CSV au format JSON
    6. Ajoutez le nom de fichier en tant que paramètre de requête dans l’URL, puis sélectionnez Envoyer pour soumettre la demande.
      Par exemple, si votre nom de fichier est monitors .json, le chemin d’accès au fichier sera https://<your-instance>.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create?filename=monitors.json
      L’API renvoie une réponse JSON contenant un ID de tâche et une URL de vérification d’état.

      { « result » : { « job_id » : « abc123def456 », « status » : « processing », « status_check_url » : « https://{instance-name}.service-now.com/api/now/synthetic/monitor/bulk/status/abc123def456 » } }

    7. Copiez l’URL de vérification de l’état à partir de la réponse.
    8. Créez une nouvelle demande GET pour vérifier l’état de la tâche.
      1. Cliquez sur l’URL de vérification de l’état dans la réponse ou créez manuellement une nouvelle demande.
        Si l’URL est cliquable dans Postman, il créera automatiquement une nouvelle requête GET avec l’URL renseignée.
      2. Si vous créez manuellement, définissez la méthode de demande sur GET.
      3. Collez l’URL de vérification de l’état (https://<your-instance>.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create/{job_id} dans le champ ß .

        Remplacez {job_id} par l’ID de la tâche de la réponse POST.

    9. Configurez l’authentification pour la demande de vérification de statut.
      Si vous êtes dans le même espace de travail Postman, l’autorisation peut déjà être héritée. Si ce n’est pas le cas, répétez la configuration de l’authentification de base de l’étape 4.
    10. Sélectionnez Envoyer pour vérifier l’état de la tâche.
      Vous pouvez enregistrer les demandes dans une collection en vue de leur réutilisation.

      L’API renvoie l’une des réponses d’état suivantes :

      État du traitement :

      {
  "result": {
    "job_id": "abc123def456",
    "status": "processing",
    "total_records": 10,
    "processed_records": 3
  }
}

      État complet (réussite) :

      {
  "result": {
    "job_id": "abc123def456",
    "status": "complete",
    "total_records": 10,
    "successful_records": 10,
    "failed_records": 0,
    "details": []
  }
}

      État complet (avec des erreurs) :

      {
  "result": {
    "job_id": "abc123def456",
    "status": "complete",
    "total_records": 10,
    "successful_records": 8,
    "failed_records": 2,
    "details": [
      {
        "name": "Monitor_API_001",
        "status": "failed",
        "error_code": "MISSING_REQUIRED_FIELD",
        "reason": "CMDB CI is required"
      },
      {
        "name": "Monitor_API_002",
        "status": "failed",
        "error_code": "INVALID_REFERENCE",
        "reason": "Location not found for this sys_id"
      }
    ]
  }
}
    11. Si l’état est « en cours de traitement », patientez quelques instants et sélectionnez à nouveau Envoyer pour actualiser l’état.
      Le système traite les enregistrements de façon asynchrone. Continuez la vérification jusqu’à ce que l’état passe à « terminé ».
    12. Si des moniteurs n’ont pas pu être créés, passez en revue les détails de l’erreur dans la réponse.
      1. Développez le tableau de détails dans la visionneuse de réponses Postman pour afficher les enregistrements d’erreurs individuels.
      2. Notez le nom du moniteur, le code d’erreur et la raison de chaque défaillance.
      3. Mettez à jour votre fichier JSON ou CSV source pour corriger les problèmes identifiés.

        Les erreurs courantes incluent :

        • Champs obligatoires manquants (CI CMDB, emplacement, méthode)
        • Références sys_id non valides qui n’existent pas dans l’instance
        • Formats de données ou noms de champs incorrects
      4. Revenez à votre demande POST d’origine et soumettez-la à nouveau avec le fichier corrigé.

    Résultats

    Les moniteurs sont créés dans votre instance ServiceNow. Les moniteurs créés avec succès sont immédiatement disponibles. Les moniteurs défaillants sont signalés avec des détails d’erreur spécifiques dans un format JSON structuré facile à consulter dans la visionneuse de réponses de Postman.

    Terminer l’exemple de workflow

    Étape 1 : configurer la demande POST

    • Méthode : POST
    • URL : https://myinstance.service-now.com/api/now/synthetic/monitor/bulk/import
    • Autorisation : authentification de base (nom d’utilisateur : admin, mot de passe : ********)
    • Corps : binaire, fichier sélectionné : monitor_data.json
    • En-têtes : Content-Type : application/json, Accepter : application/json

    Réponse reçue :

    {
  "result": {
    "job_id": "xyz789abc123",
    "status": "processing",
    "status_check_url": "https://myinstance.service-now.com/api/now/synthetic/monitor/bulk/status/xyz789abc123"
  }
}

    Étape 2 : configurez la demande GET pour la vérification du statut

    • Méthode : GET
    • URL : https://myinstance.service-now.com/api/now/synthetic/monitor/bulk/status/xyz789abc123
    • Autorisation : authentification de base (héritée de l’espace de travail)

    Réponse finale :

    {
  "result": {
    "job_id": "xyz789abc123",
    "status": "complete",
    "total_records": 5,
    "successful_records": 5,
    "failed_records": 0
  }
}

    Que faire ensuite

    • Enregistrez vos demandes Postman dans une collection pour une utilisation ultérieure et une nouvelle soumission facile.
    • Vérifiez vos moniteurs dans l’interface utilisateur ServiceNow en accédant à Surveillance synthétique > moniteurs.
    • Configurez des paramètres de surveillance supplémentaires tels que des calendriers, des notifications et des seuils selon vos besoins.

    Convertir un fichier CSV au format JSON

    Convertissez votre fichier CSV au format JSON pour créer des moniteurs synthétiques.

    Fichier CSV au format JSON

    Pour convertir le fichier CSV au format JSON, accédez au terminal. En fonction de votre système d’exploitation, exécutez les commandes requises.
    Tableau 1. Commandes pour convertir un fichier CSV au format JSON
    Système d'exploitation Commandes Curl
    MacOS jq -Rs '{csv_content : .}' filename.csv
    Windows Powershell
    • Si vous utilisez jq, utilisez la commande jq -Rs '{csv_content : .}' filename.csv
    • Si vous utilisez uniquement Powershell (aucun jq installé), utilisez les commandes :
      1. $csvContent = get-content -chemin d’accès « synthetic_checks.csv » -brut
      2. $json = @{ csv_content = $csvContent } | ConvertTo-JSON
      3. $json
    • Si vous utilisez l’invite de commande Windows avec jq installé, utilisez la commande jq -Rs "{csv_content : .}» filename.csv

    La sortie est un contenu CSV enveloppé au format JSON disponible sur le terminal. { « csv_content » : « name,method,description,interval,cmdb_ci,...\n\"Monitors1\ »,\"GET\ »,\"CHECK1\ »,5,... " }

    Une fois le contenu disponible au format JSON, accédez à l’onglet Corps dans Postman, puis sélectionnez Brut pour coller le contenu du format JSON et sélectionnez Envoyer.
    Remarque :
    Assurez-vous que le format sélectionné est JSON.

    L’état de la réponse fournit l’ID de la tâche et l’état des moniteurs créés. Si des erreurs sont détectées, corrigez le fichier et exécutez les mêmes commandes pour terminer la création du moniteur.