Schnittstellenbeschreibung

api.v2.suggest

Überblick

Mindbreeze InSpire stellt Autovervollständigungsvorschläge mit einer einfachen Schnittstelle zur Verfügung. Diese Schnittstelle basiert auf HTTP und JSON.

Anfragen werden als HTTP POST an ein Client Service gesendet. Der Pfad für Suchanfragen lautet: <Client Service URL>/api/v2/suggest

Die folgende Anfrage fordert 3 Vorschläge für Dokumenttitel mit dem Wortbeginn mindbre an:

{

  "query": "mindbre",

  "count": 3

}

Beispielaufruf mit dem Kommandozeilenwerkzeug curl:

curl https://demo.mindbreeze.com/public/api/v2/suggest -d "{\"query\":\"mindbre\",\"count\":3}"

Beispielantwort

{
  "suggest_request": {
    "query": "mindbre",
    "count": 5,
    "user_context": {}
  },
  "results": [
    {
      "value": "Mindbreeze Basic Training",
      "html": "<span class=\"matched\">Mindbre</span><span class=\"unmatched\">eze Basic Training</span>",
      "score": 9216,
      "source": "DOCUMENT_PROPERTY",
      "source_name": "Name",
      "source_id": "document_property",
      "complete_match": false
    },
    {
      "value": "Mindbreeze Advanced Training",
      "html": "<span class=\"matched\">Mindbre</span><span class=\"unmatched\">eze Advanced Training</span>",
      "score": 8192,
      "source": "DOCUMENT_PROPERTY",
      "source_name": "Name",
      "source_id": "document_property",
      "complete_match": false
    },
    {
      "value": "Mindbreeze Development Training",
      "html": "<span class=\"matched\">Mindbre</span><span class=\"unmatched\">eze Development Training</span>",
      "score": 8192,
      "source": "DOCUMENT_PROPERTY",
      "source_name": "Name",
      "source_id": "document_property",
      "complete_match": false
    }
  ]
}

Felder im Ergebnis

suggest_request

Die Anfrage.

results

Enthält die Vorschläge. Jeder Vorschlag enthält den Text mit Hervorhebungen (html) und ohne (value). complete_match gibt an, ob der Vorschlag exakt dem angefragten Begriff entspricht. score enthält eine Bewertung des Vorschlags, je größer der Wert desto besser. source liefert den Typ der Quelle, source_name  den Anzeigenamen und source_id die ID. Siehe auch Abschnitt Vorschlagsquellen.

Szenarien

Die folgenden Abschnitte zeigen jeweils eine Aufgabe bei der Verwendung von Vorschlägen und können miteinander kombiniert werden.

Einschränkung der Vorschläge

Die Anfrage kann auch mit Einschränkungen versehen werden. Dazu dient das Feld property_constraint. Hier können beliebige QueryExpr-Objekte verwendet werden (Siehe Query Expressions in api.v2.search Schnittstellenbeschreibung). Die Einschränkung bezieht sich aber nur auf Vorschlagsquellen, die die Einschränkung auch unterstützen.

{
  "query": "mindbre",
  "count": 3,
  "property_constraint": {
    "unparsed": url:www.mindbreeze.com
  }
}

Vorschlagsquellen

source_id_pattern legt mit einem Regulären Ausdruck die verwendeten Vorschlagsquellen fest. Dabei kann „document_property“ für Vorschläge aus Metadaten verwendet werden oder die ID-Werte der Vorschlagsquellen in der Konfiguration (z.B. Client Service > Suggest Settings (Similar Terms) oder Suggest Settings (Concept CSV)).

Für Metadatenvorschläge kann das Metadatum mit der Option property ausgewählt werden. Die Vorbelegung ist „title“.

Das folgende Beispiel bringt Vorschläge für das Metadatum „extension“ und die Quellen mit ID „popular_searches“ und „concept“:

{
  "query": "htm",
  "count": 3,
  "source_id_pattern": "document_property|popular_searches|concept",
  "property": "extension"
}

Beispiel für Vorschläge aus Metadaten und allen konfigurierten Quellen:

{
  "query": "htm",
  "count": 3,
  "source_id_pattern": ".*"
}

Lokalisierung von mehrsprachigen Metadaten

user_context.locale gibt das Gebietsschema an, mit dem die mehrsprachige Metadaten übersetzt werden.

{
  "query": "mindbre",
  "count": 3,
  "user_context": {              
    "locale": "de-AT"            
  }
}

Abbrechen von gleichzeitigen Anfragen

Um bereits bestehende Anfragen abzubrechen, kann die Option task_id mitgesendet werden. Dadurch werden alle vorigen Anfragen mit der gleichen task_id abgebrochen.