BoostDoc API

Vue d’ensemble

L’API BoostDoc est une API permettant de gérer les configurations de boost de documents dans Fess. En configurant le boost de documents, vous pouvez augmenter le score des documents correspondant à certaines conditions et les faire apparaître plus haut dans les résultats de recherche.

Le boost est appliqué à chaque document lors de la création de l’index (au moment du crawl). La condition (urlExpr) et la valeur de boost (boostExpr) sont toutes deux évaluées avec le moteur de script indiqué dans le champ scriptType. scriptType peut valoir javascript ou groovy (qui nécessite le plugin fess-script-groovy). L’écran de création de l’interface d’administration préremplit scriptType avec javascript, mais si cette API omet scriptType dans le corps de la requête, il n’est pas prérempli automatiquement et les expressions sont évaluées en tant que Groovy. Les règles multiples sont évaluées dans l’ordre croissant de sortOrder, et seule la valeur de boost de la première règle dont la condition correspond est appliquée (une fois qu’une règle correspondante est trouvée, les règles suivantes ne sont pas évaluées).

Note

Dans l’interface d’administration, urlExpr est affiché sous le nom « Condition », boostExpr sous le nom « Expression de valeur de boost » et scriptType sous le nom « Type de Script ». scriptType n’apparaît que dans les corps de requête et les réponses de création/mise à jour/obtention (liste et détail), pas dans les paramètres de filtre de la liste (urlExpr, boostExpr). Pour plus de détails sur les éléments de configuration, consultez Boost de document.

URL de base

/api/admin/boostdoc

Authentification

Pour utiliser cette API, un jeton d’accès avec la permission Radmin-api est requis. Pour savoir comment obtenir et spécifier un jeton d’accès, consultez Vue d’ensemble de l’API Admin.

Liste des endpoints

Méthode Chemin Description
GET /settings Obtention de la liste des boosts de documents
GET /setting/{id} Obtention d’un boost de document
POST /setting Création d’un boost de document
PUT /setting Mise à jour d’un boost de document
DELETE /setting/{id} Suppression d’un boost de document

Obtention de la liste des boosts de documents

Requête

GET /api/admin/boostdoc/settings

Paramètres

Paramètre Type Requis Description
size Integer Non Nombre d’éléments par page (par défaut : 25)
page Integer Non Numéro de page (commence à 1. Par défaut : 1)
urlExpr String Non Filtrage par expression de condition (correspondance partielle)
boostExpr String Non Filtrage par expression de valeur de boost (correspondance partielle)

Réponse

{
  "response": {
    "status": 0,
    "settings": [
      {
        "id": "boostdoc_id_1",
        "urlExpr": "url.startsWith(\"https://docs.example.com/\")",
        "boostExpr": "3.0",
        "scriptType": "javascript",
        "sortOrder": 1,
        "versionNo": 1
      }
    ],
    "total": 5
  }
}

Note

En plus des champs présentés ci-dessus, chaque objet de configuration dans la réponse inclut également des métadonnées de création/mise à jour (createdBy, createdTime, updatedBy, updatedTime). versionNo est obligatoire lors d’une mise à jour (PUT) ; récupérez sa valeur actuelle via l’API d’obtention ou de liste avant de procéder à la mise à jour.

Obtention d’un boost de document

Requête

GET /api/admin/boostdoc/setting/{id}

Réponse

{
  "response": {
    "status": 0,
    "setting": {
      "id": "boostdoc_id_1",
      "urlExpr": "url.startsWith(\"https://docs.example.com/\")",
      "boostExpr": "3.0",
      "scriptType": "javascript",
      "sortOrder": 1,
      "versionNo": 1
    }
  }
}

Création d’un boost de document

Requête

POST /api/admin/boostdoc/setting
Content-Type: application/json

Corps de la requête

{
  "urlExpr": "url.startsWith(\"https://important.example.com/\")",
  "boostExpr": "5.0",
  "scriptType": "javascript",
  "sortOrder": 0
}

Description des champs

