CMDB Datenerfassungs-API
Die CMDB-Datenerfassungs- API stellt Endpunkte bereit, die die Batch-Erfassung eines Arrays von Objekten in einer Import Set-Tabelle ermöglichen.
Darüber hinaus funktioniert diese API standardmäßig nicht für Instanzen mit zBoot.
Diese API wird über das Plugin Configuration Management Database (CMDB) (com.snc.cmdb) aktiviert und erfordert die Rolle cmdb_import_api_admin.
CMDB Datenerfassung – POST /cmdb/ingest/{data_source_sys_id}
Fügt Datensätze in die Import Set-Tabelle ein, die dem Datenquellen-Datensatz zugeordnet ist, der durch die übergebene sys_id identifiziert wird.
Darüber hinaus funktioniert diese API standardmäßig nicht für Instanzen mit zBoot.
Der Anforderungstext muss das JSON-Array von Objekten (Nutzlast) enthalten, die in die Import Set-Tabelle eingefügt werden sollen. Jedes Objekt entspricht einer Zeile in der Tabelle, jedes Name-Wert-Paar entspricht einer Spalte. Die JSON-Nutzlast muss die Feldnamen aus dem Importsatz ohne das Präfix „u_“ nutzen. Zum Beispiel muss der Feldname „u_matching_record“ in der Nutzlast des Anforderungstexts „matching_record“ sein. Wenn die Import Set-Tabelle vorhanden ist, hängt der Endpunkt die Zeilen (Objekte) an die vorhandene Import Set-Tabelle an. Es wird nicht auf Duplikate gesucht oder vorhandene Datensätze aktualisiert.
Wenn Sie anfänglich eine Anwendung erstellen, müssen Sie zuerst den zugehörigen Datenquellendatensatz in Ihrer Instanz erstellen, bevor Sie diesen Endpunkt aufrufen. Wenn Sie diesen Endpunkt nur verwenden, um Datensätze zu einer vorhandenen Import Set-Tabelle hinzuzufügen, müssen Sie den Datenquellen-Datensatz nicht erstellen, aber Sie müssen seine sys_id kennen. Der Datenquellendatensatz beschreibt die Import Set-Tabelle, in die die angegebene Nutzlast eingefügt werden soll. Diese Tabelle muss die Tabelle „Import Set-Zeilen“ [sys_import_set_row] erweitern. Außerdem muss die Datenquelle auf Anhang und das Format auf JSONfestgelegt werden. Weitere Informationen zu Datenquellen finden Sie unter Datenquellen.
Wenn die im Datenquellendatensatz definierte Import Set-Tabelle nicht vorhanden ist, hängt der Endpunkt die übergebene Nutzlast an den Datenquellendatensatz an. Um die anfängliche Import Set-Tabelle zu erstellen, müssen Sie die Daten manuell in die Import Set-Tabelle importieren. Um die Daten zu importieren, klicken Sie im zugehörigen Formular „Datenquelle“ im Abschnitt „Zugehörige Links“ auf den Link Testladen von 20 Datensätzen oder Alle Datensätze laden. Sobald die Import Set-Tabelle erstellt wurde, können Sie der Tabelle mit diesem Endpunkt keine Spalten mehr hinzufügen. Wenn später Name-Wert-Paare übergeben werden, die in der Import Set-Tabelle nicht vorhanden sind, werden sie ohne Warnung ignoriert. Wenn Sie die Spalten in der Import Set-Tabelle ändern müssen, können Sie sie der Tabelle manuell hinzufügen. Sie können auch die Import Set-Tabelle löschen oder umbenennen und den Endpunkt mit der neuen Nutzlast erneut aufrufen.
Sie müssen über die Rolle cmdb_import_api_admin verfügen, um auf diesen Endpunkt zugreifen zu können.
URL-Format
Versionierte URL: /api/now/{api_version}/cmdb/ingest/{data_source_sys_id}
Standard-URL: /api/now/cmdb/ingest/{data_source_sys_id}
Unterstützte Anforderungsparameter
| Name | Beschreibung |
|---|---|
| api_version | Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge |
| data_source_sys_id | Sys_id des Datenquellen-Datensatzes. |
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| Array | Freiform-Array von Objekten, die die Daten beschreiben, die an die zugeordnete Import Set-Tabelle angehängt werden sollen. Jedes Objekt im Array definiert eine Zeile in der Tabelle „Import Sets“; jedes Name-Wert-Paar eine Spalte. Hinweis: Dieses Array muss einen Namen haben, z. B. "{\"records\":[{\"hostname\": \"Hostname1\", \"serialnumber\": \"2acd3873-7fc5-454c-8844-e7769e4d6cfc\", \"model\": \"Modell-ID"},{\"vendor\": \"ABC Co\"}]}". |
Header
Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST-API verwendet werden, finden Sie unter Unterstützte REST-API-Header.
| Kopfzeile | Beschreibung |
|---|---|
| Akzeptieren | Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json |
| Content-Type | Datenformat des Anforderungstexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json |
| Kopfzeile | Beschreibung |
|---|---|
| Keine |
Statuscodes
Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST-API verwendet werden, finden Sie unter HTTP-Antwortcodesder REST-API.
| Statuscode | Beschreibung |
|---|---|
| 201 | Erstellt. Der Datenquelle wurde ein Anhang hinzugefügt. |
| 202 | Akzeptiert. Zeilen wurden der Import Set-Tabelle hinzugefügt. |
| 400 | Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt. |
| 404 | Nicht gefunden. Das angeforderte Element wurde nicht gefunden. |
| 409 | Konflikt. Anhang ist bereits in der Datenquelle vorhanden. |
| 500 | Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler. |
| 501 | Nicht implementiert. Anforderungsformat wird nicht unterstützt. |
Antworttextparameter (JSON oder XML)
| Name | Beschreibung |
|---|---|
| Fehler | Beschreibt einen aufgetretenen Fehler. Datentyp: Objekt |
| Fehler.Details | Zusätzliche Informationen zum Fehler. Datentyp: Zeichenfolge |
| Fehler.Nachricht | Meldung, die den Fehler beschreibt. Datentyp: Zeichenfolge |
| import_set | Name der Import Set-Tabelle, an die die Nutzlast angehängt wurde. Datentyp: Zeichenfolge |
| staged_row_count | Anzahl der an die Import Set-Tabelle angehängten Zeilen. Datentyp: Zahl |
| staging_table | Name des Datenquellen-Datensatzes, der zum Bereitstellen der Nutzlast verwendet wird. Datentyp: Zeichenfolge |
| status | Fehlerstatus. Datentyp: Zeichenfolge |
Beispiel für eine cURL-Anforderung
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"Erfolgreiche Antwort:
{
"result": {
"staged_row_count": 2,
"import_set": "ISET0010010",
"staging_table": "sn_my_demo_integra_demo_data_source_01"
}
}