Connecteur Elasticsearch/OpenSearch

Apercu

Le connecteur Elasticsearch/OpenSearch fournit la fonctionnalite permettant de recuperer des donnees a partir d’un cluster Elasticsearch ou OpenSearch et de les enregistrer dans l’index Fess.

Cette fonctionnalite necessite le plugin fess-ds-elasticsearch.

Versions prises en charge

• Elasticsearch 7.x / 8.x

• OpenSearch 1.x / 2.x

Prerequis

1. L’installation du plugin est requise

2. L’acces en lecture au cluster Elasticsearch/OpenSearch est necessaire

3. Les droits d’execution de requetes sont necessaires

Installation du plugin

Methode 1 : Placement direct du fichier JAR

# Telecharger depuis Maven Central
wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-elasticsearch/X.X.X/fess-ds-elasticsearch-X.X.X.jar

# Placement
cp fess-ds-elasticsearch-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/
# ou
cp fess-ds-elasticsearch-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/

Methode 2 : Installation depuis l’interface d’administration

1. Ouvrir « Systeme » -> « Plugins »

2. Telecharger le fichier JAR

3. Redemarrer Fess

Configuration

Configurez depuis l’interface d’administration via « Crawler » -> « Data Store » -> « Nouveau ».

Configuration de base

Element	Exemple
Nom	External Elasticsearch
Nom du gestionnaire	ElasticsearchDataStore
Active	Oui

Configuration des parametres

Connexion de base :

settings.fesen.http.url=http://localhost:9200
index=myindex
size=100
scroll=5m

Connexion avec authentification :

settings.fesen.http.url=https://elasticsearch.example.com:9200
index=myindex
settings.fesen.username=elastic
settings.fesen.password=changeme
size=100
scroll=5m

Configuration multi-hotes :

settings.fesen.http.url=http://es-node1:9200,http://es-node2:9200,http://es-node3:9200
index=myindex
size=100
scroll=5m

Liste des parametres

Parametre	Requis	Description
settings.fesen.http.url	Oui	Hotes Elasticsearch/OpenSearch (plusieurs hotes separes par des virgules)
index	Oui	Nom de l’index cible
settings.fesen.username	Non	Nom d’utilisateur pour l’authentification
settings.fesen.password	Non	Mot de passe pour l’authentification
size	Non	Nombre d’elements recuperes lors du scroll (par defaut : 100)
scroll	Non	Timeout du scroll (par defaut : 1m)
query	Non	JSON de requete (par defaut : match_all)
fields	Non	Champs a recuperer (separes par des virgules)

Configuration du script

Mapping de base :

url=data.url
title=data.title
content=data.content
last_modified=data.timestamp

Acces aux champs imbriques :

url=data.metadata.url
title=data.title
content=data.body.content
author=data.author.name
created=data.created_at
last_modified=data.updated_at

Champs disponibles

• data.<field_name> - Champ du document Elasticsearch

• data._id - ID du document

• data._index - Nom de l’index

• data._type - Type de document (Elasticsearch < 7)

• data._score - Score de recherche

Configuration des requetes

Recuperation de tous les documents

Par defaut, tous les documents sont recuperes. Si le parametre query n’est pas specifie, match_all est utilise.

Filtrage par conditions specifiques

query={"query":{"term":{"status":"published"}}}

Specification de plage :

query={"query":{"range":{"timestamp":{"gte":"2024-01-01","lte":"2024-12-31"}}}}

Conditions multiples :

query={"query":{"bool":{"must":[{"term":{"category":"news"}},{"range":{"views":{"gte":100}}}]}}}

Specification de tri :

query={"query":{"match_all":{}},"sort":[{"timestamp":{"order":"desc"}}]}

Recuperation de champs specifiques uniquement

Limitation des champs avec le parametre fields

settings.fesen.http.url=http://localhost:9200
index=myindex
fields=title,content,url,timestamp
size=100

Pour recuperer tous les champs, ne specifiez pas fields ou laissez-le vide.

Exemples d’utilisation

Crawl d’un index de base

Parametres :

settings.fesen.http.url=http://localhost:9200
index=articles
size=100
scroll=5m

Script :

url=data.url
title=data.title
content=data.content
created=data.created_at
last_modified=data.updated_at

Crawl d’un cluster avec authentification

Parametres :

settings.fesen.http.url=https://es.example.com:9200
index=products
settings.fesen.username=elastic
settings.fesen.password=changeme
size=200
scroll=10m

Script :

url="https://shop.example.com/product/" + data.product_id
title=data.name
content=data.description + " " + data.specifications
digest=data.category
last_modified=data.updated_at

Crawl de plusieurs index

Parametres :

