API de jeu d'importation

  • Rversion finale: Zurich
  • Mis à jour 31 juil. 2025
  • 11 minutes de lecture

    • L’API de jeu d’importation fournit des points de terminaison qui vous permettent d’interagir avec les tables de jeu 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 restreint par BasicAuth. Pour autoriser l’accès aux tables sans 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 incombe à 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 la 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 basées sur un script, des informations de version supplémentaires sont disponibles sur 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 différente de la dernière.

    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
    Aucun
    Tableau 3. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    Aucun

    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 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
    Aucun

    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é correctement traitée.
    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. Étant donné que les tables de jeux d’importation sont fréquemment supprimées en fonction d’une planification, les demandes GET peuvent renvoyer des réponses 404 Introuvable 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'importations.

    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 du jeu d’importation.

    Type de données : chaîne
    result.display_value Valeur du jeu d’importation.

    Type de données : chaîne
    result.record_link API de table Demande GET 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 en fonction 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 basées sur un script, des informations de version supplémentaires sont disponibles sur 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 de jeu d’importation 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 différente de la dernière.

    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
    Aucun
    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 à cette action HTTP uniquement 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 de 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
    Aucun

    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é correctement traitée.
    201 Réussi. La demande a été créée avec succès.
    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'importations.

    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 du jeu d’importation.

    Type de données : chaîne
    result.display_value Valeur du jeu d’importation.

    Type de données : chaîne
    result.record_link API de table Demande GET 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 en fonction de cartes de transformation prédéfinies ou de 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 Insertion multiple 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 la source de données
    Si vous générez une table intermédiaire à partir d’une source de données JSON, respectez le format JSON du fichier source.
    Format de colonne de la table intermédiaire
    Faire défaut. Correspond au format de corps 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 basées sur un script, des informations de version supplémentaires sont disponibles sur 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 de jeu d’importation 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 différente de la dernière.

    Type de données : chaîne
    stagingTableName Nom de la table de jeux d’importation à partir de laquelle importer les données. Reportez-vous à la section Concepts clés des jeux 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 Jeux d’importation multiples [sys_multi_import_set]. Si spécifié, ajoute l’importation actuelle à ce jeu d’importation multiple au lieu de l’ajouter à un nouveau jeu d’importation multiple.

    Type de données : chaîne

    Table :
    run_after Sys_id de l’entrée à exécuter. Permet l’exécution du 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 : jeux d’importation [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 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. Reportez-vous à la section 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 le format Utiliser la source de données dans l’insertion multiple REST.

    Type de données : objet
    Colonne de la 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 colonnes concerne 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 dans le système.

    Type de données : tableau

    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 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.
    Content-Type Format de 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
    Aucun

    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é correctement traitée.
    201 Réussi. La demande a été créée avec succès.
    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 : jeux d’importation [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 en utilisant le format de colonne de la 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 Jeux 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>"
}