CMDB API d’ingestion de données
L’API d’ingestion de données CMDB fournit des points de terminaison qui activent l’ingestion par lots d’un tableau d’objets dans une table de jeux d’importation.
De plus, cette API ne fonctionnera pas par défaut pour les instances zbooted.
Cette API est activée via le module d’extension Base de données de gestion des configurations (CMDB) (com.snc.cmdb) et nécessite le rôle cmdb_import_api_admin.
CMDB Ingestion de données : POST /cmdb/ingest/{data_source_sys_id}
Insère les enregistrements dans la table Jeu d’importation associée à l’enregistrement source de données identifié par le sys_id transmis.
De plus, cette API ne fonctionnera pas par défaut pour les instances zbooted.
Le corps de la demande doit contenir le tableau JSON d’objets (charge utile) à insérer dans la table Jeu d’importation. Chaque objet correspond à une ligne dans la table, chaque paire nom-valeur équivaut à une colonne. La charge utile JSON doit exploiter les noms de champs du jeu d’importation sans le préfixe « u_ ». Par exemple, le nom de champ « u_matching_record » doit être « matching_record » dans la charge utile du corps de la demande. Si la table Import Set (Jeu d’importation) existe, le point de terminaison ajoute les lignes (objets) à la table Import Set existante. Aucune vérification des doublons ou mise à jour des enregistrements existants n’est effectuée.
Si vous créez initialement une application, vous devez d’abord créer l’enregistrement de source de données associé dans votre instance avant d’appeler ce point de terminaison. Si vous utilisez simplement ce point de terminaison pour ajouter des enregistrements à une table de jeux d’importation existante, vous n’avez pas besoin de créer l’enregistrement de source de données, mais vous devez connaître son sys_id. L’enregistrement de source de données décrit la table Jeu d’importation dans laquelle insérer la charge utile spécifiée. Cette table doit étendre la table Lignes de jeux d’importation [sys_import_set_row]. En outre, la source de données doit être définie sur Pièce jointe et le format défini sur JSON. Pour plus d’informations sur les sources de données, consultez Sources de données.
Si la table Jeu d’importation définie dans l’enregistrement de source de données n’existe pas, le point de terminaison joint la charge utile transmise à l’enregistrement de source de données. Pour créer la table Import Set initiale, vous devez importer manuellement les données dans la table Import Set. Pour importer les données, cliquez sur le lien Tester le chargement de 20 enregistrements dans le formulaire de source de données associé ou sur le lien Charger tous les enregistrements dans la section Liens connexes. Une fois la table de jeux d’importation créée, vous ne pouvez pas ajouter de colonnes à la table à l’aide de ce point de terminaison. Si des paires nom-valeur qui n’existent pas dans la table Jeu d’importation sont transmises ultérieurement, elles sont ignorées sans avertissement. Si vous devez modifier les colonnes de la table Jeu d’importation, vous pouvez les ajouter manuellement à la table. Vous pouvez également supprimer ou renommer la table Import Set, et appeler à nouveau le point de terminaison à l’aide de la nouvelle charge utile.
Vous devez disposer du rôle cmdb_import_api_admin pour accéder à ce point de terminaison.
Format d'URL
URL versionnée : /api/now/{api_version}/cmdb/ingest/{data_source_sys_id}
URL par défaut : /api/now/cmdb/ingest/{data_source_sys_id}
Paramètres de demande pris en charge
| 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 |
| data_source_sys_id | Sys_id de l’enregistrement de source de données. |
| Nom | Description |
|---|---|
| Aucun |
| Nom | Description |
|---|---|
| Tableau | Tableau de forme libre d’objets qui décrit les données à ajouter à la table Jeu d’importation associée. Chaque objet du tableau définit une ligne dans la table Ensembles d’importation ; Chaque paire nom-valeur est une colonne. Remarque : Ce tableau doit être nommé, par exemple « {\"records\ » :[{\"hostname\ » : \"Hostname1\ », \"serialnumber\ » : \"2acd3873-7fc5-454c-8844-e7769e4d6cfc\ », \"model\ » : \"ID de modèle"},{\"vendor\ » : \"ABC Co\"}]} ». |
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.
| 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 |
| 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.
| Code d'état | Description |
|---|---|
| 201 | Créé. Une pièce jointe a été ajoutée à la source de données. |
| 202 | Accepté. Des lignes ont été ajoutées à la table Jeu d’importation. |
| 400 | Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté. |
| 404 | Introuvable. L’élément demandé est introuvable. |
| 409 | Conflit. La pièce jointe existe déjà dans la source de données. |
| 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. |
| 501 | Non implémenté. Le format de la demande n’est pas pris en charge. |
Paramètres du corps de réponse (JSON ou XML)
| Nom | Description |
|---|---|
| erreur | Décrit une erreur rencontrée. Type de données : objet |
| error.details | Informations supplémentaires sur l’erreur. Type de données : chaîne |
| message.erreur | Message décrivant l’erreur. Type de données : chaîne |
| import_set | Nom de la table de jeu d’importation à laquelle la charge utile a été ajoutée. Type de données : chaîne |
| staged_row_count | Nombre de lignes ajoutées à la table Jeu d’importation. Type de données : nombre |
| staging_table | Nom de l’enregistrement de source de données utilisé pour préparer la charge utile. Type de données : chaîne |
| statut | État de l’erreur. Type de données : chaîne |
Exemple de demande cURL
curl "instance.service-now.com/api/now/cmdb/ingest/4dd9686d1b9800103d374087bc4bcb3d" \
--request POST \
--header "Accept: application/json" \
--header "Content-Type:application/json" \
--data "{\"records\":[{\"hostname\": \"Hostname1\", \"serialnumber\": \"2acd3873-7fc5-454c-8844-e7769e4d6cfc\", \"model\": \"Model 5100"},{\"vendor\": \"ABC Co\"},
{\"hostname\": \"Hostname2\", \"serialnumber\": \"3adb3873-7fc5-564d-8844-e7769e4d6ded\", \"model\": \"Model 5200"},{\"vendor\": \"ACME Co\"}]}"
--user "username":"password"Réponse réussie :
{
"result": {
"staged_row_count": 2,
"import_set": "ISET0010010",
"staging_table": "sn_my_demo_integra_demo_data_source_01"
}
}