Importsatz-API

  • Freigeben Version: Zurich
  • Aktualisiert 31. Juli 2025
  • 8 Minuten Lesedauer

    • Die Importsatz Die API stellt Endpunkte bereit, mit denen Sie mit Importsatztabellen interagieren können.

    Diese API transformiert eingehende Daten basierend auf zugehörigen Transformationszuordnungen. 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

    Versionierte URL: /api/now/{api_Version}/Import/{stagingTableName}/{sys_ID}

    Standard-URL: /api/now/Import/{stagingTableName}/{sys_ID}

    Hinweis:
    Verfügbare Versionen werden in angegeben REST API-Explorer . Für geskriptete REST-APIs gibt es zusätzliche Versionsinformationen auf der Formular „geskripteter REST-Service“ .

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    api_version Optional. Version des Endpunkts, auf den zugegriffen werden soll. Beispiel: v1 Oder v2 . Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden.

    Datentyp: Zeichenfolge
    Staging TableName 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 REST API-HTTP-Antwortcodes .

    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 basierend auf einem Zeitplan gelöscht werden, können GET-Anforderungen 404 nicht gefundene Antworten zurückgeben, 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.

    Antworttext-Parameter (JSON oder XML)

    Name Beschreibung
    import_set Name des Importsatzes

    Datentyp: Zeichenfolge
    Ergebnis Liste der Objekte, 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"
  }
]
    Ergebnis.Anzeigename Anzeigename des Importsatzes.

    Datentyp: Zeichenfolge
    Ergebnis.Anzeigewert Wert des Importsatzes.

    Datentyp: Zeichenfolge
    Ergebnis.Datensatz_Link Tabellen-API RUFT die Anforderung für den importierten Datensatz AB.

    Datentyp: Zeichenfolge
    Ergebnis.Status Status des Imports.

    Datentyp: Zeichenfolge
    Ergebnis.sys_ID SYS_ID des Importdatensatzes.

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

    Datentyp: Zeichenfolge
    Ergebnis.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

    Versionierte URL: /api/now/{api_Version}/Import/{stagingTableName}

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

    Hinweis:
    Verfügbare Versionen werden in angegeben REST API-Explorer . Für geskriptete REST-APIs gibt es zusätzliche Versionsinformationen auf der Formular „geskripteter REST-Service“ .

    Unterstützte Anforderungsparameter

    Hinweis:
    Die POST-Methode „Importsatz“ akzeptiert nur Name-Wert-Paare von Zeichenfolgendatentypen in Anforderungstext-Parametern. Wenn ein anderer Datentyp angegeben wird, entspricht der resultierende Wert, der in der Importsatztabelle gespeichert ist, möglicherweise nicht dem beabsichtigten Format. Beispielsweise wird die Bezeichnung „:“ des geschachtelten JSON-Objekts in „=“ geändert.
    Tabelle : 7. Pfad-Parameter
    Name Beschreibung
    api_version Optional. Version des Endpunkts, auf den zugegriffen werden soll. Beispiel: v1 Oder v2 . Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden.

    Datentyp: Zeichenfolge
    Staging TableName 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
    Rufen Sie spezifisch an Name-Wert-Paare, die in die Importfelder eingefügt werden sollen.

    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
    Inhaltstyp 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 REST API-HTTP-Antwortcodes .

    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.

    Antworttext-Parameter (JSON oder XML)

    Name Beschreibung
    import_set Name des Importsatzes

    Datentyp: Zeichenfolge
    Ergebnis Liste der Objekte, 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"
  }
]
    Ergebnis.Anzeigename Anzeigename des Importsatzes.

    Datentyp: Zeichenfolge
    Ergebnis.Anzeigewert Wert des Importsatzes.

    Datentyp: Zeichenfolge
    Ergebnis.Datensatz_Link Tabellen-API RUFT die Anforderung für den importierten Datensatz AB.

    Datentyp: Zeichenfolge
    Ergebnis.Status Status des Imports.

    Datentyp: Zeichenfolge
    Ergebnis.sys_ID SYS_ID des Importdatensatzes.

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

    Datentyp: Zeichenfolge
    Ergebnis.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.

    Transformation ist standardmäßig asynchron. Um die synchrone Transformation festzulegen, erstellen Sie einen neuen Datensatz in der Tabelle „Rest – Multiple einfügen“ [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.
    Datenquellendateiformat
    Wenn Sie eine Bereitstellungstabelle aus einer JSON-Datenquelle generieren, stimmen Sie dem JSON-Format der Quelldatei zu.
    Spaltenformat der Bereitstellungstabelle
    Standard. Stimmt mit dem Textformat der Staging-Tabellenspalte in Schlüssel-Wert-Paaren überein.

    URL-Format

    Versionierte URL: /api/now/{api_Version}/Import/{stagingTableName}/insertMultiple

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

    Hinweis:
    Verfügbare Versionen werden in angegeben REST API-Explorer . Für geskriptete REST-APIs gibt es zusätzliche Versionsinformationen auf der Formular „geskripteter REST-Service“ .

    Unterstützte Anforderungsparameter

    Hinweis:
    Die POST-Methode „Importsatz“ akzeptiert nur Name-Wert-Paare von Zeichenfolgendatentypen in Anforderungstext-Parametern. Wenn ein anderer Datentyp angegeben wird, entspricht der resultierende Wert, der in der Importsatztabelle gespeichert ist, möglicherweise nicht dem beabsichtigten Format. Beispielsweise wird die Bezeichnung „:“ des geschachtelten JSON-Objekts in „=“ geändert.
    Tabelle : 13. Pfad-Parameter
    Name Beschreibung
    api_version Optional. Version des Endpunkts, auf den zugegriffen werden soll. Beispiel: v1 Oder v2 . Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden.

    Datentyp: Zeichenfolge
    Staging TableName Name der Importsatztabelle, aus der die Daten importiert werden sollen. Siehe Importsätze – Schlüsselkonzepte .

    Datentyp: Zeichenfolge
    Tabelle : 14. Abfrageparameter
    Name Beschreibung
    multi_import_set_id SYS_ID eines Eintrags in der Tabelle „Mehrfachimportsätze“ [sys_Multi_Import_Set]. Wenn angegeben, wird der aktuelle Import zu diesem mehrfachen Importsatz hinzugefügt, anstatt ihn zu einem neuen mehrfachen 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 von Importen 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 Textformat der Anforderung stimmt mit dem JSON-Dateiformat überein, das zum Erstellen der Datenquelle verwendet wird. Geben Sie den Anforderungstext im gleichen Format wie die JSON in der Datenquelle an. Die JSON-Eingabe hängt von den Eigenschaften in Ihrer Datenquelle ab. Weitere Informationen finden Sie in JSON-Informationen Dateityp-Datenquelle .
    • Diese Option ist nur verfügbar, wenn die Bereitstellungstabelle mit einer JSON-Datenquelle erstellt wurde. Siehe Erstellen Sie eine Dateityp-Datenquelle .
    • Sie müssen den Pfad der Datenquelle in der Tabelle „Datenquelle“ [sys_Data_Source] in definieren Pfad für jede Zeile Feld.
    • Um das Standardverhalten für den REST-Anwender „mehrere einfügen“ zu ändern, erstellen Sie einen Eintrag in der Tabelle „REST Multiple einfügen“ [sys_Rest_insert_multiple].
    • Aktivieren Sie Verwenden Sie das Datenquellenformat Fügen Sie im REST mehrere Einträge ein.

    Datentyp: Objekt
    Staging-Tabellenspalte (Standard) Dieses Textformat der Anforderung entspricht den Spalten der Bereitstellungstabelle. Verwenden Sie recordsArray von Schlüssel-Wert-Paaren, die der Spalte der Bereitstellungstabelle entsprechen, die in die Importfelder eingefügt werden soll. Jeder JSON-Schlüssel ordnet die Tabellenspalte einem JSON-Wert zu, der den einzufügenden Wert darstellt. Die JSON-Eingabe hängt davon ab, welche Felder sich in Ihrer Bereitstellungstabelle befinden.

    Der Standardschlüsselwert für die Spaltenzuordnung ist die Spaltentabelle.

    {
   "records":[
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      },
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      }
   ]
}
    Sie können Zuordnungseinstellungen ändern, indem Sie in der Tabelle „Rest Multiple einfügen“ [sys_Rest_insert_multiple] einen Eintrag hinzufügen und ändern Spaltenzuordnung Von Bezeichnung Bis Spaltenname .
    {
   "records":[
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      },
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      }
   ]
}

    Die Data dictionary tables Stellt Details zu Tabellenfeldern im System bereit.

    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 REST API-HTTP-Antwortcodes .

    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. Für asynchrone Anforderungen können Sie diesen Wert verwenden, um einen weiteren Importsatz auszuführen, nachdem dieser Importsatz-Prozess abgeschlossen ist.

    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: Mehrere 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 mit dem Spaltenformat 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 umfassen 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>"
}