API de jeu d'importation

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 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 limité 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 est de la responsabilité de l’administrateur de désactiver les ACL.

    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}

    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. 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
    Nom de table intermédiaire 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. Comme 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 Not Found 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 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 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
    table.résultats 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}

    Paramètres de demande pris en charge

    Remarque :
    La méthode POST du jeu d’importation accepte uniquement les paires nom-valeur de types de données chaîne dans les paramètres du corps de la demande. Si un autre type de données est fourni, la valeur résultante stockée dans la table de jeux d’importation peut ne pas être conforme au format prévu. Par exemple, la notion « : » de l’objet JSON imbriqué est remplacée par « = ».
    Tableau 7. Paramètres de chemin d'accès
    Nom Description
    api_version Facultatif. Version du point de terminaison auquel accéder. 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
    Nom de table intermédiaire 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
    Spécifique à l’appel 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
    Content-Type 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 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 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
    table.résultats 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 des cartes de transformation prédéfinies ou des configurations du moteur de transformation robuste (RTE) dans une seule demande.

    La transformation est asynchrone par défaut. Pour définir la transformation synchrone, créez un nouvel enregistrement dans la table Multiple 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 du 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
    Faire défaut. Correspond au format du 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

    Paramètres de demande pris en charge

    Remarque :
    La méthode POST du jeu d’importation accepte uniquement les paires nom-valeur de types de données chaîne dans les paramètres du corps de la demande. Si un autre type de données est fourni, la valeur résultante stockée dans la table de jeux d’importation peut ne pas être conforme au format prévu. Par exemple, la notion « : » de l’objet JSON imbriqué est remplacée par « = ».
    Tableau 13. Paramètres de chemin d'accès
    Nom Description
    api_version Facultatif. Version du point de terminaison auquel accéder. 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
    Nom de table intermédiaire Nom de la table de jeux d’importation à partir de laquelle importer les données. Reportez-vous aux 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 Ensembles de données à importations multiples [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
    run_after Sys_id d’une entrée dans la table Jeux d’importation [sys_import_set]. Active l’exécution du jeu d’importation actuel une fois que le jeu d’importation spécifié est 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
    Tableau 15. Corps de la demande (JSON)
    Format Description
    Fichier 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. Consultez les 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 l’option Utiliser le format de source de données dans l’entrée multiple d’insertion 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 présents dans votre table intermédiaire.

    La valeur de clé par défaut du mappage de colonnes est 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 Multiple d’insertion REST [sys_rest_insert_multiple] et en remplaçant le mappage de colonnesÉtiquette par Nom de colonne.
    {
   "records":[
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      },
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      }
   ]
}

    Le Data dictionary tables fournit 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 réponse (JSON)

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

    Type de données : chaîne
    multi_import_set_id Sys_id de l’enregistrement ajouté à la table Ensembles de données à importations multiples [sys_multi_import_set]. Cette valeur permet de regrouper plusieurs ensembles d’importation en un seul ensemble.

    Type de données : chaîne

    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 de nouveaux enregistrements dans les tables Jeux d’importation [sys_import_set] et Jeux d’importation multiples [sys_multi_import_set].

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