api.v2.export
Schnittstellenbeschreibung

Überblick

Mindbreeze InSpire stellt den Export von Suchergebnissen mit einer einfachen Schnittstelle zur Verfügung. Diese Schnittstelle basiert auf HTTP und JSON.

Die Export-Schnittstelle ist spezifisch auf Endnutzer-Workflows zugeschnitten, die Datenexporte basierend auf individuellen Suchanfragen durchführen. Es ist als ergänzendes Tool für die manuelle Datenextraktion konzipiert.

Achtung: Es ist nicht empfohlen diese API für Szenarien zu verwenden, die eine hochfrequente, vollautomatisierte Datenabfrage oder Massenexporte erfordern.

Konfiguration und Voraussetzungen

Der Client Service nutzt diese API, um den Export von Ergebnissen direkt aus der Suche im Browser zu ermöglichen. Alle im Client Service vorgenommenen Exportkonfigurationen gelten für diese API. Siehe auch Konfiguration – Export Funktionalität.

Die Export-API ist primär für die Nutzung über einen Browser konzipiert. Es verarbeitet eingehende Export-Anfragen pro Sitzung. Stellen Sie sicher, dass die Einstellung „Disable Session Cookie“ in der Konfiguration des Client Service nicht aktiviert ist.

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>

In diesem Beispiel ist die URL: <Client Service URL>/api/v2/exportAsync?resource_path=queryexport/default/4

Der Export wird mit dieser Anfrage 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 „title“, „date“ und „size“ 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.