Importsatz-API

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 8 Minuten Lesedauer

    • Die Import Set -API stellt Endpunkte bereit, mit denen Sie mit Import Set-Tabellen interagieren können.

    Die API transformiert eingehende Daten basierend auf zugehörigen Transform Maps. 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.

    Import Set – 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}

    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-Antwortcodesder 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 Import Set-Tabellen 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.

    Antworttextparameter (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"
  }
]
    result.display_name Anzeigename des Importsatzes.

    Datentyp: Zeichenfolge
    result.display_value Wert des Importsatzes.

    Datentyp: Zeichenfolge
    result.record_link GET-Anforderung der Tabellen-API 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"
    }
  ]
}

    Import Set – POST /now/import/{stagingTableName}

    Fügt eingehende Daten in eine angegebene Staging-Tabelle ein und löst die Transformation basierend auf vordefinierten Transformationszuordnungen in der Import Set-Tabelle 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}

    Unterstützte Anforderungsparameter

    Hinweis:
    Die Import Set-POST-Methode akzeptiert nur Name-Wert-Paare von Zeichenfolgen-Datentypen in Anforderungstextparametern. Wenn ein anderer Datentyp angegeben wird, entspricht der resultierende Wert, der in der Import Set-Tabelle gespeichert wird, möglicherweise nicht dem beabsichtigten Format. Zum Beispiel 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 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
    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-Antwortcodesder 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.

    Antworttextparameter (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"
  }
]
    result.display_name Anzeigename des Importsatzes.

    Datentyp: Zeichenfolge
    result.display_value Wert des Importsatzes.

    Datentyp: Zeichenfolge
    result.record_link GET-Anforderung der Tabellen-API 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"
    }
  ]
}

    Import Set – POST /now/import/{stagingTableName}/insertMultiple

    Fügt mehrere Datensätze in eine angegebene Staging-Tabelle 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 – Mehrere 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.
    Dateiformat der Datenquelle
    Wenn Sie eine Staging-Tabelle aus einer JSON-Datenquelle generieren, passen Sie das JSON-Format der Quelldatei an.
    Spaltenformat der Bereitstellungstabelle
    Standard. Entspricht dem Anforderungstextformat der Staging-Tabellenspalte in Schlüssel-Wert-Paaren.

    URL-Format

    Versionierte URL: /api/now/{api_version}/import/{stagingTableName}/insertMultiple

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

    Unterstützte Anforderungsparameter

    Hinweis:
    Die Import Set-POST-Methode akzeptiert nur Name-Wert-Paare von Zeichenfolgen-Datentypen in Anforderungstextparametern. Wenn ein anderer Datentyp angegeben wird, entspricht der resultierende Wert, der in der Import Set-Tabelle gespeichert wird, möglicherweise nicht dem beabsichtigten Format. Zum Beispiel 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 Import Set-Tabelle, aus der die Daten importiert werden sollen. Weitere Informationen finden Sie unter Schlüsselkonzepte für Import Sets.

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

    Datentyp: Zeichenfolge
    run_after Sys_id eines Eintrags in der Tabelle „Import Sets“ [sys_import_set]. Ermöglicht 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 : 15. Anforderungstext (JSON)
    Format Beschreibung
    Datenquellendatei Dieses Anforderungstextformat entspricht dem JSON-Dateiformat, das zum Erstellen der Datenquelle verwendet wird. Geben Sie den Anforderungstext im selben Format wie das JSON in der Datenquelle an. Die JSON-Eingabe hängt von den Eigenschaften in Ihrer Datenquelle ab. Weitere Informationen finden Sie unter JSON-Informationen in Dateityp-Datenquelle.
    • Diese Option ist nur verfügbar, wenn die Bereitstellungstabelle mit einer JSON-Datenquelle erstellt wurde. Weitere Informationen finden Sie unter Datenquellen vom Typ Datei erstellen.
    • Sie müssen den Pfad der Datenquelle in der Datenquellentabelle [sys_data_source] im Feld Pfad für jede Zeile definieren.
    • Um das Standardverhalten für den REST-Benutzer „Mehrere einfügen“ zu ändern, erstellen Sie einen Eintrag in der Tabelle „REST-Mehrere einfügen“ [sys_rest_insert_multiple].
    • Aktivieren Sie den Eintrag Datenquellenformat verwenden im REST-Eintrag Insert Multiple (Mehrere einfügen).

    Datentyp: Objekt
    Staging-Tabellenspalte (Standard) Dieses Anforderungstextformat stimmt mit Staging-Tabellenspalten überein. Verwenden Sie das Array records von Schlüssel-Wert-Paaren, die der Staging-Tabellenspalte entsprechen, zum Einfügen in die Importfelder. 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 Staging-Tabelle befinden.

    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 einen Eintrag in der Tabelle „REST – Mehrere einfügen“ [ sys_rest_insert_multiple ] hinzufügen und die Spaltenzuordnung von Bezeichnungin Spaltenname ändern.
    {
   "records":[
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      },
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      }
   ]
}

    Das Datenwörterbuch 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-Antwortcodesder 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 Datensatzes, der der Tabelle „Import Sets“ [sys_import_set] hinzugefügt wurde. Für asynchrone Anforderungen können Sie diesen Wert verwenden, um einen weiteren Importsatz auszuführen, nachdem dieser Importsatzprozess abgeschlossen ist.

    Datentyp: Zeichenfolge
    multi_import_set_id Sys_id des Datensatzes, der der Tabelle „Multi-Import Sets“ [sys_multi_import_set] hinzugefügt wurde. Dieser Wert kann verwendet werden, um mehrere Importsätze in einem Satz zu gruppieren.

    Datentyp: Zeichenfolge

    Beispiel für eine cURL-Anforderung

    Das folgende Beispiel zeigt, wie eine Transformation für eine Importtabelle namens u_employee_import_set_table unter Verwendung des Staging-Tabellenspaltenformats 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 „Import Sets“ [sys_import_set] und „Multi-Import Sets“ [sys_multi_import_set].

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