settings.fesen.http.url=http://localhost:9200
index=logs-2024-*
query={"query":{"term":{"level":"error"}}}
size=100

Script :

url="https://logs.example.com/view/" + data._id
title=data.message
content=data.stack_trace
digest=data.service + " - " + data.level
last_modified=data.timestamp

Crawl d’un cluster OpenSearch

Parametres :

settings.fesen.http.url=https://opensearch.example.com:9200
index=documents
settings.fesen.username=admin
settings.fesen.password=admin
size=100
scroll=5m

Script :

url=data.url
title=data.title
content=data.body
last_modified=data.modified_date

Crawl avec limitation de champs

Parametres :

settings.fesen.http.url=http://localhost:9200
index=myindex
fields=id,title,content,url,timestamp
size=100

Script :

url=data.url
title=data.title
content=data.content
last_modified=data.timestamp

Repartition de charge multi-hotes

Parametres :

settings.fesen.http.url=http://es1.example.com:9200,http://es2.example.com:9200,http://es3.example.com:9200
index=articles
size=100
scroll=5m

Script :

url=data.url
title=data.title
content=data.content
last_modified=data.timestamp

Depannage

Erreur de connexion

Symptome : Connection refused ou No route to host

Points a verifier :

1. Verifier si l’URL de l’hote est correcte (protocole, nom d’hote, port)

2. Verifier si Elasticsearch/OpenSearch est en cours d’execution

3. Verifier les parametres du pare-feu

4. Pour HTTPS, verifier si le certificat est valide

Erreur d’authentification

Symptome : 401 Unauthorized ou 403 Forbidden

Points a verifier :

1. Verifier si le nom d’utilisateur et le mot de passe sont corrects

2. Verifier si l’utilisateur a les droits appropries :

   • Droits de lecture sur l’index

   • Droits d’utilisation de l’API scroll

3. Si Elasticsearch Security (X-Pack) est active, verifier la configuration

Index introuvable

Symptome : index_not_found_exception

Points a verifier :

1. Verifier si le nom de l’index est correct (incluant la casse)

2. Verifier si l’index existe :

   GET /_cat/indices
   

3. Verifier si le pattern wildcard est correct (ex: logs-*)

Erreur de requete

Symptome : parsing_exception ou search_phase_execution_exception

Points a verifier :

1. Verifier si le JSON de la requete est correct

2. Verifier si la requete est compatible avec la version d’Elasticsearch/OpenSearch

3. Verifier si les noms de champs sont corrects

4. Tester la requete directement sur Elasticsearch/OpenSearch :

   POST /myindex/_search
   {
     "query": {...}
   }
   

Timeout du scroll

Symptome : No search context found ou Scroll timeout

Solution :

1. Augmenter scroll :

   scroll=10m
   

2. Reduire size :

   size=50
   

3. Verifier les ressources du cluster

Crawl de donnees volumineuses

Symptome : Le crawl est lent ou expire

Solution :

1. Ajuster size (trop grand le ralentit) :

   size=100  # Par defaut
   size=500  # Plus grand
   

2. Limiter les champs recuperes avec fields

3. Filtrer les documents necessaires avec query

4. Diviser en plusieurs data stores (par index, par periode, etc.)

Memoire insuffisante

Symptome : OutOfMemoryError

Solution :

1. Reduire size

2. Limiter les champs recuperes avec fields

3. Augmenter la taille du tas de Fess

4. Exclure les champs volumineux (donnees binaires, etc.)

Connexion SSL/TLS

Cas de certificat auto-signe

Avertissement

Utilisez des certificats signes de maniere appropriee en environnement de production.

Pour utiliser des certificats auto-signes, ajoutez le certificat au keystore Java :

keytool -import -alias es-cert -file es-cert.crt -keystore $JAVA_HOME/lib/security/cacerts

Authentification par certificat client

Si un certificat client est necessaire, des parametres supplementaires sont requis. Consultez la documentation du client Elasticsearch pour plus de details.

Exemples de requetes avancees

Requete avec agregation

Note

Les resultats d’agregation ne sont pas recuperes, seuls les documents sont recuperes.

query={"query":{"match_all":{}},"aggs":{"categories":{"terms":{"field":"category"}}}}

Champs de script

query={"query":{"match_all":{}},"script_fields":{"full_url":{"script":"doc['protocol'].value + '://' + doc['host'].value + doc['path'].value"}}}

Script :

url=data.full_url
title=data.title
content=data.content

Informations de reference

• Apercu des connecteurs DataStore - Apercu des connecteurs Data Store

• Connecteur base de donnees - Connecteur de base de donnees

• Présentation - Guide de configuration Data Store

• Elasticsearch Documentation

• OpenSearch Documentation

• Elasticsearch Query DSL