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 jeu 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 de 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 équivaut à 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 d’ensemble d’importation existe, le point de terminaison ajoute les lignes (objets) à la table d’ensemble d’importation existante. Aucune vérification des doublons ni 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 la source de données associée 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 de 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, voir Sources de données.
Si la table Import Set 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 d’ensemble d’importation initiale, vous devez importer manuellement les données dans la table d’ensemble d’importation. Pour importer les données, sur le formulaire 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 Import Set créée, vous ne pouvez pas y ajouter de colonnes à l’aide de ce point de terminaison. Si des paires nom-valeur qui n’existent pas dans la table Import Set 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. 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 |
| data_source_sys_id | Sys_id de l’enregistrement de source de données. Type de données : chaîne |
| Nom | Description |
|---|---|
| Néant |
| Nom | Description |
|---|---|
| Tableau | Tableau de forme libre d’objets qui décrivent les données à ajouter à la table d’ensembles d’importation associée. Chaque objet du tableau définit une ligne dans la table Import Sets ; 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\ » : \"Model Id"},{\"vendor\ » : \"ABC Co\"}]} ».Type de données : tableau d’objets |
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à sur 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 la 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 annexé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 organiser 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"
}
}