Xperience by Kentico + Elasticsearch – schnelle Volltextsuche im CMSMS

Das Anschließen einer On-Premise-Instanz von Elasticsearch kann mit nur wenigen Schritten durchgeführt werden.
In diesem Artikel zeigen wir, welche Schritte erforderlich sind, um Elasticsearch einzurichten, die Indexierung und Datenzuordnung aus Kentico Xperience zu konfigurieren und anschließend die Suche zu implementieren.

Zuerst muss das NuGet-Paket hinzugefügt werden. Führen Sie im Terminal den folgenden Befehl aus:

dotnet add package XperienceCommunity.ElasticSearch

Fügen Sie in der Datei appsettings.json der Anwendung die folgende Konfiguration hinzu, einschließlich des Endpunkts der laufenden Elasticsearch-Instanz und der Authentifizierungsdaten.
Zur Authentifizierung kann entweder ein Benutzername und Passwort oder ein in Kibana generierter API-Schlüssel verwendet werden.

 "SearchServiceEnabled": true,

 "SearchServiceEndPoint": "<your index application url>", //Endpoint der laufenden Elasticsearch-Instanz

 "SearchServiceAPIKey": "<your API Key for Elasticsearch>"

 }

Alternativ können Sie anstelle des API-Schlüssels Benutzername und Passwort verwenden:

"CMSElasticSearch": {

 // ...

 // ...

 "SearchServiceUsername": "<your index application username>",

 "SearchServicePassword": "<your index application password>",

 }

Die Hauptfunktionalität dieser Bibliothek basiert auf dem Konzept einer benutzerdefinierten Indexierungsstrategie, die sich vollständig an das Inhaltsmodell und das gewünschte Suchverhalten anpasst.
Diese Strategie ermöglicht es, genau zu definieren, welche Daten indiziert werden sollen, wie sie in Elasticsearch abgebildet werden und wie auf Inhaltsänderungen reagiert werden soll.
In den folgenden Schritten zeigen wir, wie dieser Prozess mit den bereitgestellten Schnittstellen und Methoden konfiguriert werden kann.

Custom Index Model

Definieren Sie Ihr eigenes Suchmodell, indem Sie das von der Bibliothek bereitgestellte BaseElasticSearchModel erweitern. Dieses Modell wird zum Erstellen des Indexes in Elasticsearch verwendet.

public class DancingGoatSearchModel : BaseElasticSearchModel

{

    public string Title { get; set; }

    public string Content { get; set; }

}

Implementierung der Indexierungsstrategie

Definieren Sie Ihre eigene Implementierung von BaseElasticSearchIndexingStrategy<TSearchModel>, um anzupassen, wie Webseitenelemente oder Inhaltsobjekte für die Indexierung verarbeitet werden.

public class DancingGoatSearchStrategy(...) : BaseElasticSearchIndexingStrategy<DancingGoatSearchModel>
{
    ...
}

Festlegen der Felder (TypeMapping)

Definieren Sie, wie die einzelnen Felder des Modells im Elasticsearch-Index gespeichert werden.
Überschreiben Sie die Methode Mapping(TypeMappingDescriptor<TSearchModel> descriptor).
Diese Methode ermöglicht es, Datentypen der Felder zu definieren und ihr Verhalten innerhalb der Suche festzulegen – z. B. ob sie für die Volltextsuche (text) oder für exakte Filterungen (keyword) verwendet werden sollen.

public override void Mapping(TypeMappingDescriptor<DancingGoatSearchModel> descriptor) =>
    descriptor
        .Properties(props => props
            .Keyword(x => x.Title)
            .Text(x => x.Content));

Die vollständige Liste der Typen finden Sie in der offiziellen Elasticsearch-Dokumentation.

Im nächsten Schritt definieren Sie die Zuordnung der einzelnen Inhaltseigenschaften zu Ihrem eigenen Indexmodell.

Überschreiben Sie die Methode Task<IElasticSearchModel?> MapToElasticSearchModelOrNull(IIndexEventItemModel item) und definieren Sie die Zuordnung zu Ihrer eigenen Implementierung von BaseElasticSearchModel (in diesem Beispiel DancingGoatSearchModel).
Gemeinsame Eigenschaften, die in der Basisklasse definiert sind, werden automatisch abgebildet – Sie müssen also nur benutzerdefinierte Felder des jeweiligen Inhaltstyps zuordnen.

Im folgenden Beispiel wird gezeigt, wie der Inhaltstyp ArticlePage mit der Eigenschaft ArticleTitle und dem Rohinhalt der Seite auf DancingGoatSearchModel abgebildet wird:

public override async Task<IElasticSearchModel?> MapToElasticSearchModelOrNull(IIndexEventItemModel item)
{
    var result = new DancingGoatSearchModel();
 
    if (item is not IndexEventWebPageItemModel indexedPage)
    {
        return null;
    }
 
    if (string.Equals(item.ContentTypeName, ArticlePage.CONTENT_TYPE_NAME, StringComparison.OrdinalIgnoreCase))
    {
        var page = await strategyHelper.GetPage<ArticlePage>(
            indexedPage.ItemGuid,
            indexedPage.WebsiteChannelName,
            indexedPage.LanguageName,
            ArticlePage.CONTENT_TYPE_NAME);
 
        if (page is null)
        {
            return null;
        }
 
        result.Title = page.ArticleTitle ?? string.Empty;
        var rawContent = await webCrawler.CrawlWebPage(page!);
        result.Content = htmlSanitizer.SanitizeHtmlDocument(rawContent);
    }
 
    return result;
}

