API de jeu d'importation

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 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.

    L’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 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
    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 à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir une 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 une 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 jeu d’importation sont supprimées fréquemment en fonction d’un calendrier, 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 de 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’importations.

    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ésultat 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 façon 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, de même que 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 n’accepte que 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 jeux 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. 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
    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 à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir une 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 une 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 de 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’importations.

    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ésultat 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 comme synchrone.

    Ce point de terminaison peut envoyer un corps de requête 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
    Par défaut. Correspond au format de corps de la demande de colonne de 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 n’accepte que 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 jeux 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. 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 jeu d’importation à partir de laquelle importer les données. Reportez-vous aux 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 cette option est spécifiée, elle 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]. Permet d’exécuter le jeu d’importation actuel une fois que le jeu d’importations 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 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 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. 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 de votre table intermédiaire.

    La valeur 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 Rest Insert Multiple [sys_rest_insert_multiple] et en remplaçant le mappage de colonneÉtiquette par Nom de colonne.
    {
   "records":[
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      },
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      }
   ]
}

    Le dictionnaire de données fournit 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 à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir une 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 une 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 de jeu d’importation terminé.

    Type de données : chaîne
    multi_import_set_id Sys_id de l’enregistrement ajouté à la table Jeux d’importation multiples [sys_multi_import_set]. Cette valeur peut être utilisée pour regrouper plusieurs jeux 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 pour les 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>"
}