Der folgende Abschnitt enthält Informationen zur Web-API von Xtract Universal.

Xtract Universal bietet eine Web-API, die das Ausführen von Extraktionen und das Abfragen von Metainformationen und Extraktionsprotokollen von Xtract Universal über Webaufrufe ermöglicht. Die Web-API gibt das Ergebnis als http-json-Stream zurück.

Basis-URL-Format #

Die Basis-URL für Webaufrufe verwendet das folgende Format: [protocol]://[host or IP address]:[port]/.

Beispiele

Protokoll Syntax Beispiel
HTTP http://[host].[domain]:[port] http://sherri.theobald.local:8065
HTTP http://[host]:[port] http://localhost:8065
HTTPS https://[host].[domain]:[port] https://sherri.theobald.local:8165
Erfordert einen dedizierten Hostnamen und ein X.509-Zertifikat, siehe Web Server Einstellungen.

Hinweis: Stellen Sie sicher, dass Sie die richtigen Ports verwenden, siehe Server Ports.

Version abrufen # 

[protocol]://[host]:[port]/version

Gibt die Softwareversion der Xtract Universal-Serverinstallation im JSON-Format zurück.

Beispiel

http://sherri.theobald.local:8065/version

Click here to show the response body 
{
    "version": "6.2.13.4"
}

Destinationsdetails abrufen # 

[protocol]://[host]:[port]/destinations

Gibt eine Liste aller definierten Definitionen zurück. Das Ergebnis enthält die folgenden Elemente:

Element Beschreibung
name Name der Zielverbindung
type Verbindungstyp
host Hostname, wenn vorhanden
port Portname, wenn vorhanden
database Datenbankname, wenn vorhanden
user Nutzername in der Verbindung, wenn vorhanden
schema Schemaname, wenn vorhanden
directory Verzeichnisname, wenn vorhanden

Tipp: Für eine Liste von Extraktionen mit einer bestimmten Destination, siehe Extraktionsdetails abrufen.

Beispiel

http://sherri.theobald.local:8065/destinations

Click here to show the response body 
Name,Type,Host,Port,Database,User,Schema,Directory
csv,FileCSV,,,,,,"C:\Users\alice\Documents\csv\"
http-csv,CSV,,,,,,
http-json,HTTPJSON,,,,,,
json,FileJSON,,,,,,"C:\Users\alice\Documents\json"
sql-server,SQLServer,dbtest-ws2019.theobald.local,1433,alice,THEOBALD\alice,,
tableau2022,Tableau,,,,,,"C:\Users\alice\Documents\csv"

Extraktionsdetails abrufen # 

[protocol]://[host]:[port]/config/extractions

Gibt eine Liste aller definierten Extraktionen im JSON-Format zurück. Das Ergebnis enthält die folgenden Elemente:

Element Beschreibung
name Name der Extraktion
type Extraktionstyp
sapObject Name des extrahierten SAP-Objekts
source Name der Quellverbindung
destination Name der Zielverbindung
latestRun Enthält rowCount, duration, state und startedAt des letzten Extraktionslaufs
rowCount Anzahl der zuletzt extrahierten Datensätze
duration Dauer der letzten Ausführung
state Status der Extraktion (Running, FinishedNoErrors, FinishedErrors)
startedAt Zeitstempel der letzten Ausführung
created Enthält Angaben zur Maschine, zum Zeitstempel und zum Benutzer zum Zeitpunkt der Extraktionserstellung
machine Maschine, auf der die Extraktion erstellt wurde
timestamp timestamp of the creation
user Benutzer, der die Extraktion erstellt hat
lastChange Enthält Angaben zur Maschine, zum Zeitstempel und zum Benutzer zum Zeitpunkt der letzten Änderung der Extraktion
machine Maschine, auf der die Extraktion zuletzt geändert wurde
timestamp Zeitstempel der letzten Änderung
user Benutzer, der die Extraktion zuletzt geändert hat

Parameter und Optionen

[protocol]://[host]:[port]/config/extractions

Parameter Beschreibung
?destinationType=[destination] Gibt eine Liste von Extraktionen zurück, die in eine bestimmte Destination schreiben.
/[extraction_name]/parameters Gibt eine Liste der Laufzeitparameter zurück, die in der angegebenen Extraktion verwendet werden. Jede Extraktion verfügt über eine Reihe von Laufzeitparametern Extraction, Source und Custom Extraktionsparameter. Die Parameter stehen im Fenster „Run Extraction“ des Xtract Universal Designers zur Verfügung.
/[extraction_name]/result-columns Returns the result columns of an extraction.

