API de jeu d’importation

  • Rversion finale: Australia
  • Mis à jour 12 mars 2026
  • 11 minutes de lecture

    • L’API de jeu d’importation fournit des points de terminaison qui vous permettent d’interagir avec les tables de jeux d’importation.

    Cette API transforme les données entrantes en fonction des cartes de transformation associées. L’API de jeu d’importation prend en charge les transformations synchrones. L’API de jeu d’importation reflète l’interface SOAP existante.

    Sécurité

    L’accès aux tables via l’API REST est limité par BasicAuth. Pour autoriser l’accès aux tables sans aucune authentification ni autorisation, ajoutez le nom de la table à sys_public.list. Les ACL définies sur les tables sont toujours appliquées, et il est de la responsabilité de l’administrateur de les désactiver.

    Jeu d’importation : GET /now/import/{stagingTableName}/{sys_id}

    Récupère l’enregistrement intermédiaire d’importation spécifié et le résultat de transformation qui en résulte.

    Format d'URL

    URL versionnée : /api/now/{api_version}/import/{stagingTableName}/{sys_id}

    URL par défaut : /api/now/import/{stagingTableName}/{sys_id}

    Remarque :
    Les versions disponibles sont spécifiées dans l’explorateur d’API REST. Pour les API REST scriptées, des informations supplémentaires sur la version se trouvent dans le formulaire Service REST scripté.

    Paramètres de demande pris en charge

    Tableau 1. Paramètres de chemin d'accès
    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
    stagingTableName Nom de la table à partir de laquelle obtenir les données d’importation.

    Type de données : chaîne
    sys_id Sys_id de l’enregistrement qui contient les données.

    Type de données : chaîne
    Tableau 2. Paramètres de requête
    Nom Description
    Néant
    Tableau 3. Paramètres de corps de demande (XML ou JSON)
    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.

    Tableau 4. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Tableau 5. En-têtes de réponses
    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.

    Tableau 6. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été traitée avec succès.
    401 Non autorisé. Les informations d’identification de l’utilisateur sont incorrectes ou n’ont pas été transmises.
    404 Indique que la ressource spécifiée n’était pas disponible. Comme les tables d’ensembles de données à importer sont fréquemment supprimées en fonction d’un calendrier, les demandes GET peuvent renvoyer des réponses 404 Introuvables si le résultat de transformation n’existe plus.
    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 du corps de la réponse (JSON ou XML)

    Nom Description
    import_set Nom du jeu d’importation.

    Type de données : chaîne
    résultat Liste des objets qui contiennent des informations sur les ensembles de données qui ont été importés.
    Type de données : tableau
    "result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]
    result.display_name Nom d’affichage de la colonne spécifique de la table pour laquelle la valeur d’affichage est vraie. Par exemple, nombre.

    Type de données : chaîne
    result.display_value Valeur d’affichage de la display_name colonne. Par exemple, CHG0000123.

    Type de données : chaîne
    result.record_link Demande GET d’API de table pour l’enregistrement importé.

    Type de données : chaîne
    résultat.état État de l’importation.

    Type de données : chaîne
    result.sys_id Sys_id de l’enregistrement d’importation.

    Type de données : chaîne
    résultat.table Nom de la table dans laquelle les données ont été importées.

    Type de données : chaîne
    result.transform_map Nom de la carte de transformation.

    Type de données : chaîne
    staging_table Nom de la table intermédiaire d’importation.

    Type de données : chaîne

    Exemple de demande cURL

    curl "https://instance.servicenow.com/api/now/import/imp_user/e2928be64f411200adf9f8e18110c777" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    {
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.service-now.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

    Jeu d’importation : POST /now/import/{stagingTableName}

    Insère les données entrantes dans une table intermédiaire spécifiée et déclenche la transformation basée sur des cartes de transformation prédéfinies dans la table de jeux d’importation.

    La transformation se produit de manière synchrone. Pour chaque carte de transformation que vous définissez, les réponses incluent des résultats de transformation tels que des informations sur les enregistrements cibles.
    Remarque :
    Les champs status_message et error_message des scripts de transformation sont traités et renvoyés en réponse, ainsi que tous les champs de réponse personnalisés.

    Format d'URL

    URL versionnée : /api/now/{api_version}/import/{stagingTableName}

    URL par défaut : /api/now/import/{stagingTableName}

    Remarque :
    Les versions disponibles sont spécifiées dans l’explorateur d’API REST. Pour les API REST scriptées, des informations supplémentaires sur la version se trouvent dans le formulaire Service REST scripté.

    Paramètres de demande pris en charge

    Remarque :
    La méthode POST du jeu d’importation accepte uniquement les paires nom-valeur des types de données Chaîne dans les paramètres de corps de la demande. Si un autre type de données est fourni, la valeur résultante stockée dans la table d’ensembles de données à importer peut ne pas être conforme au format prévu. Par exemple, la notion « : » de l’objet JSON imbriqué est changée en « = ».
    Tableau 7. Paramètres de chemin d'accès
    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
    stagingTableName Nom de la table à partir de laquelle importer les données.

    Type de données : chaîne
    Tableau 8. Paramètres de requête
    Nom Description
    Néant
    Tableau 9. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    Appel spécifique Paires nom-valeur à insérer dans les champs d’importation.

    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.

    Tableau 10. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Type de contenu Format des données du corps de la demande. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Tableau 11. En-têtes de réponses
    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.

    Tableau 12. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été traitée avec succès.
    201 Réussi. La demande a été créé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 du corps de la réponse (JSON ou XML)

    Nom Description
    import_set Nom du jeu d’importation.

    Type de données : chaîne
    résultat Liste des objets qui contiennent des informations sur les ensembles de données qui ont été importés.
    Type de données : tableau
    "result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]
    result.display_name Nom d’affichage de la colonne spécifique de la table pour laquelle la valeur d’affichage est vraie. Par exemple, nombre.

    Type de données : chaîne
    result.display_value Valeur d’affichage de la display_name colonne. Par exemple, CHG0000123.

    Type de données : chaîne
    result.record_link Demande GET d’API de table pour l’enregistrement importé.

    Type de données : chaîne
    résultat.état État de l’importation.

    Type de données : chaîne
    result.sys_id Sys_id de l’enregistrement d’importation.

    Type de données : chaîne
    résultat.table Nom de la table dans laquelle les données ont été importées.

    Type de données : chaîne
    result.transform_map Nom de la carte de transformation.

    Type de données : chaîne
    staging_table Nom de la table intermédiaire d’importation.

    Type de données : chaîne

    Exemple de demande cURL

    curl "https://instance.servicenow.com/api/now/import/imp_user" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{'first_name':'John','last_name':'Public','user_id':'john.public','email':'john.public@company.com'}" \
--user "username":"password"
    {
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.servicenow.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

    Jeu d’importation : POST /now/import/{stagingTableName}/insertMultiple

    Insère plusieurs enregistrements dans une table intermédiaire spécifiée et déclenche la transformation basée sur des cartes de transformation prédéfinies ou des configurations RTE (Robust Transform Engine) en une seule demande.

    La transformation est asynchrone par défaut. Pour définir la transformation synchrone, créez un nouvel enregistrement dans la table Multiples d’insertion REST [sys_rest_insert_multiple], sélectionnez la table source et définissez la transformation sur synchrone.

    Ce point de terminaison peut envoyer un corps de demande dans deux formats possibles.
    Format de fichier de source de données
    Si vous générez une table intermédiaire à partir d’une source de données JSON, faites correspondre le format JSON du fichier source.
    Format de colonne de la table intermédiaire
    Par défaut. Correspond au format corps de la demande de colonne de la table intermédiaire dans les paires de valeurs clés.

    Format d'URL

    URL versionnée : /api/now/{api_version}/import/{stagingTableName}/insertMultiple

    URL par défaut : /api/now/import/{stagingTableName}/insertMultiple

    Remarque :
    Les versions disponibles sont spécifiées dans l’explorateur d’API REST. Pour les API REST scriptées, des informations supplémentaires sur la version se trouvent dans le formulaire Service REST scripté.

    Paramètres de demande pris en charge

    Remarque :
    La méthode POST du jeu d’importation accepte uniquement les paires nom-valeur des types de données Chaîne dans les paramètres de corps de la demande. Si un autre type de données est fourni, la valeur résultante stockée dans la table d’ensembles de données à importer peut ne pas être conforme au format prévu. Par exemple, la notion « : » de l’objet JSON imbriqué est changée en « = ».
    Tableau 13. Paramètres de chemin d'accès
    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
    stagingTableName Nom de la table de jeux d’importation à partir de laquelle importer les données. Consultez Concepts clés des ensembles d’importation.

    Type de données : chaîne
    Tableau 14. Paramètres de requête
    Nom Description
    multi_import_set_id Sys_id d’une entrée dans la table Multi Import Sets [sys_multi_import_set]. Si spécifié, ajoute l’importation actuelle à ce jeu d’importations multiples au lieu de l’ajouter à un nouveau jeu d’importations multiples.

    Type de données : chaîne

    Table :
    run_after Sys_id de l’entrée à exécuter. Permet d’exécuter le jeu d’importation actuel une fois le jeu d’importation spécifié terminé. Vous pouvez utiliser ce paramètre pour appliquer l’ordre séquentiel des importations.

    Ce paramètre n’est valide que dans les transformations asynchrones.

    Type de données : chaîne

    Table : Ensembles de données à importer [sys_import_set]
    Tableau 15. Corps de la demande (JSON)
    Format Description
    Fichier de source de données Ce format de corps de demande correspond au format de fichier JSON utilisé pour créer la source de données. Fournissez le corps de la demande au même format que le JSON dans la source de données. L’entrée JSON varie en fonction des propriétés de votre source de données. Reportez-vous aux informations JSON dans la source de données du type de fichier.
    • Cette option n’est disponible que si la table intermédiaire a été créée à l’aide d’une source de données JSON. Consultez Créer une source de données de type Fichier.
    • Vous devez définir le chemin d’accès de la source de données dans la table Source de données [sys_data_source] dans le champ Chemin d’accès de chaque ligne .
    • Pour modifier le comportement par défaut de l’utilisateur Insertion multiple REST, créez une entrée dans la table Insertion multiple REST [sys_rest_insert_multiple].
    • Activez l’option Utiliser le format de source de données dans l’insertion multiple REST.

    Type de données : objet
    Colonne de table intermédiaire (par défaut) Ce format de corps de demande correspond aux colonnes de la table intermédiaire. Utilisez le records tableau de paires clé-valeur correspondant à la colonne de la table intermédiaire à insérer dans les champs d’importation. Chaque clé JSON mappe la colonne de table à une valeur JSON représentant la valeur à insérer. L’entrée JSON varie en fonction des champs de votre table intermédiaire.

    La valeur clé par défaut du mappage de colonne est vers la table de colonnes.

    {
   "records":[
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      },
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      }
   ]
}
    Vous pouvez modifier les paramètres de mappage en ajoutant une entrée dans la table Multiples d’insertion REST [sys_rest_insert_multiple] et en changeant le mappage de colonne de Étiquette à Nom de colonne.
    {
   "records":[
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      },
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      }
   ]
}

    Fournit Data dictionary tables des détails sur les champs de table du système.

    Type de données : tableau

    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.

    Tableau 16. En-têtes de demandes
    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 des données du corps de la demande. Prend uniquement en charge application/json.
    Tableau 17. En-têtes de réponses
    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.

    Tableau 18. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été traitée avec succès.
    201 Réussi. La demande a été créé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.

    Corps de la réponse (JSON)

    Nom Description
    import_set_id Sys_id de l’enregistrement ajouté. Pour les demandes asynchrones, vous pouvez utiliser cette valeur pour exécuter un autre jeu d’importation une fois ce processus de jeu d’importation terminé.

    Type de données : chaîne

    Table : Ensembles de données à importer [sys_import_set]
    multi_import_set_id Sys_id de l’enregistrement ajouté. Utilisez cette valeur pour regrouper plusieurs ensembles de données à importer en un seul ensemble.

    Type de données : chaîne

    Table : Multi Import Sets [sys_multi_import_set]

    Exemple de demande cURL

    L’exemple suivant montre comment exécuter une transformation sur une table d’importation appelée u_employee_import_set_table à l’aide du format de colonne de table intermédiaire.

    curl "https://instance.servicenow.com/api/now/import/u_employee_import_set_table/insertMultiple" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"records\": [
  {
   \"Address\": \"Hollywood\",
   \"Name\": \"Tom\",
   \"ID\": \"123\"
  },
  {
   \"Address\": \"Vine\",
   \"Name\": \"Irene\",
   \"ID\": \"456\"
  }
  ]
}" \
--user 'username':'password'

    Les résultats incluent sys_ids pour les nouveaux enregistrements dans les tables Ensembles d’importation [sys_import_set] et Multi Import Sets [sys_multi_import_set].

    {
  "import_set_id": "<import_set_sys_id>",
  "multi_import_set_id": "<multi_import_set_sys_id>"
}