Importsatz-API

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 8 Minuten Lesedauer

    • Die Importsatz- API stellt Endpunkte bereit, die Ihnen die Interaktion mit Importsatztabellen ermöglichen.

    Diese API wandelt eingehende Daten basierend auf zugeordneten Transformationszuordnungen um. Die Import Set API unterstützt synchrone Transformationen. Die Import Set API spiegelt die vorhandene SOAP-Schnittstelle wider.

    Sicherheit

    Der Zugriff auf Tabellen über die REST API ist durch BasicAuth eingeschränkt. Um den Zugriff auf Tabellen ohne Authentifizierung oder Autorisierung zu ermöglichen, fügen Sie den Tabellennamen zu sys_public.list hinzu. Für Tabellen definierte ACLs werden weiterhin erzwungen, und der Administrator ist für die Deaktivierung von ACLs verantwortlich.

    Importsatz – GET /now/import/{stagingTableName}/{sys_id}

    Ruft den angegebenen Importbereitstellungsdatensatz und das resultierende Transformationsergebnis ab.

    URL-Format

    URL mit Versionsnummer: /api/now/{api_version}/import/{stagingTableName}/{sys_id}

    Standard-URL: /api/now/import/{stagingTableName}/{sys_id}

    Hinweis:
    Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    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
    stagingTableName Name der Tabelle, aus der die Importdaten abgerufen werden sollen.

    Datentyp: Zeichenfolge
    sys_id Sys_id des Datensatzes, der die Daten enthält.

    Datentyp: Zeichenfolge
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    Keine

    Kopfzeilen

    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.

    Tabelle : 4. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml.

    Standard: application/json
    Tabelle : 5. Antwortkopfzeilen
    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.

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    401 Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
    404 Gibt an, dass die angegebene Ressource nicht verfügbar war. Da Importsatztabellen häufig nach einem Zeitplan gelöscht werden, geben GET-Anforderungen möglicherweise die Antwort 404 Nicht gefunden zurück, wenn das Transformationsergebnis nicht mehr vorhanden ist.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Parameter des Antworttexts (JSON oder XML)

    Name Beschreibung
    import_set Name des Importsatzes

    Datentyp: Zeichenfolge
    Ergebnis Liste von Objekten, die Informationen zu den importierten Datensätzen enthalten.
    Datentyp: Array
    "result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]
    result.display_name Anzeigename des Importsatzes.

    Datentyp: Zeichenfolge
    result.display_value Wert des Importsatzes.

    Datentyp: Zeichenfolge
    result.record_link Tabellen-API-GET-Anforderung für den importierten Datensatz.

    Datentyp: Zeichenfolge
    result.status Status des Imports

    Datentyp: Zeichenfolge
    result.sys_id Sys_id des Importdatensatzes.

    Datentyp: Zeichenfolge
    result.table Name der Tabelle, in die die Daten importiert wurden.

    Datentyp: Zeichenfolge
    result.transform_map Name der Transformationszuordnung.

    Datentyp: Zeichenfolge
    staging_table Name der Importbereitstellungstabelle.

    Datentyp: Zeichenfolge

    Beispiel für eine cURL-Anforderung

    curl "https://instance.servicenow.com/api/now/import/imp_user/e2928be64f411200adf9f8e18110c777" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    {
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.service-now.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

    Importsatz – POST /now/import/{stagingTableName}

    Fügt eingehende Daten in eine angegebene Bereitstellungstabelle ein und löst die Transformation basierend auf vordefinierten Transformationszuordnungen in der Importsatztabelle aus.

    Die Transformation erfolgt synchron. Für jede von Ihnen definierte Transform Map enthalten die Antworten Transformationsergebnisse, z. B. Informationen zu den Zieldatensätzen.
    Hinweis:
    Die Felder status_message und error_message in Umwandlungsskripts werden zusammen mit benutzerdefinierten Antwortfeldern verarbeitet und als Antwort zurückgegeben.

    URL-Format

    URL mit Versionsnummer: /api/now/{api_version}/import/{stagingTableName}

    Standard-URL: /api/now/import/{stagingTableName}

    Hinweis:
    Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

    Unterstützte Anforderungsparameter

    Hinweis:
    Die Importsatz-POST-Methode akzeptiert nur Name/Wert-Paare des Datentyps Zeichenfolge in Anforderungstextparametern. Wenn ein anderer Datentyp angegeben wird, entspricht der in der Importsatztabelle gespeicherte resultierende Wert möglicherweise nicht dem beabsichtigten Format. Beispielsweise wird der Begriff „":"“ des geschachtelten JSON-Objekts in „=“ geändert.
    Tabelle : 7. Pfad-Parameter
    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
    stagingTableName Name der Tabelle, aus der die Daten importiert werden sollen.

    Datentyp: Zeichenfolge
    Tabelle : 8. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 9. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    Anrufspezifisch In die Importfelder einzufügende Name-Wert-Paare.

    Datentyp: Zeichenfolge

    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.

    Tabelle : 10. Anforderungskopfzeilen
    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
    Tabelle : 11. Antwortkopfzeilen
    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.

    Tabelle : 12. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    201 Erfolgreich. Die Anforderung wurde erfolgreich erstellt.
    401 Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Parameter des Antworttexts (JSON oder XML)

    Name Beschreibung
    import_set Name des Importsatzes

    Datentyp: Zeichenfolge
    Ergebnis Liste von Objekten, die Informationen zu den importierten Datensätzen enthalten.
    Datentyp: Array
    "result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]
    result.display_name Anzeigename des Importsatzes.

    Datentyp: Zeichenfolge
    result.display_value Wert des Importsatzes.

    Datentyp: Zeichenfolge
    result.record_link Tabellen-API-GET-Anforderung für den importierten Datensatz.

    Datentyp: Zeichenfolge
    result.status Status des Imports

    Datentyp: Zeichenfolge
    result.sys_id Sys_id des Importdatensatzes.

    Datentyp: Zeichenfolge
    result.table Name der Tabelle, in die die Daten importiert wurden.

    Datentyp: Zeichenfolge
    result.transform_map Name der Transformationszuordnung.

    Datentyp: Zeichenfolge
    staging_table Name der Importbereitstellungstabelle.

    Datentyp: Zeichenfolge

    Beispiel für eine cURL-Anforderung

    curl "https://instance.servicenow.com/api/now/import/imp_user" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{'first_name':'John','last_name':'Public','user_id':'john.public','email':'john.public@company.com'}" \
--user "username":"password"
    {
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.servicenow.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

    Importsatz: POST /now/import/{stagingTableName}/insertMultiple

    Fügt mehrere Datensätze in eine angegebene Bereitstellungstabelle ein und löst die Transformation basierend auf vordefinierten Transformationszuordnungen oder RTE-Konfigurationen (Robust Transform Engine) in einer einzigen Anforderung aus.

    Die Transformation ist standardmäßig asynchron. Um die synchrone Transformation festzulegen, erstellen Sie einen neuen Datensatz in der Tabelle REST Insert Multiples [sys_rest_insert_multiple], wählen Sie die Quelltabelle aus, und legen Sie die Transformation auf synchron fest.

    Dieser Endpunkt kann einen Anforderungstext in zwei möglichen Formaten senden.
    Dateiformat der Datenquelle
    Wenn Sie eine Bereitstellungstabelle aus einer JSON-Datenquelle generieren, entsprechen Sie dem JSON-Format der Quelldatei.
    Spaltenformat der Bereitstellungstabelle
    Standard Entspricht dem Format des Anforderungstexts der Bereitstellungstabellenspalte in Schlüssel-Wert-Paaren.

    URL-Format

    URL mit Versionsnummer: /api/now/{api_version}/import/{stagingTableName}/insertMultiple

    Standard-URL: /api/now/import/{stagingTableName}/insertMultiple

    Hinweis:
    Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

    Unterstützte Anforderungsparameter

    Hinweis:
    Die Importsatz-POST-Methode akzeptiert nur Name/Wert-Paare des Datentyps Zeichenfolge in Anforderungstextparametern. Wenn ein anderer Datentyp angegeben wird, entspricht der in der Importsatztabelle gespeicherte resultierende Wert möglicherweise nicht dem beabsichtigten Format. Beispielsweise wird der Begriff „":"“ des geschachtelten JSON-Objekts in „=“ geändert.
    Tabelle : 13. Pfad-Parameter
    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
    stagingTableName Name der Importsatztabelle, aus der die Daten importiert werden sollen. Weitere Informationen finden Sie unter Importsätze – Schlüsselkonzepte.

    Datentyp: Zeichenfolge
    Tabelle : 14. Abfrageparameter
    Name Beschreibung
    multi_import_set_id Sys_id eines Eintrags in der Tabelle „Multi-Importsätze“ [sys_multi_import_set]. Wenn angegeben, wird der aktuelle Import diesem Mehrfach-Importsatz hinzugefügt, anstatt ihn einem neuen Mehrfach-Importsatz hinzuzufügen.

    Datentyp: Zeichenfolge

    Tabelle:
    run_after Sys_id des auszuführenden Eintrags. Aktiviert die Ausführung des aktuellen Importsatzes, nachdem der angegebene Importsatz abgeschlossen ist. Sie können diesen Parameter verwenden, um die sequenzielle Reihenfolge der Importe zu erzwingen.

    Dieser Parameter ist nur in asynchronen Transformationen gültig.

    Datentyp: Zeichenfolge

    Tabelle: Importsätze [sys_import_set]
    Tabelle : 15. Anforderungstext (JSON)
    Format Beschreibung
    Datenquellendatei Dieses Format des Anforderungstexts entspricht dem JSON-Dateiformat, das zum Erstellen der Datenquelle verwendet wird. Geben Sie den Anforderungstext im gleichen Format wie JSON in der Datenquelle an. Die JSON-Eingabe hängt von den Eigenschaften in Ihrer Datenquelle ab. Weitere Informationen finden Sie unter Dateityp-Datenquelle.
    • Diese Option ist nur verfügbar, wenn die Bereitstellungstabelle mit einer JSON-Datenquelle erstellt wurde. Weitere Informationen finden Sie unter Datenquelle vom Typ „Datei“ erstellen.
    • Sie müssen den Pfad der Datenquelle in der Tabelle „Datenquelle“ [sys_data_source] im Feld Pfad für jede Zeile definieren.
    • Um das Standardverhalten für den Anwender von „REST Insert Multiple“ zu ändern, erstellen Sie einen Eintrag in der Tabelle „REST Insert Multiples“ [sys_rest_insert_multiple].
    • Aktivieren Sie das Datenquellenformat verwenden im Eintrag REST Insert Multiple (Mehrere einfügen).

    Datentyp: Objekt
    Bereitstellungstabellenspalte (Standard) Dieses Format des Anforderungstexts entspricht Staging-Tabellenspalten. Verwenden Sie das Array records von Schlüssel-Wert-Paaren, die der Bereitstellungstabellenspalte entsprechen, um sie in die Importfelder einzufügen. Jeder JSON-Schlüssel ordnet die Tabellenspalte einem JSON-Wert zu, der den einzufügenden Wert darstellt. Die JSON-Eingabe variiert je nach den Feldern in Ihrer Bereitstellungstabelle.

    Der Standardschlüsselwert für die Spaltenzuordnung bezieht sich auf die Spaltentabelle.

    {
   "records":[
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      },
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      }
   ]
}
    Sie können die Zuordnungseinstellungen ändern, indem Sie in der Tabelle „Rest Insert Multiples“ [sys_rest_insert_multiple] einen Eintrag hinzufügen und die Spaltenzuordnung von „Bezeichnung“ in „Spaltenname“ändern.
    {
   "records":[
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      },
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      }
   ]
}

    Data dictionary tables enthält Details zu Tabellenfeldern im System.

    Datentyp: Array

    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.

    Tabelle : 16. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützt nur application/json.
    Content-Type Datenformat des Anforderungstexts. Unterstützt nur application/json.
    Tabelle : 17. Antwortkopfzeilen
    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.

    Tabelle : 18. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    201 Erfolgreich. Die Anforderung wurde erfolgreich erstellt.
    401 Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Antworttext (JSON)

    Name Beschreibung
    import_set_id Sys_id des hinzugefügten Datensatzes. Bei asynchronen Anforderungen können Sie diesen Wert verwenden, um einen weiteren Importsatz auszuführen, nachdem der Importsatzvorgang abgeschlossen wurde.

    Datentyp: Zeichenfolge

    Tabelle: Importsätze [sys_import_set]
    multi_import_set_id Sys_id des hinzugefügten Datensatzes. Verwenden Sie diesen Wert, um mehrere Importsätze in einem Satz zu gruppieren.

    Datentyp: Zeichenfolge

    Tabelle: Multi-Importsätze [sys_multi_import_set]

    Beispiel für eine cURL-Anforderung

    Das folgende Beispiel zeigt, wie eine Transformation für eine Importtabelle namens u_employee_import_set_table mithilfe des Spaltenformats der Bereitstellungstabelle ausgeführt wird.

    curl "https://instance.servicenow.com/api/now/import/u_employee_import_set_table/insertMultiple" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"records\": [
  {
   \"Address\": \"Hollywood\",
   \"Name\": \"Tom\",
   \"ID\": \"123\"
  },
  {
   \"Address\": \"Vine\",
   \"Name\": \"Irene\",
   \"ID\": \"456\"
  }
  ]
}" \
--user 'username':'password'

    Die Ergebnisse enthalten sys_ids für neue Datensätze in den Tabellen „Importsätze“ [sys_import_set] und „Multi-Importsätze“ [sys_multi_import_set].

    {
  "import_set_id": "<import_set_sys_id>",
  "multi_import_set_id": "<multi_import_set_sys_id>"
}