CMDB Datenerfassungs-API
Die CMDB-Datenerfassungs -API stellt Endpunkte bereit, die die Batch-Erfassung eines Arrays von Objekten in einer Importsatztabelle ermöglichen.
Darüber hinaus funktioniert diese API bei zBoot-Instanzen nicht standardmäßig.
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 Importsatztabelle ein, die dem Datenquellen-Datensatz zugeordnet ist, der durch die übergebene sys_id identifiziert wird.
Darüber hinaus funktioniert diese API bei zBoot-Instanzen nicht standardmäßig.
Der Anforderungstext muss das JSON-Array von Objekten (Nutzlast) enthalten, die in die Importsatztabelle 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. Beispielsweise sollte der Feldname „u_matching_record“ in der Nutzlast des Anforderungstexts „matching_record“ sein. Wenn die Importsatztabelle vorhanden ist, hängt der Endpunkt die Zeilen (Objekte) an die vorhandene Importsatztabelle an. Es wird nicht nach Duplikaten gesucht oder ein Update vorhandener Datensätze durchgeführt.
Wenn Sie zum ersten Mal 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 zum Hinzufügen von Datensätzen zu einer vorhandenen Importsatztabelle verwenden, müssen Sie den Datenquellen-Datensatz nicht erstellen, Sie müssen jedoch dessen sys_id kennen. Der Datenquellendatensatz beschreibt die Importsatztabelle, in die die angegebene Nutzlast eingefügt werden soll. Diese Tabelle muss die Tabelle „Importsatzzeilen“ [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 Importsatztabelle nicht vorhanden ist, hängt der Endpunkt die übergebene Nutzlast an den Datenquellendatensatz an. Um die erste Importsatztabelle zu erstellen, müssen Sie die Daten manuell in die Importsatztabelle importieren. Um die Daten zu importieren, klicken Sie im zugehörigen Datenquellenformular im Abschnitt „Zugehörige Links“ auf den Link „20 Datensätze testen“ oder „Alle Datensätze laden“. Sobald die Importsatztabelle erstellt wurde, können Sie ihr mit diesem Endpunkt keine Spalten hinzufügen. Wenn später Name-Wert-Paare übergeben werden, die in der Importsatztabelle nicht vorhanden sind, werden sie ohne Warnung ignoriert. Wenn Sie die Spalten in der Importsatztabelle ändern müssen, können Sie sie der Tabelle manuell hinzufügen. Sie können die Importsatztabelle auch 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
URL mit Versionsnummer: /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 Datenquelldatensatzes. Datentyp: Zeichenfolge |
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| Array | Freiform-Array von Objekten, welche die Daten beschreiben, die an die zugehörige Importsatztabelle angehängt werden sollen. Jedes Objekt im Array definiert eine Zeile in der Importsatztabelle. 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\"}]}".Datentyp: Array von Objekten |
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-Antwortcodes der REST-API.
| Statuscode | Beschreibung |
|---|---|
| 201 | Erstellt Der Datenquelle wurde ein Anhang hinzugefügt. |
| 202 | Akzeptiert. Der Importsatztabelle wurden Zeilen 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 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. |
Parameter des Antworttexts (JSON oder XML)
| Name | Beschreibung |
|---|---|
| Fehler | Beschreibt einen aufgetretenen Fehler. Datentyp: Objekt |
| Fehler.Details | Zusätzliche Informationen zum Fehler. Datentyp: Zeichenfolge |
| Fehlernachricht | Meldung, in der der Fehler beschrieben wird. Datentyp: Zeichenfolge |
| import_set | Name der Importsatztabelle, an die die Nutzlast angehängt wurde. Datentyp: Zeichenfolge |
| staged_row_count | Anzahl der Zeilen, die an die Importsatztabelle angehängt sind. 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"
}
}