IIndexEventItemModel ist eine abstrakte Klasse eines Elements, das für die Indexierung verarbeitet wird.
Sie umfasst sowohl IndexEventWebPageItemModel für Webseiteninhalte als auch IndexEventReusableItemModel für wiederverwendbare Inhalte.

Je nach Implementierung können die zu indizierenden Daten beispielsweise mit der generischen Methode GetPage<T> geladen werden, wie in diesem Beispiel gezeigt.

Direkte Änderungen an einem bestimmten Element im CMS lösen automatisch verknüpfte Ereignisse aus, die sicherstellen, dass der entsprechende Eintrag im Index aktuell bleibt.

Wenn jedoch ein verknüpfter Inhalt geändert wird – z. B. ein wiederverwendbares Element, das Teil mehrerer Seiten ist –, muss eine Logik implementiert werden, die anhand der Änderung bestimmt, welche weiteren Elemente im Index neu indiziert werden müssen.

Dafür wird die Methode FindItemsToReindex verwendet.
Alle von dieser Methode zurückgegebenen Elemente werden an MapToElasticSearchModelOrNull(IIndexEventItemModel item) zur Indexierung übergeben.
Diese Methode ist entscheidend, um die Datenkonsistenz im Index bei Änderungen von verknüpften Inhalten sicherzustellen.

Ein Beispiel für die Implementierung dieser Methode finden Sie in der Dokumentation.

Damit die benutzerdefinierte Strategie verwendet werden kann, muss sie über Dependency Injection (DI) registriert werden:

services.AddKenticoElasticSearch(builder =>

{

    builder.RegisterStrategy<DancingGoatSearchStrategy, DancingGoatSearchModel>(nameof(DancingGoatSearchStrategy));

}, configuration);

Der nächste Schritt besteht darin, den Index in der Xperience-Administration zu erstellen.
Dies erfolgt in der Anwendung Elastic Search, die von dieser Bibliothek hinzugefügt wird.
Hier legen Sie den Indexnamen fest, wählen die entsprechende Strategie, Sprachvarianten, Kanäle und Inhaltstypen aus, die indiziert werden sollen.

Nach der Erstellung und Konfiguration des Indexes führen Sie die Aktion Rebuild auf der Seite List of registered Elastic Search indices aus.

Nach dieser Aktion sollte der Index bereits mit Elementen (gemäß der Implementierung Ihrer DancingGoatSearchStrategy) gefüllt und für die Suche und Filterung bereit sein.

📘 Dokumentation – Managing Indexes

Der letzte Schritt ist die Implementierung der eigentlichen Suche.

Die Suche wird über den Dienst IElasticSearchQueryClientService ausgeführt, der es ermöglicht, Suchparameter festzulegen und Daten aus dem Elasticsearch-Index abzurufen.

    var index = searchClientService.CreateSearchClientForQueries(indexName);
 
    page = Math.Max(page, 1);
    pageSize = Math.Max(1, pageSize);
 
    var request = new SearchRequest(indexName)
    {
        From = (page - 1) * pageSize,
        Size = pageSize,
        Query = string.IsNullOrEmpty(searchText)
            ? new MatchAllQuery()
            : new MultiMatchQuery()
            {
                Fields = new[]
                {
                    nameof(DancingGoatSearchModel.Title).ToLower(),
                },
                Query = searchText,
            },
        TrackTotalHits = new TrackHits(true)
    };
 
    var response = await index.SearchAsync<DancingGoatSearchModel>(request);

Bei der Implementierung der Suche wird der ElasticsearchClient (.NET Client v8) verwendet, der sowohl das Fluent API als auch das Object Initializer API unterstützt.
Die Unterschiede zwischen diesen Ansätzen sind in der offiziellen Dokumentation dargestellt.

Die Integration von Elasticsearch in Xperience by Kentico erweitert die Suchmöglichkeiten und bietet eine Flexibilität, die andere Volltextwerkzeuge nicht erreichen.
Diese Integration ermöglicht eine schnelle Indexierung, erweiterte Abfragen und On-Premise-Hosting – ein großer Vorteil für Benutzer, die die volle Kontrolle über ihre Daten behalten möchten.

Mit der Weiterentwicklung der Technologie wird Elasticsearch zu einer noch attraktiveren Lösung für Suchanforderungen in Xperience by Kentico.

Wir hoffen, dass dieser Artikel Ihnen geholfen hat, sich besser in der Integration von Elasticsearch in Xperience by Kentico zurechtzufinden.
Die Möglichkeiten dieser Integration gehen jedoch noch weiter – in der Dokumentation finden Sie beispielsweise Beispiele für das Crawlen von Seiten oder die Verwaltung von Index-Aliasen.

Eine detaillierte Anleitung zur Erstellung einer eigenen Indexierungsstrategie (einschließlich Codebeispielen), zur Datenzuordnung und zur Verbindung mit Kentico Xperience finden Sie im offiziellen Bibliotheks-Repository.