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.
En outre, 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 de jeux d’importation associée à l’enregistrement de source de données identifié par l’sys_id transmis.
En outre, 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 extraire 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 Jeu d’importation existe, le point de terminaison ajoute les lignes (objets) à la table Jeu d’importation 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 jeu 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 de jeu d’importation dans laquelle insérer la charge utile spécifiée. Cette table doit étendre la table Lignes du jeu d’importation [sys_import_set_row]. En outre, la source de données doit être définie sur Pièce jointe et le format sur JSON. Pour plus d’informations sur les sources de données, reportez-vous à la rubrique Sources de données.
Si la table Jeux 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 Sets initiale, vous devez importer manuellement les données dans la table Import Sets. Pour importer les données, sur le formulaire de source de données associé, cliquez sur le lien Tester le chargement de 20 enregistrements ou 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 de jeu d’importation sont transmises ultérieurement, elles sont ignorées sans avertissement. Si vous devez modifier les colonnes de la table de jeux d’importation, vous pouvez les ajouter manuellement à la table. Vous pouvez également supprimer ou renommer la table de jeux d’importation, puis appeler à nouveau le point de terminaison à l’aide de la nouvelle charge utile.
Vous devez avoir le 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 |
|---|---|
| Néant |
| Nom | Description |
|---|---|
| Tableau | Tableau de forme libre d’objets qui décrit les données à ajouter à la table de jeux d’importation associée. Chaque objet du tableau définit une ligne dans la table Jeux d’importation ; Chaque paire nom-valeur a une colonne. Remarque : Ce tableau doit être nommé, par exemple « {\"records\ » :[{\"hostname\ » : \"Hostname1\ », \"serialnumber\ » : \"2acd3873-7fc5-454c-8844-e7769e4d6cfc\ », \"model\ » : \"Model Id"},{\"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 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.
| 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 une 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é. 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 de corps de réponse (JSON ou XML)
| Nom | Description |
|---|---|
| erreur | Décrit une erreur rencontrée. Type de données : objet |
| erreur.détails | Informations supplémentaires sur l’erreur. Type de données : chaîne |
| message d’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 de jeux 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 correcte :
{
"result": {
"staged_row_count": 2,
"import_set": "ISET0010010",
"staging_table": "sn_my_demo_integra_demo_data_source_01"
}
}