Das Ergebnis von [protocol]://[host]:[port]/config/extractions/[extraction_name]/result-columns enthält die folgenden Elemente:

Element Typ Beschreibung
name String Spalte name
description String Spalte description
type String Spalte datatype
length Integer Spalte length
isPrimaryKey boolean Spalte ist der Primärschlüssel der Extraktion
isEncrypted boolean Verschlüsselung für Spalte ist aktiv
decimalsCount Integer Anzahl der Dezimalstellen
referenceField String Referenzfeld für Währung/Menge
referenceTable String Referenztabelle für Währung/Menge

Hinweis: Datenfelder, die Datumsangaben enthalten, haben den Datentyp ConvertedDate, wenn die Option Date Conversion (Datumsumrechnung) in den Destination Settings (Destinationseinstellungen) aktiv ist. Wenn inaktiv, ist der Datentyp StringLengthMax mit einer Länge von 8 (Datum).

Beispiele

http://sherri.theobald.local:8065/config/extractions/

Click here to show the response body 
{
    "extractions": 
    [
        {
            "name": [
                "0MAT"
            ],
            "type": "DeltaQ",
            "technicalName": "0MATERIAL_ATTR",
            "source": "saperp",
            "destination": "GoogleCloudStorage",
            "latestRun": {
                "rowCount": 20275,
                "duration": "PT00H00M13.383S",
                "state": "FinishedNoErrors",
                "startedAt": "2023-08-17_11:24:07.770"
            },
            "created": {
                "machine": "TODD",
                "timestamp": "20221005T080618.544Z",
                "user": "THEOBALD\\steffan"
            },
            "lastChange": {
                "machine": "SHERRI",
                "timestamp": "20240129T131530.701Z",
                "user": "THEOBALD\\alice"
            }
        },
        {
            "name": [
                "0MATERIAL"
            ],
            "type": "DeltaQ",
            "technicalName": "0COSTCENTER_0101_HIER",
            "source": "saperp",
            "destination": "csv",
            "latestRun": {
                "rowCount": 200,
                "duration": "PT00H00M00.114S",
                "state": "FinishedNoErrors",
                "startedAt": "2023-08-17_11:31:44.029"
            },
            "created": {
                "machine": "SHERRI",
                "timestamp": "20230815T114651.045Z",
                "user": "THEOBALD\\alice"
            },
            "lastChange": {
                "machine": "SHERRI",
                "timestamp": "20230817T113328.786Z",
                "user": "THEOBALD\\alice"
            }
        }

http://sherri.theobald.local:8065/config/extractions/?destinationType=sqlserver

Click here to show the response body 
{
    "extractions": 
    [
        {
            "name": [
                "bw2--UCONRFC_ATTR_F"
            ],
            "type": "ODP",
            "technicalName": "UCONRFC_ATTR$F",
            "source": "bw2",
            "destination": "sql-server",
            "created": {
                "machine": "SHERRI",
                "timestamp": "20230622T062454.495Z",
                "user": "alice"
            },
            "lastChange": {
                "machine": "SHERRI",
                "timestamp": "20230703T070609.890Z",
                "user": "THEOBALD\\alice"
            }
        },
        {
            "name": [
                "ec5--KNA1_DELTA"
            ],
            "type": "TableCDC",
            "technicalName": "KNA1_DELTA",
            "source": "ec5",
            "destination": "sql-server",
            "created": {
                "machine": "SHERRI",
                "timestamp": "20230622T051526.003Z",
                "user": "alice"
            },
            "lastChange": {
                "machine": "SHERRI",
                "timestamp": "20230703T070609.955Z",
                "user": "THEOBALD\\alice"
            }
        },
        {
            "name": [
                "HIERARCHY"
            ],
            "type": "Hierarchy",
            "technicalName": "TEST_DEP_01",
            "source": "bw2",
            "destination": "sql-server",
            "latestRun": {
                "rowCount": 13,
                "duration": "PT00H00M02.710S",
                "state": "FinishedNoErrors",
                "startedAt": "2023-07-19_06:04:04.139"
            },
            "created": {
                "machine": "SHERRI",
                "timestamp": "20230719T051513.542Z",
                "user": "THEOBALD\\alice"
            },
            "lastChange": {
                "machine": "SHERRI",
                "timestamp": "20230815T074627.575Z",
                "user": "THEOBALD\\alice"
            }
        }
    ]
}

http://sherri.theobald.local:8065/config/extractions/KNA1/parameters

Click here to show the response body 
{
    "extraction": 
    [
        {
            "name": "ignoreCache",
            "description": "Ignore the result cache",
            "type": "Flag",
            "default": "False"
        },
        {
            "name": "preview",
            "description": "Enable/disable preview mode",
            "type": "Flag",
            "default": "False"
        },
        {
            "name": "source",
            "description": "Sets the name of the source",
            "type": "Text",
            "default": "ec5"
        },
        {
            "name": "destination",
            "description": "Sets the name of the destination",
            "type": "Text",
            "default": "csv"
        },
        {
            "name": "rows",
            "description": "Maximum number of rows",
            "type": "Number",
            "default": "0"
        },
        {
            "name": "whereClause",
            "description": "Where Clause",
            "type": "Text",
            "default": null
        },
        {
            "name": "packageSize",
            "description": "Package Size",
            "type": "Number",
            "default": "50000"
        }
    ],
    "source": 
    [
        {
            "name": "lang",
            "description": "Logon Language",
            "type": "Text",
            "default": "EN"
        }
    ]
}

http://sherri.theobald.local:8065/config/extractions/KNA1/result-columns

Click here to show the response body 
{
    "columns": 
    [
        {
            "name": "KUNNR",
            "description": "Customer Number",
            "type": "StringLengthMax",
            "length": 10,
            "isPrimaryKey": true,
            "isEncrypted": false,
            "referenceField": "",
            "referenceTable": ""
        },
        {
            "name": "LAND1",
            "description": "Country Key",
            "type": "StringLengthMax",
            "length": 3,
            "isPrimaryKey": false,
            "isEncrypted": false,
            "referenceField": "",
            "referenceTable": ""
        },
        {
            "name": "NAME1",
            "description": "Name 1",
            "type": "StringLengthMax",
            "length": 35,
            "isPrimaryKey": false,
            "isEncrypted": false,
            "referenceField": "",
            "referenceTable": ""
        },
        {
            "name": "ORT01",
            "description": "City",
            "type": "StringLengthMax",
            "length": 35,
            "isPrimaryKey": false,
            "isEncrypted": false,
            "referenceField": "",
            "referenceTable": ""
        },
        {
            "name": "Mean_UMSAT",
            "description": "Annual sales",
            "type": "Double",
            "isPrimaryKey": false,
            "isEncrypted": false,
            "referenceField": "UWAER",
            "referenceTable": "KNA1"
        }
    ]
}

Extraktionen ausführen # 

[protocol]://[host]:[port]/run/[extraction_name]

Führt die angegebene Extraktion aus und wartet darauf, dass der Prozess angeschlossen ist.

[protocol]://[host]:[port]/start/[extraction_name]

Führt die angegebene Extraktion asynchron aus und gibt den Ausführungsstatus sofort zurück.

Warnung! Veraltete Endpunkte:
[protocol]://[host]:[port]/?name=[extraction_name] (synchron)
[protocol]://[host]:[port]/?name=[extraction_name]&wait=false (asynchron)

Tipp: Sie können die Benutzeroberfläche im Menü “Run Extraction” verwenden, um eine URL für das Ausführen einer Extraktion zu generieren, siehe Extraktion ausführen.

Antwort

Die Antwort eines Webservice-Aufrufs enthält die folgenden Informationen:

  Antwort Beschreibung
(1) HTTP Statuscode Der HTTP-Statuscode 200 zeigt einen erfolgreichen Extraktionsaufruf an. Dies weist nicht auf eine erfolgreiche Ausführung der Extraktion hin.
Der HTTP-Statuscode 404 zeigt an, dass die aufgerufene Extraktion nicht existiert. Detaillierte Informationen finden Sie im Protokoll des Webservices.
(2) HTTP-Header Zeigt den Zeitstempel der Extraktion im HTTP-Header an, z. B., X-XU-Timestamp: 2021-04-09_19:03:09.971
(3) HTTP Response-Body Die Antwort im HTTP-Body hängt vom Typ der Destination der Extraktion ab. Abhängig vom Destinationstyp werden die extrahierten Daten entweder im CSV-oder JSON-Format zurückgegeben.

Webservice Call pull

Parameter

[protocol]://[host]:[port]/start/[extraction_name]

Parameter Beschreibung
&[parameter1_name]=[value] Führt die angegebene Extraktion aus und übergibt Werte an die angegebenen Extraktionsparameter.
&quiet-push=true Führt die angegebene Extraktion aus und unterdrückt die Ausgabe von Extraktionsprotokollen für Push-Destinationen. Dieser Parameter hat keine Auswirkung auf Pull-Destinationen und asynchrone Extraktionen.

Beispiel

http://sherri.theobald.local:8065/start/KNA1/?name1=heobald%20Software&city=Stuttgart

Click here to show the response body 
KUNNR,LAND1,NAME1,ORT01
0000000779,DE,Theobald Software,Stuttgart

Extraktion abbrechen # 

[protocol]://[host]:[port]/abort?name=[extraction_name]

Bricht die angegebene Extraktion ab. Bei erfolgreichem Abbruch wird im HTTP-Body eine Bestätigungsmeldung zurückgegeben.

* Dieser Endpunkt ist als veraltet markiert und wird durch /stop/[extraction_name] ersetzt. *

Beispiel

http://sherri.theobald.local:8065//abort?name=KNA1

Click here to show the response body 
All runs of extraction 'KNA1' aborted.

Status einer Extraktion abrufen # 

[protocol]://[host]:[port]/status/?name=[extraction_name]&timestamp=[yyyy-MM-dd_HH:mm:ss.SSS]

Gibt den Status einer (laufenden) Extraktion zum angegebenen Zeitstempel zurück. Der Zeitstempel entspricht dem von zurückgegebenen startedAt-Element [protocol]://[host]:[port]/config/extractions/ oder [protocol]://[host]:[port]/logs/extractions/[extraction-name].

Status Beschreibung
Running Die Extraktion läuft.
FinishedNoErrors Die Extraktion wurde ohne Fehler abgeschlossen.
FinishedErrors Die Extraktion wurde abgeschlossen, weist jedoch mindestens einen Fehler auf.

Beispiel

http://sherri.theobald.local:8065/status/?name=KNA1&timestamp=2024-02-05_10:23:08.025

Click here to show the response body 
FinishedNoErrors

Extraktionslogs abrufen # 

[protocol]://[host]:[port]/logs/extractions

Gibt eine Liste von Extraktionsläufen zurück. Das Ergebnis enthält die folgenden Elemente:

Element Beschreibung
extractionName Name der Extraktion
runs enthält rowCount, duration, state, webServerLog und startedAt der Extraktionsläufe
row count Anzahl der extrahierten Datensätze
duration Dauer der Ausführung
state Status der Extraktion (Running, FinishedNoErrors, FinishedErrors)
webServerLog Zeitstempel des entsprechenden Serverlogs
startedAt Zeitstempel der Ausführung

Parameter & Optionen

[protocol]://[host]:[port]/logs/extractions

Parameter Beschreibung
?min=[yyyy-MM-dd_HH:mm:ss.SSS] Gibt die Extraktionsläufe nach dem angegebenen Datum und der angegebenen Uhrzeit zurück.
?max=[yyyy-MM-dd_HH:mm:ss.SSS] Gibt die Extraktionsläufe vor dem angegebenen Datum und der angegebenen Uhrzeit zurück.
/[extraction-name] Gibt alle Extraktionsläufe der angegebenen Extraktion zurück.
/[extraction-name]/[yyyy-MM-dd_HH:mm:ss.SSS] Gibt den Extraktionslauf der angegebenen Extraktion mit dem angegebenen Zeitstempel zurück.
/[extraction-name]/[yyyy-MM-dd_HH:mm:ss.SSS]/log Gibt das Extraktionslog der angegebenen Extraktion mit dem angegebenen Zeitstempel zurück.

Beispiel

http://sherri.theobald.local:8065/logs/extractions?min=2023-08-17_11:20:44.029

Click here to show the response body 
{
    "extractions": 
    [
        {
            "extractionName": [
                "0MATERIAL"
            ],
            "runs": [
                {
                    "rowCount": 200,
                    "duration": "PT00H00M00.2651",
                    "state": "FinishedNoErrors",
                    "startedAt": "2023-08-17_11:31:44.029"
                }
            ]
        }
        {
            "extractionName": [
                "KNA1"
            ],
            "runs": [
                {
                    "rowCount": 0,
                    "duration": "PT00H00M01.3741",
                    "state": "FinishedErrors",
                    "webServerLog": "2024-02-05_08:13:48.132",
                    "startedAt": "2024-02-05_08:14:13.771"
                },
                {
                    "rowCount": 9995,
                    "duration": "PT00H00M00.477S",
                    "state": "FinishedNoErrors",
                    "webServerLog": "2024-02-05_10:20:51.851",
                    "startedAt": "2024-02-05_10:20:52.344"
                }
            ]
        }
    ]
}

http://sherri.theobald.local:8065/logs/extractions/KNA1

Click here to show the response body 
{
    "runs": [
        {
            "rowCount": 0,
            "duration": "PT00H00M01.3741",
            "state": "FinishedErrors",
            "webServerLog": "2024-02-05_08:13:48.132",
            "startedAt": "2024-02-05_08:14:13.771"
        },
        {
            "rowCount": 9995,
            "duration": "PT00H00M00.477S",
            "state": "FinishedNoErrors",
            "webServerLog": "2024-02-05_10:20:51.851",
            "startedAt": "2024-02-05_10:20:52.344"
        }
    ]
}

http://sherri.theobald.local:8065/logs/extractions/KNA1/2024-02-05_10:20:52.344

Click here to show the response body 
{
    "rowCount": 9995,
    "duration": "PT00H00M00.477S",
    "state": "FinishedNoErrors",
    "webServerLog": "2024-02-05_10:20:51.851",
    "startedAt": "2024-02-05_10:20:52.344"
}

http://sherri.theobald.local:8065/logs/extractions/KNA1/2024-02-05_10:20:52.344/log

Click here to show the response body 
{
    "rowCount": 9995,
    "duration": "PT00H00M00.477S",
    "state": "FinishedNoErrors",
    "webServerLog": "2024-02-05_10:20:51.851",
    "startedAt": "2024-02-05_10:20:52.344",
    "logEntries": [
        {
            "timestamp": "2024-02-05_10:20:52.377",
            "logLevel": "Info",
            "source": "Table",
            "message": "server version: 999.999.999.691"
        },
        {
            "timestamp": "2024-02-05_10:20:52.470",
            "logLevel": "Debug",
            "source": "Table",
            "message": "Attempting to load Theobald.Extractors.Table.TableExtractionDefinition information for extraction KNA1"
        },
		
		...
		
        {
            "timestamp": "2024-02-05_10:20:53.774",
            "logLevel": "Info",
            "source": "Table",
            "message": "Extraction finished with status FinishedNoErrors."
        },
        {
            "timestamp": "2024-02-05_10:20:53.774",
            "logLevel": "Debug",
            "source": "Table",
            "message": "Writing run information."
        },
        {
            "timestamp": "2024-02-05_10:20:53.779",
            "logLevel": "Info",
            "source": "Table",
            "message": "Extraction run information was updated."
        }
    ]
}

Hinweis: Informationen zur Interpretation von Protokollen, siehe Logging.

Serverlogs abrufen # 

[protocol]://[host]:[port]/logs/web

Gibt eine Liste von Zeitstempeln zurück, die den Serverlogs entsprechen.

Parameter & Optionen

[protocol]://[host]:[port]/logs/web

Parameter Beschreibung
?min=[yyyy-MM-dd_HH:mm:ss.SSS] Gibt die Zeitstempel der Serverlogs nach dem angegebenen Datum und der angegebenen Uhrzeit zurück.
?max=[yyyy-MM-dd_HH:mm:ss.SSS] Gibt die Zeitstempel der Serverlogs vor dem angegebenen Datum und der angegebenen Uhrzeit zurück.
/[yyyy-MM-dd_HH:mm:ss.SSS] Gibt die Serverlogeinträge mit dem angegebenen Zeitstempel zurück.

Beispiel

http://sherri.theobald.local:8065/logs/web?min=2024-02-05_12:39:29.022

Click here to show the response body 
{
    "logs": 
    [
        "2024-02-05_12:44:44.741",
        "2024-02-05_13:09:11.899",
        "2024-02-07_08:52:17.487",
        "2024-02-07_08:58:14.920",
        "2024-02-07_10:44:21.652",
        "2024-02-07_10:50:58.202",
        "2024-02-07_10:54:25.552"
    ]
}

http://sherri.theobald.local:8065/logs/web/2024-02-05_12:44:44.741

Click here to show the response body 
{
    "logEntries": 
    [
        {
            "timestamp": "2024-02-05_12:44:44.815",
            "logLevel": "Info",
            "source": "WebServerHandler",
            "message": "Client [fe80::d3ac:77ba:ce0f:83b1%8]:55904"
        },
        {
            "timestamp": "2024-02-05_12:44:45.012",
            "logLevel": "Debug",
            "source": "HttpServer",
            "message": "Reading..."
        },
        {
            "timestamp": "2024-02-05_12:44:45.060",
            "logLevel": "Info",
            "source": "HttpServer",
            "message": "Processing /."
        },
        {
            "timestamp": "2024-02-05_12:44:45.251",
            "logLevel": "Info",
            "source": "WebServer",
            "message": "Attempting to load server permissions."
        },
		
		...
        
        {
            "timestamp": "2024-02-05_12:44:45.808",
            "logLevel": "Debug",
            "source": "HttpServer",
            "message": "Reading..."
        }
    ]
}

Hinweis: Informationen zur Interpretation von Logs, siehe Logging.