api.v2.export
Schnittstellenbeschreibung
Copyright ©
Mindbreeze GmbH, A-4020 Linz, 23.12.2020.
Alle Rechte vorbehalten. Alle verwendeten Hard- und Softwarenamen sind Handelsnamen und/oder Marken der jeweiligen Hersteller.
Diese Unterlagen sind streng vertraulich. Durch die Übermittlung und Präsentation dieser Unterlagen alleine werden keine Rechte an unserer Software, an unseren Dienstleistungen und Dienstleistungsresultaten oder sonstigen geschützten Rechten begründet.
Die Weitergabe, Veröffentlichung oder Vervielfältigung ist nicht gestattet.
Aus Gründen der einfacheren Lesbarkeit wird auf die geschlechtsspezifische Differenzierung, z.B. Benutzer/-innen, verzichtet. Entsprechende Begriffe gelten im Sinne der Gleichbehandlung grundsätzlich für beide Geschlechter.
Überblick
Mindbreeze InSpire stellt den Export von Suchergebnissen mit einer einfachen Schnittstelle zur Verfügung. Diese Schnittstelle basiert auf HTTP und JSON. Es gibt die Möglichkeit den Export synchron oder asynchron durchzuführen.
Synchroner Export
Der Export kann direkt heruntergeladen werden. Der Synchrone Export wird nur für die Exportformate Excel und CSV bereitgestellt.
Der Synchrone Export wird mit der URL <Client Service URL>/api/v2/export bereitgestellt.
Durch ein HTTP/POST an die Export URL mit dem Inhalt:
{
"search_request": {
"sort_date_facets_by_value": true,
"content_sample_length": 300,
"count": 10,
"alternatives_query_spelling_max_estimated_count": 50,
"properties": [{
"formats": ["HTML", "VALUE"],
"name": "title"
}, {
"formats": ["HTML", "VALUE"],
"name": "mes:date"
}, {
"formats": ["HTML", "VALUE"],
"name": "mes:size"
}, {
"formats": ["HTML", "VALUE"],
"name": "action_0"
}
],
"user": {
"query": {
"and": [{
"unparsed": "ALL",
"id": "query"
}
]
},
"constraints": []
},
"source_context": {
"constraints": [{
"unparsed": "ALL",
"id": "view_base"
}
]
},
"generate_available_properties_and_facets": true
},
"id": "ALL_10:11",
"name": "my testexport",
"groupby_properties": [],
"batch_size": 1000,
"allow_duplicate": false,
"currentTime": "10:11",
"add_description_of_search_request": true,
"export_format":"application/x-ms-excel"
}
Die Eigenschaft export_format spezifiziert das gewünschte Format des Exports.
Folgene Formate werden unterstützt
application/x-ms-excel Microsoft Excel XSLX Format
text/csv CSV Format
Asynchroner Export
Der Export erfolgt über 2 Schritte. Zuerst muss eine Exportanfrage mittels Persisted Resources gespeichert werden. Damit erhält man einen Pfad (= ID) für den Export, der dann durch das Aufrufen der Export Schnittstelle durchgeführt und abgeholt werden kann.
Speichern der Exportanfrage
Der Export Request wird als HTTP POST an ein Client Service gesendet. Der Pfad für das Speichern der Exportanfrage lautet: <Client Service URL>/api/v2/persistedresources
Der Request hat folgende Form:
{
"create": {
"path": ["queryexports", "default"],
"data": "<exportrequest>"
}
}
Der <exportrequest> wird als String in die Eigenschaft data gespeichert und hat die Form:
{
"search_request": {
"sort_date_facets_by_value": true,
"content_sample_length": 300,
"count": 10,
"alternatives_query_spelling_max_estimated_count": 50,
"properties": [{
"formats": ["HTML", "VALUE"],
"name": "title"
}, {
"formats": ["HTML", "VALUE"],
"name": "mes:date"
}, {
"formats": ["HTML", "VALUE"],
"name": "mes:size"
}, {
"formats": ["HTML", "VALUE"],
"name": "action_0"
}
],
"user": {
"query": {
"and": [{
"unparsed": "ALL",
"id": "query"
}
]
},
"constraints": []
},
"source_context": {
"constraints": [{
"unparsed": "ALL",
"id": "view_base"
}
]
},
"generate_available_properties_and_facets": true
},
"export_format": "undefined",
"id": "ALL_10:11",
"name": "my testexport",
"groupby_properties": [],
"batch_size": 1000,
"allow_duplicate": false,
"currentTime": "10:11",
"add_description_of_search_request": true
}
Als Antwort wird der Status der Anfrage geliefert und der Pfad zum durchführen des Exports.
{
"persisted_resources": [{
"path": ["queryexports", "default", "4"],
"data": "<exportrequest>"
}
],
"persisted_resource_request": {
"create": {
"path": ["queryexports", "default"],
"data": "<exportrequest>"
},
"user_context": {}
},
"status": {
"success": true
}
}
In diesem Beispiel liefert die Antwort den Pfad queryexports/default/4.
Gespeicherten Export durchführen
Der Export Request wird als HTTP GET an ein Client Service gesendet. Der Pfad für das Speichern der Exportanfrage lautet:
<Client Service URL>/api/v2/exportAsync?resource_path=<PFAD_DES_GESPEICHERTEN_EXPORTS>
Um den in 1.1 gespeicherten Export zu starten muss also folgendes HTTP GET durchgeführt werden:
<Client Service URL>/api/v2/exportAsync?resource_path=queryexport/default/4
Der Export wird gestartet. Wenn der Export fertig ist wechselt der Status von PROGRESS auf SUCCESS.
Status des Export abfragen
Jeder Export und dessen Status wird gespeichert. Die gespeicherten Informationen eines Exports können mit folgendem Request abgefragt werden.
Url: <Client Service URL>/api/v2/persistedresources
Der Request hat folgende Form:
{
"read": {
"path": ["queryexports", "default", "4"]
}
}
Die Option path identifiziert den Export dessen Status abgeholt werden soll. Die Antwort liefert status, status_description und den downloaded_timestamp. Da diese Information in den Persisted Resources gespeichert ist kann diese an einem beliebigen Zeitpunkt abgeholt werden.
{
"persisted_resources": [{
"path": [
"queryexports",
"default",
"16"
],
"data": <exportrequest>,
"property": [{
"key": "status_description",
"value": ""
}, {
"key": "downloaded_timestamp",
"value": "2017-05-18T09:24:47+02:00"
}, {
"key": "status",
"value": "SUCCESS"
}
],
"created": "2017-05-18T09:24:43+02:00",
"lastmod": "2017-05-18T09:24:47+02:00",
"owner": "administrator@testlab.mindbreeze.fabagl.fabasoft.com",
"operations": {
"operations": [
"READ",
"UPDATE",
"REMOVE",
"CREATE"
]
}
}
],
"persisted_resource_request": {
"read": {
"path": [
"queryexports",
"default",
"16"
]
},
"user_context": {}
},
"status": {
"success": true
}
}
Export herunterladen
Wenn der Status des Exports SUCCESS ist kann der Export heruntergeladen werden.
<Client Service URL>/api/v2/export?resource_path=<PFAD_DES_GESPEICHERTEN_EXPORTS>
In unserem Beispiel lautet die konkrete URL:
<Client Service URL>/api/v2/export?resource_path=queryexport/default/4
Export Optionen
Um das Ergebnis zu konfigurieren gibt es Export Optionen in der Exportanfrage.
Bestimmen der Eigenschaften die pro Ergebnis exportiert werden sollen
In der Suchanfrage müssen alle Eigenschaften die als „Spalten“ im Ergebnis vorkommen sollen folgendermaßen angegeben werden:
"properties": [{
"formats": ["HTML", "VALUE"],
"name": "title"
}, {
"formats": ["HTML", "VALUE"],
"name": "mes:date"
}, {
"formats": ["HTML", "VALUE"],
"name": "mes:size"
}
In diesem Beispiel werden titel, datum und Größe exportiert.
Export Format bestimmen
Das Format in dem das Ergebnis der Suchanfrage geliefert werden kann über die Option export_format bestimmt werden. Falls kein export_format oder ein nicht verfügbares export_format gesetzt wird, wird das Default Export Format aus den Export Options der Client-Service Konfiguration verwendet.
Folgende Werte und Formate stehen zur Verfügung:
application/x-ms-excel => Ein Microsoft Excel xslx Dokument wird erzeugt.
application/json => Die Ergebnisse werden als JSON Dokument exportiert.
application/zip => Die Daten werden als ZIP exportiert.
text/csv => Die Daten werden als CSV exportiert.
Batch Size konfigurieren
Um die Performance zu erhöhen kann die Größe der Anfragen konfiguriert werden. Per default werden immer 250 Ergebnisse vom Query-Service geholt und verarbeitet, bis die nächsten 250 Ergebnisse geholt werden. Die Batch Size ist so gewählt um den Speicherbedarf im Client-Service zu minimieren. Um eine bessere Performance zu erreichen kann die Batch Size erhöht werden, was jedoch zu mehr Speicherbedarf im Client-Service führt. Mit der Option batch_size kann die Batch Size bis zu dem Limit aus der Client-Service Konfiguration erhöht werden.
Duplikate im Ergebnis verhindern
Um bei den Ergebnissen Duplikate zu verhindern gibt es die Option allow_duplicate. Mit allow_duplicate : false kann erreicht werden das Duplikate im Ergebnisdokument entfernt werden.
Gruppieren von Werten
Wie auch bei SQL können die Ergebnisse nach einzelnen Eigenschaften gruppiert werden. Die Option groupby_properties enthält die Eigenschaften nach denen gruppiert werden soll.
Um z.B.: nach Datum und Titel zu gruppieren kann die Option groupby_properties folgendermaßen konfiguriert werden:
groupby_properties : [“mes:date“, “title“]
Wichtig ist das Eigenschaften nach denen gruppiert werden soll im Search Request auch angefordert werden.
Abbrechen eines Exports
Ein Export kann durch das Senden des original Export Request mit der Option "cancel_pending": true abgebrochen werden.
Der Export Request wird mit HTTP POST an die URL <Client Service URL>/api/v2/export durchgeführt.