Champ Requis Description
urlExpr Oui Expression de condition. Expression de script retournant un Boolean permettant de déterminer les documents à booster. Correspond au champ « Condition » de l’interface d’administration (maximum 10000 caractères).
boostExpr Oui Expression de valeur de boost. Expression de script retournant la valeur de boost (numérique). Une valeur fixe telle que 3.0 peut également être spécifiée. Correspond au champ « Expression de valeur de boost » de l’interface d’administration (maximum 10000 caractères).
scriptType Non Moteur de script utilisé pour évaluer urlExpr et boostExpr. javascript ou groovy (nécessite le plugin fess-script-groovy). Correspond au champ « Type de Script » de l’interface d’administration (maximum 100 caractères). Si omis, les expressions sont évaluées en tant que Groovy.
sortOrder Oui Ordre d’application. Les règles sont évaluées dans l’ordre croissant et la valeur de boost de la première règle correspondante est appliquée (valeur initiale du formulaire : 0, entier supérieur ou égal à 0).

Réponse

{
  "response": {
    "status": 0,
    "id": "new_boostdoc_id",
    "created": true
  }
}

Mise à jour d’un boost de document

Requête

PUT /api/admin/boostdoc/setting
Content-Type: application/json

Corps de la requête

{
  "id": "existing_boostdoc_id",
  "urlExpr": "url.startsWith(\"https://important.example.com/\")",
  "boostExpr": "10.0",
  "scriptType": "javascript",
  "sortOrder": 0,
  "versionNo": 1
}

Lors de la mise à jour, en plus des champs utilisés lors de la création, id (l’identifiant de la règle cible, 1000 caractères maximum) et versionNo (le numéro de version pour le verrouillage optimiste) sont obligatoires. Spécifiez pour versionNo la valeur actuelle obtenue depuis la réponse de l’API d’obtention ou de liste. La mise à jour échoue si le numéro de version ne correspond pas.

Réponse

{
  "response": {
    "status": 0,
    "id": "existing_boostdoc_id",
    "created": false
  }
}

Suppression d’un boost de document

Requête

DELETE /api/admin/boostdoc/setting/{id}

Réponse

{
  "response": {
    "status": 0
  }
}

Expressions de condition et de valeur de boost

urlExpr (condition) et boostExpr (expression de valeur de boost) sont toutes deux évaluées avec le moteur de script indiqué par scriptType (valeur par défaut : Groovy ; seul l’écran de création de l’interface d’administration préremplit javascript). Dans les expressions, les valeurs des champs du document cible de l’indexation peuvent être référencées comme des variables portant le nom du champ.

  • urlExpr doit retourner un Boolean (exemple : url.startsWith("https://docs.example.com/")). Une simple chaîne d’expression régulière (exemple : .*docs\.example\.com.*) ne retourne pas un Boolean en tant qu’expression de script et ne fonctionne donc pas comme condition. Pour utiliser des expressions régulières, utilisez String#matches (disponible avec la même notation en Groovy comme en JavaScript).

  • boostExpr doit retourner une valeur numérique. Le résultat est converti en float et le boost n’est appliqué que si la valeur est supérieure à 0.

Note

Principales variables de champs référençables dans les expressions : url, title, content, content_length, last_modified, etc. click_count et favorite_count sont disponibles respectivement lorsque indexer.click.count.enabled / indexer.favorite.count.enabled sont activés (toutes deux activées par défaut). La syntaxe de calcul de date OpenSearch telle que now - 7d ne peut être utilisée ni en Groovy ni en JavaScript.

Exemples d’expressions de condition (urlExpr)

Expression de condition Description
url.startsWith("https://docs.example.com/") Cible les documents dont l’URL commence par la valeur spécifiée
url.matches("https://www\\.example\\.com/.*") Évalue l’URL avec une expression régulière (String#matches)
title.contains("Notes de version") Cible les documents dont le titre contient un mot spécifique

Exemples d’expressions de valeur de boost (boostExpr)

Expression de valeur de boost Description
3.0 Boost avec une valeur fixe
click_count * 0.1 + 1 Boost proportionnel au nombre de clics
Math.log(click_count + 1) Boost sur une échelle logarithmique basée sur le nombre de clics

Exemples d’utilisation

Boost d’un site de documentation

curl -X POST "http://localhost:8080/api/admin/boostdoc/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "urlExpr": "url.startsWith(\"https://docs.example.com/\")",
       "boostExpr": "5.0",
       "sortOrder": 0
     }'

Boost de contenu populaire

curl -X POST "http://localhost:8080/api/admin/boostdoc/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "urlExpr": "url.startsWith(\"https://www.example.com/\")",
       "boostExpr": "click_count * 0.1 + 1",
       "sortOrder": 10
     }'

Informations complémentaires