API de recherche

Copier
GET http://recs.richrelevance.com/rrserver/api/find/v1/<API_KEY> or GET http://integration.richrelevance.com/rrserver/api/find/v1/<API_KEY>

Note: Si vous effectuez des requêtes API de recherche directement depuis les navigateurs Web, il est recommandé de mettre à jour le point de terminaison API vers notre nouveau domaine de capture de données de première partie https://recs.algorecs.com à la place de https://recs.richrelevance.com. Veuillez travailler avec votre consultant Algonomy pour configurer les URL de clic afin qu'elles pointent également vers https://recs.algorecs.com.

Renvoie les résultats de produits pour un terme de recherche. C'est l'API principale pour initier des requêtes de recherche. Vous pouvez spécifier plusieurs paramètres tels que le nombre de produits à retourner, le numéro de page, les filtres à appliquer, etc., pour affiner davantage la requête de recherche.

La réponse est une liste d'informations sur les produits et les facettes nécessaires pour afficher une page de résultats de recherche. Elle peut varier en fonction des paramètres des attributs de recherche disponibles sur le tableau de bord FIND. (Voir ci-dessous pour plus de détails sur l'objet de réponse)

Lors de l'utilisation de l'API de recherche pour l'autocomplétion en tant que suggestions de produits, « recherche instantanée » ou « recherche en ligne », les paramètres suivants doivent être inclus pour garantir des performances optimales :

  • findCallType=overlay

  • facet.enabled=false

  • ngramSearch=true

  • fl=linkId, name, imageId, … (limitez aux seuls champs nécessaires à l'affichage des suggestions de produits)

  • rows= (définissez le nombre exact de produits à afficher)

Paramètres

Les paramètres requis sont suivis des paramètres facultatifs dans l'ordre alphabétique.

Nom

Type de données

Requis ou Facultatif

Description

lang

Chaîne

Requis

Il est recommandé d'utiliser le code ISO à deux caractères tel que "en" pour l'anglais, ou d'utiliser les codes utilisés dans le flux ou dans l'API de catalogue en continu. 

placement

Chaîne

Requis

Chemin de la page à réutiliser : /Template:API/placements

query

Chaîne

Requis

Le texte à rechercher.  

Exemple : query=shoes

Il existe une limite à la taille d'une requête.  Elle est actuellement limitée à 75 caractères. 

rows

Entier

Requis

Rows décrit le nombre de résultats à retourner.  Si vous souhaitez afficher 20 produits sur la page, définissez rows=20.

start

Entier

Requis

La position de départ des résultats que vous souhaitez pour la requête spécifiée.  C'est un système indexé à zéro.  

Par exemple, si vous voulez les 20 premiers résultats, définissez start=0. Si vous voulez les 20 suivants (21-40), définissez start=20.

sessionId

Chaîne

Requis

Identifie une seule visite par un acheteur.  Les sessions sont utilisées par les modèles comportementaux (pour cadrer le comportement de l'utilisateur lors d'une session d'achat) et les métriques de reporting.

Exemple : sessionId=93484

userId

Chaîne

Requis

ID utilisateur. Une chaîne unique pour identifier chaque acheteur (utilisateur). Tous les comportements des acheteurs sont enregistrés en utilisant cette clé. Elle est sensible à la casse et doit être identique à l'ID utilisateur envoyé à Algonomy dans d'autres applications.

Exemple : userId=0982347

Si aucun userId n'est fourni, les résultats de recherche seront basés sur l'historique basé sur la session (sessionId) et le comportement d'achat/vu précédent via le paramètre/cookie rcs. Les résultats de recherche prendront également en compte le comportement de Sagesse Collective.

rcs

Chaîne

Requis

Chaîne de cookie Algonomy. Ceci est le cookie Algonomy crypté pour l'utilisateur associé à la requête API. Il doit être transmis exactement tel qu'il a été reçu dans une réponse API précédente.

Les clients doivent s'assurer de préserver la valeur 'rcs' telle qu'elle a été fournie. Le paramètre 'rcs' est toujours alphanumérique et sensible à la casse, avec une valeur de jeton comprenant un mélange de lettres majuscules, de lettres minuscules et de chiffres.

Note: Le paramètre 'rcs' permet aux marchands de fournir efficacement à la plateforme Algonomy l'accès au cookie navigateur d'un utilisateur Algonomy en agissant comme un proxy de cookie (ou un relais de cookie). Ce processus implique que le marchand lit et écrit le cookie navigateur d'un utilisateur Algonomy et le transmet à Algonomy via l'API côté serveur.

Les paramètres suivants sont facultatifs.

callback

Chaîne

Facultatif

Nom de la fonction JavaScript à laquelle les données JSON seront passées. Cela doit être spécifié pour JSONP. La valeur de ce paramètre est utilisée comme nom de la fonction JavaScript dans la réponse.

Exemple : callback=products_returned

channelId

Chaîne

Facultatif

Channel ID est utilisé par certains rapports Algonomy pour différencier les canaux tels que mobile ou bureau.  Exemples de valeurs : WEB, WEB_PHONE, WEB_TABLET.  Cela peut être une clé API client configurée par un consultant Algonomy pour un client.

facet

Chaîne

Facultatif

Spécifiez les champs/attributs pour lesquels vous souhaitez des facettes dans la réponse. Si vous ne spécifiez rien, tous les attributs configurés pour être facettés (dans le tableau de bord) seront retournés dans la réponse.

Pour une liste de tous les champs applicables, voir la section ci-dessous intitulée "Champs".

facetDepth

Entier

Facultatif

Contrôle le nombre de niveaux de catégories retournés dans le filtre de facette Catégorie.

facetDepth < 0 - Le paramètre de profondeur n'est pas pris en compte, le comportement standard est appliqué, c'est-à-dire que seul le niveau supérieur est retourné lors de la première requête et les enfants ne sont retournés qu'après la sélection du niveau supérieur.

facetDepth == 0 - Ne retourne aucune catégorie à filtrer.

facetDepth > 0 - La profondeur de la catégorie est construite jusqu'au niveau de profondeur maximal ou jusqu'à ce que la profondeur spécifiée dans le paramètre soit atteinte. Exemple : facetDepth=5 retournera 5 niveaux de profondeur si la hiérarchie des catégories possède tous ces niveaux. Si la hiérarchie ne possède que 3 niveaux, alors seuls ces 3 niveaux seront retournés.

facet.limit

Entier

Facultatif

Valeur par défaut = 100

Peut être une valeur entière positive ou négative.

Une valeur négative signifie que Solr retournera un nombre illimité de comptes de contraintes.

Plus d'informations :

https://lucene.apache.org/solr/guide/6_6/faceting_fr.html#Faceting-Thefacet.limitParameter

facet.limit s'applique uniquement aux styles de réponse suivants : fullResponse et facetsOnly.

Note: facetDepth a priorité sur facet.limit et facet.mincount. Lorsque facetDepth est présent, facet.limit et facet.mincount sont ignorés pour le champ catégorie (product_category_name).

facet.mincount

Entier

Facultatif

Valeur par défaut = 0

Peut être une valeur entière.

Pour plus d'informations, voir :

https://lucene.apache.org/solr/guide/6_6/faceting_fr.html#Faceting-Thefacet.mincountParameter

Note: facetDepth a priorité sur facet.limit et facet.mincount. Lorsque facetDepth est présent, facet.limit et facet.mincount sont ignorés pour le champ catégorie (product_category_name).

filter

Chaîne

Facultatif

Appliquez un filtre au terme de recherche. Vous pouvez appliquer plusieurs filtres. Pour une liste de tous les champs applicables, voir la section ci-dessous intitulée "Champs". La réponse (voir la section "Réponse" ci-dessous) vous fournit également une liste de facettes et la façon de filtrer par ces facettes.

Voici un exemple de filtre pour les marques "adidas" et "puma" :

filter=product_brand:"adidas"&filter=product_brand:"puma"

Un autre exemple de filtre avec AND et OR :

filter={!tag=material q.op=OR}material:("Leather" OR "Cotton").

La syntaxe de filtre "tag" est utilisée pour renvoyer toutes les options différentes pour une facette même après filtrage.

findCallType

Chaîne

Facultatif

Spécifie le type d'appel depuis le client. La valeur par défaut est 'direct'.

direct - Si log est vrai, enregistre l'événement de demande de recherche dans le système d'analyse et le transfère également au service de statistiques en temps réel.

overlay - Si log est vrai, enregistre l'événement de demande de recherche dans le système d'analyse, mais ne le transfère pas au service de statistiques en temps réel. Dans ce cas, l'URL de suivi de recherche (searchTrackingUrl) doit être utilisée pour fournir des statistiques en temps réel.

fl

Chaîne

Facultatif

Liste des champs

Le paramètre fl limite les informations incluses dans un ensemble de résultats à une liste spécifiée de champs. L'ensemble de résultats n'inclura que les champs spécifiés dans la liste ainsi que id et score (toujours retournés).

Chaque champ doit être "stockable" ou ses valeurs ne seront pas retournées. La valeur par défaut est de retourner tous les champs stockables.

La liste des champs est spécifiée sous forme de liste de noms de champs séparés par des virgules.

Exemple : fl=size,color renverra : id score size color

Si vide, un caractère générique ou null est utilisé, les comportements suivants se produiront :

fl= (vide) Renvoie tous les champs stockables

fl=* Renvoie tous les champs stockables

fl=null Aucun champ n'est retourné

    Notes:
  • Pour retourner clickURL, veuillez utiliser linkID. L'utilisation de linkId retournera à la fois clickURL et linkID.

  • clickURL est un attribut dérivé et n'a pas d'attributs de recherche associés tels que "stockable".

Exemple :

Exemple : fl=size,color,linkId retournera : id score size color linkID clickURL

log

Booléen

Facultatif

Si défini sur true, cela enregistrera l'événement de demande de recherche pour les analyses. Le comportement par défaut est que ce soit false.

Note: Seules les valeurs "true" et "false" fonctionneront.

mm

Entier

Facultatif

Correspondance minimale

Les valeurs valides pour mm (correspondance minimale) avec des exemples dans Solr sont les suivantes :

  • Entier positif 3

  • Entier négatif -2

  • Pourcentage 75%

  • Pourcentage négatif -25%

  • Une expression 3<90%

  • Expressions conditionnelles multiples impliquant les signes > ou < 2<-25% 9<-3

Pour plus d'informations, voir :

https://lucene.apache.org/solr/guide/6_6/the-dismax-query-parser_fr.html#TheDisMaxQueryParser-Themm_MinimumShouldMatch_Parameter

ngramSearch

Booléen

Facultatif

Les N-grams sont comme une fenêtre glissante qui se déplace sur un mot - une séquence continue de caractères d'une longueur spécifiée, qui dans Find est par défaut définie sur 1. La recherche ngram est souvent utilisée avec une fonction de saisie semi-automatique ou de suggestion. Par exemple, lorsqu'un utilisateur tape chaque caractère dans la barre de recherche, une correspondance basée sur les caractères saisis est effectuée.

Certains clients utilisent l'API Find pour compléter automatiquement des produits au lieu de l'API autocomplete. Il est important pour eux de pouvoir définir ngramSearch=true dans une requête Find. Pour les requêtes générales de produits, il est recommandé de définir ngram=false.

Cette valeur peut être définie au niveau du système par un consultant Algonomy dans la configuration du site. Si elle n'est pas configurée, la valeur par défaut est true. Ce paramètre remplacera à la fois la configuration du site et la valeur par défaut.

ngramSearch=true/false.

searchAttributeBoosts

Chaîne

Facultatif

''searchAttributeBoosts'' spécifie le nom de l'attribut de recherche, la valeur et le montant du boost dans le format suivant "<search-attribute-name>:<value>^<boost-amount>".

Par exemple : "product_brand:LargeSize^0.25"

Pour searchAttributeBoosts, une valeur de boost positive augmente le poids du produit avec cette combinaison attribut:valeur. Une valeur de boost négative déplace le produit à la fin de la liste des résultats de recherche.

pref

Chaîne

Facultatif

Référent de l'utilisateur avant de voir la page. Utilisé pour les rapports et le merchandising. Il est fortement recommandé.

Exemple : pref=http://www.google.com

privm

Boolean

Optional

True/false. If set to true, privacy mode is enabled for the request. In privacy mode, user affinity data is ignored, and search results are generated without personalization based on behavioral data. This ensures that search results respect user consent preferences and do not use behavioral data for users who decline tracking.

Example: privm=true

region

Chaîne

Facultatif

Identifiant de la région

responseStyle

Chaîne

Facultatif

Le paramètre responseStyle contrôle l'ensemble des résultats retournés. Par défaut, tous les champs marqués comme "stockables" sont retournés ainsi que les facettes (facetable). La personnalisation et les boosts seront également appliqués s'ils sont configurés et activés. Le paramètre responseStyle propose plusieurs options détaillées ci-dessous :

  • fullResponse - Par défaut. La limite de l'ensemble des résultats est de 512 lignes.

  • idAndScores - Retourne uniquement les identifiants des produits et leurs scores. La limite de l'ensemble des résultats est de 10 000.

  • facetsOnly - Retourne uniquement les facettes et non les produits ou contenus. Aucune limite n'est appliquée aux facettes retournées. Cependant, le nombre d'éléments retournés dans une facette est par défaut de 100 et peut être contrôlé par le paramètre facet.limit.

  • productsOnly - Retourne uniquement les produits. Ne retourne pas les facettes et n'applique pas de personnalisation, de boosts, de règles de merchandising ou de vérification orthographique.

Exemple d'idAndScores :

Requête :

Copier
https://...start=0&rows=10000&facet=0&query=phone&responseStyle=idAndScores

Réponse :

Copier
....{
     "docs": [
        {   "score": 1,
           "id": "58481" }
......}

sort

Chaîne

Facultatif

Spécifiez comment trier une liste de résultats de produits ou de contenus de référence. Le tri par défaut est personnalisé en fonction du "score" (sort=score desc). Vous pouvez également trier par n'importe quel attribut que vous avez configuré pour être triable dans les attributs de recherche.

Nous recommandons de proposer des options pour trier par ces champs en plus du tri personnalisé :

  • product_rating (Note moyenne des avis)

  • product_effectiveprice_cents (Prix combiné et prix promotionnel)

  • product_release_date (Nouveauté du produit)

Spécifiez également si le tri doit être en ordre croissant ou décroissant. Les valeurs autorisées sont : "asc" ou "desc".

Exemple : sort=product_release_date desc

Vous pouvez spécifier plusieurs champs et inclure un tri secondaire, par exemple :

sort=score desc, field name asc

Note: Les attributs à valeurs multiples ne sont pas triables.

Si le paramètre de tri est incorrect, la valeur par défaut sera utilisée : "score desc".

spellcheck

Chaîne

Facultatif

Find effectuera une vérification orthographique d'un terme de requête lorsque la requête initiale retourne 0 résultat. Une seconde requête est alors exécutée en utilisant le terme corrigé recommandé. La vérification orthographique est basée sur tous les attributs recherchables indexés, à l'exception des attributs liés à la "sagesse de la foule" et du champ product_external_id.

La valeur par défaut est "jaro", un algorithme de similarité permettant de comparer des chaînes courtes.

Les options suivantes de vérification orthographique sont proposées afin de retourner les meilleurs termes suggérés et de répondre aux attentes des clients :

  • jaro - par défaut, JaroWinklerDistance est un algorithme de similarité pour comparer des chaînes courtes.

  • off - la vérification orthographique est désactivée, utile lorsque la requête est un code-barres ou un autre code produit.

  • hits - retourne le terme suggéré ayant le plus grand nombre de résultats.

  • suggest - une liste de suggestions est retournée, utile pour mettre en œuvre "vouliez-vous dire".

  • Ci-dessous, vous trouverez des détails et exemples supplémentaires.

  • jaro - par défaut - non explicitement fourni dans la requête.

Si le paramètre de vérification orthographique n'est pas explicitement défini, le champ "spellchecked" est retourné.

Copier
query=seattle1
Response will include:
"spellchecked" : "seattle"

jaro - parameter provided in query - equivalent result to "query=seattle1".

Note that the "spellcheck" parameter will provide the type of spellcheck and the suggested term.

Copier
query=seattle1&spellcheck=jaro
Response will include:
"spellchecked" : "seattle"
"spellcheck" : {
  "spellcheckType" : "jaro"
  "spellchecked" : "seattle"
}

off

Copier
query=seattle1&spellcheck=off
Response -  "docs" is empty

"spellcheck" : {
  "spellcheckType" : "off"
}

hits - see the "suggest" list below to understand why "settler" is returned

Copier
query=seattle1&spellcheck=hits
Response will include:

"spellchecked" : "settler"
"spellcheck" : {
  "spellcheckType" : "hits"
  "spellchecked" : "settler"
}

suggest

A set of suggested terms are returned that could be used for "did you mean" and to build an alternate query. This option does not automatically execute a second query as is the case for "jaro" and "hits". Two lists are returned: "spellcheckSuggestions" and "suggestionsWithHits" (number of hits for suggested terms is provided).

Copier
query=seattle1&spellcheck=suggest
Response - "docs" is empty

"spellcheck" : {
  "spellcheckSuggestions" : {
    "seattle1" :  ["seattle", "seat tl e1", "settler"]
  },
  "suggestionsWithHits": {"seattle":8,  "settler":20},
  "spellcheckType": "suggest"
}

suggest - multiple search terms

Copier
query=seattle1 washington1&spellcheck=suggest
Response -  "docs" is empty

"spellcheck" : {
  "spellcheckSuggestions" : {
    "seattle1" :  ["seattle", "seat tl e1", "settler"]
    "washington1" :  ["washington", "washing to n1"]
  },
  "suggestionsWithHits": {"seattle washington":8},
  "spellcheckType": "suggest"
}

 

ssl

Booléen

Facultatif

Si défini sur true, alors clickUrl et searchTrackingUrl sont renvoyés avec le protocole HTTPS.

tie

Double

Facultatif

Par défaut, le score de chaque élément dans un ensemble de résultats est basé sur le score "max" d’un champ (avec la personnalisation, les boosts, etc. également pris en compte). Souvent, plusieurs résultats ont le même score. "Tie" est un paramètre Solr qui prend en compte les résultats sur d'autres champs. Il applique le calcul suivant :

score = [score de la sous-requête la mieux notée] + tie * (somme des autres sous-requêtes correspondantes)

Il est recommandé de définir "tie" sur une faible valeur, par exemple 0,1, pour éviter que la somme des autres champs ne domine le champ principal avec le plus de correspondances. Les valeurs peuvent aller de 0,0 à 1,0, avec une valeur par défaut de 0,0.

Exemple de requête : ...query=shoes&rows=15&tie=0.1

Pour plus de détails : Consultez la documentation Solr

fq

String

Facultatif

Le paramètre Requête de Filtrage (fq) est une option de filtrage avancée utilisée en complément du paramètre de filtrage existant. Il permet une logique de requête plus complexe en utilisant la syntaxe Solr et offre une plus grande flexibilité. Cependant, une utilisation excessive peut impacter les performances. Pour plus d'informations sur le paramètre fq, voir, Requête de Filtrage (fq).

Exemple de Réponse

Copier
{
   "request":{
      "apiKey":"showcaseparent",
      "placements":[
         "search_page.sort"
      ],
      "sessionId":"s1234",
      "userId":"u1234"
   },
   "placements":[
      {
         "searchTrackingUrl":"http://localhost:8101/rrserver/api/v1/service/track/search/showcaseparent?query=t&lang=en&user=u1234&session=s1234&channel=WEB&region=&numFound=1956&placement=search_page.sort&page=0&rcs=eF4FwbENgDAMBMCGill4yUls570BcyRgiYIOmJ-7Zb2_5zo2F6KosfReW3gEWCHLO3eK2NAUpOYJ1WmYVEeatWAdPpg_V-4RTg",
         "rcs":"eF4FwbENgDAMBMCGill4yUls570BcyRgiYIOmJ-7Zb2_5zo2F6KosfReW3gEWCHLO3eK2NAUpOYJ1WmYVEeatWAdPpg_V-4RTg",
         "links": {
            "directlink": [
               {
                  "id": "direct-link-id",
                  "title": "direct-link-title",
                   "subtitle": "direct-link-subtitle",
                  "url": "direct-link-url"
               }
            ],
            "banner": [
               {
                  "id": "banner-id",
                  "title": "banner-title",
                  "subtitle": "banner-subtitle",
                  "url": "banner-url",
                  "image_url": "image-ur"
               }
            ],
            "sponsored": [
               {
                  "id": "sponsored-id",
                  "title": "sponsored-title",
                  "subtitle": "sponsored-subtitle",
                  "url": "sponsored-url",
                  "image_url": "sponsored-image-url"
               }
            ]
         },
         "docs":[
            {
               "clickUrl":"http://localhost:8101/rrserver/api/v1/service/track/click/showcaseparent?a=showcaseparent&vg=80015896-f4fe-44c5-41ab-6654e0877e89&pti=2&pa=sort&hpi=0&stn=PersonalizedProductSearchAndBrowse&stid=184&rti=2&sgs=&u=u1234&mvtId=0&mvtTs=1458177239699&uguid=8005b4f0-f4fe-44c5-c846-f553982b6b8f&channelId=WEB&s=s1234&pg=-1&page=0&query=t&lang=en&p=10308694&ind=0&ct=http://labs.richrelevance.com/storre/catalog/product/view/sku/10308694",
               "imageId":"http://labs.richrelevance.com/storre/media/catalog/product/t/-/t-gel-original-shampoo-8.5oz-1e2df9930cf89d1614debdbaa3feaf38.jpg",
               "linkId":"",
               "salePriceCents":798,
               "name":"T-Gel Original Shampoo, 8.5oz",
               "priceCents":798,
               "id":"10308694"
            },
            {
               "clickUrl":"http://localhost:8101/rrserver/api/v1/service/track/click/showcaseparent?a=showcaseparent&vg=80015896-f4fe-44c5-41ab-6654e0877e89&pti=2&pa=sort&hpi=0&stn=PersonalizedProductSearchAndBrowse&stid=184&rti=2&sgs=&u=u1234&mvtId=0&mvtTs=1458177239699&uguid=8005b4f0-f4fe-44c5-c846-f553982b6b8f&channelId=WEB&s=s1234&pg=-1&page=0&query=t&lang=en&p=10339306&ind=1&ct=http://labs.richrelevance.com/storre/catalog/product/view/sku/10339306",
               "imageId":"http://labs.richrelevance.com/storre/media/catalog/product/a/t/atampampt-2000-minutes-rechargeable-us-ampamp-international-prepaid-phone-card-c9152dba32526ce359e426e5bcad0903.jpg",
               "linkId":"",
               "salePriceCents":4488,
               "name":"AT&amp;T 2000-Minutes Rechargeable US &amp; International PrePaid Phone Card",
               "priceCents":6320,
               "id":"10339306"
            }
         ],
         "numFound":1956,
         "placement":"search_page.sort",
         "spellchecked":null,
         "addtoCartParams": "page=1&query=t&lang=en&searchConfigId=123434sdef3222",
         "errors":[],
         "facets":[
            {
               "values":[
                  {
                     "filter":"{!tag=categories_facet}categoryIds:\"871098905\"",
                     "count":842,
                     "value":"Apparel"
                  },
                  {
                     "filter":"{!tag=categories_facet}categoryIds:\"1985805468\"",
                     "count":519,
                     "value":"Beauty"
                  }
               ],
               "facet":"categories_facet"
            },
            {
               "values":[
                  {
                     "filter":"{!tag=brand_facet}brand_facet:\"Generic\"",
                     "count":126,
                     "value":"Generic"
                  },
                  {
                     "filter":"{!tag=brand_facet}brand_facet:\"Hanes\"",
                     "count":77,
                     "value":"Hanes"
                  }
               ],
               "facet":"brand_facet"
            },
            {
               "min":0,
               "max":10000,
               "values":[
                  {
                     "filter":"product_effectiveprice_cents:[0 TO 5000]",
                     "count":126,
                     "value":"0:5000"
                  },
                  {
                     "filter":"product_effectiveprice_cents:[5000 TO *]",
                     "count":77,
                     "value":"5000:*"
                  }
               ],
               "facet":"product_effectiveprice_cents"
            },
         ]
      }
   ],
   "message":"",
   "status":"OK"
}

 

Nom

Description

request

Les paramètres de la requête qu’a utilisés Algonomy pour traiter la demande. Généralement utilisé à des fins de test.

placements

Dans presque tous les cas, une seule position doit être demandée pour la recherche.  Cet objet contiendra toutes les informations nécessaires pour afficher les résultats de recherche sur une page ou une application.

Ceci est un champ imbriqué contenant plusieurs sous-champs :

  1. searchTrackingUrl :  Une URL utilisée pour les statistiques de requêtes de recherche en temps réel dans l'application client Overlay.  Cette URL doit être invoquée par l'application Overlay, qui envoie également des requêtes de recherche avec findCallType = 'overlay'.

  2. docs :  La liste des produits correspondant au terme recherché - 

    REMARQUE : si le clickUrl est utilisé directement sur le produit et nécessite une redirection vers la page produit,  le paramètre &redirect=true doit être ajouté à chaque clickUrl

  3. numFound : Indique combien de produits dans le catalogue correspondent au terme recherché et aux filtres appliqués.  Cela sert à informer l’utilisateur final du nombre de produits correspondant à son terme de recherche.

  4. placement :  Le nom de cette position.

  5. spellchecked : Si une faute de frappe a été corrigée automatiquement par notre moteur, le terme corrigé sera spécifié ici.  Si aucune correction n'était nécessaire, cette valeur sera vide ou "null".

  6. facets :  Liste de toutes les facettes applicables aux produits correspondant à ce terme de recherche.

  7. addtoCartParams : Paramètres qui doivent être ajoutés lors de l'ajout au panier à partir de la page de détails du produit des résultats de recherche. 

  8. links : liens configurés (URLs) associés au terme de recherche spécifié dans la requête

    1. banner : lien vers l'image de bannière qui doit être affichée avec les résultats de recherche.

    2. directlink : lien vers une autre page où le client doit être redirigé.

    3. sponsored : lien vers du contenu sponsorisé qui doit être affiché. 

errors

Erreurs signalées survenues lors du traitement de la requête.

facets

Les facettes sont retournées comme partie de la structure des placements. Elles permettent une navigation par recherche à facettes facetted search

Les facettes contiennent les champs suivants :

1. values : tableau d’options possibles pour un type de facette donné

2. filter : requête de filtre utilisée lorsque le client sélectionne cette option de facette. La requête de filtre doit être transmise telle quelle au paramètre de filtre de la requête de recherche suivante

3. count : Nombre d’éléments correspondant à cette option de facette. Autrement dit, le nombre d’éléments attendus lorsque le filtre pour cette facette est appliqué.

4. value : Valeur d’affichage de la facette

5. child : Pour les attributs hiérarchiques tels que les catégories, Trouver permet de naviguer dans la hiérarchie en fournissant les catégories enfant immédiates dans les valeurs de facette. Cela se fait en utilisant une catégorie de niveau supérieur comme filtre. Par exemple, filter=categoryId:root retourne les enfants du premier niveau.

6. Prix min - max : Pour les facettes de prix, Trouver retourne les valeurs de prix min et max pour les résultats actuels, permettant d'alimenter une interface avec un curseur de sélection de prix au lieu de cases pour chaque tranche de prix individuelle. 

status

Nous retournons toujours des codes 200.  L'objet "status" indiquera si la requête a été traitée avec succès ("OK") ou si une erreur est survenue ("error").  Les clients doivent vérifier la chaîne "OK" pour confirmation. 

message

Si une erreur s’est produite dans le statut, ce champ contiendra les informations expliquant pourquoi une erreur est survenue.

Champs

Certains attributs de produit partagés via le flux de catalogue ont des noms fixes/réservés et doivent être décrits par leur nom canonique.  Le tableau ci-dessous les décrit.

Nom

Type de Donnée

Description

brand

Chaîne de caractères

La marque du fabricant de ce produit.  Ex. : "Lenovo".

categoryId

Liste de chaînes de caractères 

Les identifiants des catégories auxquelles appartient ce produit.

categoryName

Chaîne de caractères

Les noms des catégories auxquelles appartient ce produit.

description

Chaîne de caractères

La description du produit.

id

Chaîne de caractères

L'identifiant du produit.  Un identifiant unique pour ce produit.

name

Chaîne de caractères

Le nom du produit.

numReviews

Nombre

Nombre total d'avis pour ce produit.

priceCents

Nombre

Le prix régulier de ce produit.

rating

Nombre

La note moyenne du produit.

releaseDate

Date

La date à laquelle ce produit a été introduit dans le catalogue.  Cet attribut permet de calculer la "nouveauté" d'un produit.

salePriceCents

Nombre

Le prix promotionnel de ce produit.

Tous les autres attributs de produit partagés dans le flux peuvent être décrits par le nom dans le flux de catalogue partagé par le détaillant avec Algonomy.

Requête de Filtrage (fq)

  • S'applique à: Requêtes GET et POST dans les appels Find

  • Format: Syntaxe de requête de filtrage Solr avec encodage spécial des caractères

  • Limitations:

    • Les requêtes GET ont une limite de longueur ; utilisez POST pour les valeurs fq volumineuses.

    • Maximum de 1000 clauses booléennes dans toute requête Solr.

Différences principales par rapport au paramètre filter

  • Le paramètre filter permet un filtrage basique, tandis que le paramètre fq prend en charge un filtrage avancé avec une logique booléenne complexe (AND/OR imbriqués).

  • Les caractères spéciaux doivent être encodés à l'aide d'un schéma d'encodage personnalisé (voir ci-dessous).

  • Pour des filtres complexes, privilégiez la méthode POST pour éviter de dépasser les limites de longueur des URL.

  • Une utilisation excessive du paramètre fq peut nuire aux performances de l'API.

  • Limite: Une requête Solr ne peut contenir plus de 1000 clauses booléennes.

Encodage des caractères spéciaux dans fq

Le paramètre fq utilise la syntaxe Solr, ce qui signifie que les noms de champs contenant des caractères spéciaux (comme les espaces) doivent être encodés.

  • Format d'encodage : Même code numérique que l'encodage URL, mais avec $ au lieu de %.

  • Exemple :

    • Champ d'origine : Womens Sizes

    • Encodé en URL : Womens%20Sizes

    • Encodé pour fq : Womens$20Sizes

Exemples d'utilisation

Clause fq basique:

Copier
fq=(Womens$20Sizes:"4")OR(Womens$20Sizes:"5.5")
fq=(Womens$20Sizes:%224%22)OR(Womens$20Sizes:%225.5%22)

Note: $20 (représentant un espace) reste inchangé dans la version encodée de fq.

Filtrage des dates avec fq

Lors de l'utilisation du paramètre fq pour filtrer les plages de dates, il est important de structurer la requête de manière à favoriser une mise en cache efficace et à éviter les dégradations de performance.

À éviter:

fq=date:[* TO NOW]

Pourquoi c'est mauvais?

  • NOW est évalué à la milliseconde, ce qui en fait une valeur constamment changeante.

  • Conséquence : Cela empêche la mise en cache et rend la requête moins efficace.

  • Solution : Si une précision milliseconde est réellement nécessaire, envisagez d'ajouter cache=false.

Modèles recommandés

Utilisez des unités de temps arrondies (comme le jour ou l'heure) pour des requêtes plus efficaces et facilement cachées.

fq=date:[* TO NOW/DAY+1DAY]

  • Avantage: Ronde NOW au jour actuel et ajoute un jour.

  • Optimisé pour le cache: La requête ne change qu'une seule fois par jour.

fq=date:[* TO NOW/HOUR+1HOUR]

  • Avantage: Ronde NOW à l'heure actuelle et ajoute une heure.

  • Optimisé pour le cache: La requête se met à jour toutes les heures, idéale pour les cas d'utilisation temporels fréquents.

Note: L'utilisation de NOW/DAY ou NOW/HOUR permet de rendre vos filtres plus stables et cacheables, améliorant ainsi les performances globales des requêtes fréquemment exécutées.

Instantané

L'instantané est un paramètre permettant de référencer un instantané dans un état "Complet" (pas encore activé) afin de vérifier les résultats avant d'activer l'instantané.

Note: L'instantané est uniquement destiné aux clients utilisant le catalogue en streaming.

searchConfig

Le paramètre searchConfig peut être ajouté à la requête Find avec l'URL du fichier JSON encodée en tant que valeur. Ce paramètre est transmis au moteur de recherche Solr, où la configuration peut être remplacée par une requête Find incluant le paramètre HTTP searchConfig avec un fichier JSON encodé.

Le format du paramètre de requête Find pour toute clé searchConfig prise en charge est :

Copier
&searchConfig.<keyName>=urlEncoded(jsonValue)

Pour remplacer la configuration, remplacez la clé keyName par un attribut produit requis associé à la recherche :

Copier
&searchConfig=urlEncoded(fullSearchConfigJson)
 
Exemple :
&searchConfig.searchAttributeBoosts= urlEncoded(["excessInventory:LargeSize^0.25","excessInventory:MidSizer^0.0","excessInventory:SmallSize^0.0"])

Find ajoute ces valeurs au fichier JSON de configuration complémentaire dans le portail UI, ce qui garantit que les paramètres passés dans la requête remplacent toujours ceux définis dans la configuration. Pour une même paire attribut:valeur, la valeur de renforcement de la requête remplacera la valeur de renforcement par défaut configurée.

Vous pouvez remplacer les éléments individuels suivants de la configuration de recherche configurée dans le Test Drive :

  • SearchAttributeBoosts
  • SearchAttributeFilters
  • psEnable (personnalisation)
  • synonymWeight

searchAttributeBoosts

searchAttributeBoosts est un paramètre clé transmis à Solr, où il recalculera la sortie pour renforcer les résultats de recherche. Ce paramètre spécifie le nom de l'attribut de recherche, sa valeur et l'intensité du renforcement au format suivant : "<nom-attribut-recherche>:<valeur>^<intensité-renforcement>".

Exemple : Le nom de l'attribut de recherche est 'excessInventory', la valeur est 'LargeSize' et l'intensité est '0.25'.

Copier
&searchConfig.searchAttributeBoosts= urlEncoded("excessInventory:LargeSize^0.25")

Une valeur de renforcement positive augmente l'importance du produit avec cette combinaison attribut:valeur, tandis qu'une valeur négative déplace le produit à la fin de la liste des résultats de recherche.

searchAttributeFilters

Copier
searchConfig.searchAttributeFilters=urlEncoded(["product_effectiveprice_cents:500"])

psEnable

Copier
psEnablesearchConfig.psEnable=false

synonymWeight

Copier
synonymWeightsearchConfig.synonymWeight=1.1

ngramSearch

Les n-grams sont comme une fenêtre glissante qui se déplace sur un mot, une séquence continue de caractères de longueur spécifiée, qui par défaut est de 1 dans Find. Le paramètre ngramSearch est souvent utilisé avec la fonctionnalité d'autocomplétion ou de suggestion anticipée. Par exemple, lorsqu'un utilisateur saisit des caractères dans la barre de recherche, il y a une correspondance basée sur les caractères entrés. Certains clients Find utilisent l'API Find pour l'autocomplétion de produits à la place de l'API d'autocomplétion. Pour ces cas, il est important de définir ngramSearch=true dans la requête Find. Il est recommandé de le désactiver (ngramSearch=false) pour les requêtes produit générales.

Il peut y avoir un paramètre global dans la configuration du site que le consultant Algonomy met en place. Si ce paramètre n'est pas défini, la valeur par défaut est true. Ce paramètre dans la requête Find remplacera les paramètres du site ainsi que la valeur par défaut.

Copier
ngramSearch=true/false

Minimum Match (mm)

Minimum Match (Correspondance minimale) indique le nombre minimal de termes devant correspondre. Les spécifications incluent les formats suivants et leurs valeurs valides avec un exemple de paramètre dans Solr :

  • Entier positif 3 : Indique une valeur fixe, quel que soit le nombre de clauses optionnelles.
  • Entier négatif -2 : Indique que le total des clauses optionnelles, moins ce nombre, doit être obligatoire.
  • Pourcentage 75% : Indique le pourcentage nécessaire du total des clauses optionnelles. Le nombre calculé est arrondi à l'inférieur.
  • Pourcentage négatif -25% : Indique le pourcentage manquant des clauses optionnelles. Ce pourcentage est arrondi à l'inférieur avant d'être soustrait du total.
  • Expression 3<90% : Une spécification conditionnelle où un entier positif est suivi du symbole <, puis d'un des spécificateurs précédents. Exemple : pour 1 à 3 clauses, toutes sont requises, mais au-delà de 4 clauses, seulement 90% sont requises.
  • Expressions multiples 2<-25% 9<-3 : Plusieurs spécifications conditionnelles séparées par des espaces. Exemple : pour 1 ou 2 clauses, toutes sont requises ; pour 3 à 9 clauses, 25% peuvent manquer ; au-delà de 9 clauses, trois peuvent manquer.

Pour plus d'informations, consultez :

Copier
https://lucene.apache.org/solr/guide/6_6/the-dismax-query-parser_fr.html#TheDisMaxQueryParser-Themm_MinimumShouldMatch_Parameter

Use Cases

Voici les cas d'utilisation du paramètre searchConfig :

Cas d'utilisation 1

Aucune entrée dans siteConfig.searchConfig et une entrée valide dans Find API searchConfig

  • Portail de configuration du site (searchConfig)

    Copier
    {"psEnable":true, ... "ngramSearch":true}
  • Find API searchConfig

    Copier
    &searchConfig.searchAttributeBoosts=["size:US_8^0.25","size:US_7^0.33"]

Cas d'utilisation 2

Entrée valide pour searchAttributeBoosts dans siteConfig.searchConfig et dans Find API searchConfig

  • Portail de configuration du site (searchConfig)

    Copier
    {"searchAttributeBoosts":["product_brand:Zalora^2.0"], ... , "ngramSearch":true}
  • Find API searchConfig

    Copier
    &searchConfig.searchAttributeBoosts=["size:US_8^0.25","size:US_7^0.33"]

Cas d'utilisation 3

Entrée valide pour searchAttributeBoosts dans siteConfig.searchConfig et entrée invalide dans Find API searchConfig

  • Portail de configuration du site (searchConfig)

    Copier
    {"searchAttributeBoosts":["product_brand:Zalora^2.0"], ... , "ngramSearch":true}
  • Find API searchConfig

    Copier
    &searchConfig.searchAttributeBoosts=["size:US_8^0.25","size:US_7^0.33"

Cas d'utilisation 4

Entrée valide pour searchAttributeBoosts dans siteConfig.searchConfig et champ invalide dans Find API searchConfig

  • Portail de configuration du site (searchConfig)

    Copier
    {"searchAttributeBoosts":["product_brand:Zalora^2.0"], ... , "ngramSearch":true}
  • Find API searchConfig

    Copier
    &searchConfig.searchAttributeBoosts=["invalidField:abc^2"]

Cas d'utilisation 5

Propriété searchConfig de type chaîne

  • Portail de configuration du site (searchConfig)

    Copier
    {"mm":"50%", ... , "ngramSearch":true}
  • Find API searchConfig

    Copier
    &searchConfig.mm="100%"

Cas d'utilisation 6

Propriété searchConfig de type chaîne invalide

  • Portail de configuration du site (searchConfig)

    Copier
    {"mm":"50%", ... , "ngramSearch":true}
  • Find API searchConfig

    Copier
    &searchConfig.mm=100%
  • Erreurs du service de recherche (si présentes)

    Ignorant la configuration de recherche invalide fournie dans la requête :

    Copier
    &searchConfig.mm=100%

Cas d'utilisation 7

Propriété searchConfig de type entier

  • Portail de configuration du site (searchConfig)

    Copier
    {"psditem":25, ... , "ngramSearch":true}
  • Find API searchConfig

    Copier
    &searchConfig.psdItem=10

Cas d'utilisation 8

Propriété searchConfig de type double

  • Portail de configuration du site (searchConfig)

    Copier
    {"psdMaxS":0.9, ... , "ngramSearch":true}
  • Find API searchConfig

    Copier
    &searchConfig.psdMaxS=0.5

Cas d'utilisation 9

Propriété searchConfig de type objet JSON

  • Portail de configuration du site (searchConfig)

    Copier
    {"offMenu":{"offMenuFlagField":"onlySearchableByArticleNumber",

                                    "offMenuSearchField":"articleNumber","offMenuDefault":"exclude"},

                                ,..,"ngramSearch":true}
  • Find API searchConfig

    Copier
    &searchConfig.offMenu={"offMenuFlagField":"onlySearchableByArticleNumber",

                                "offMenuSearchField":"articleNumber","offMenuDefault":"include"}

Cas d'utilisation 10

Propriété de type booléen pour searchConfig

  • Portail de configuration du site (searchConfig)

    Copier
    {"psditem":25, ... , "ngramSearch":true}
  • Find API searchConfig

    Copier
    &searchConfig.ngramSearch=false

Cas d'utilisation 11

Combinaison de diverses propriétés de searchConfig

  • Portail de configuration du site (searchConfig)

    Copier
    {"psEnable":true,"psdItem":25,"psdMinS":0.0,"psdMaxS":0.9,
                                    "pBal":4.0,"enableMetrics":true,"emw":10.0,"synonymWeight":0.9,
                                    "ngramSearch":false,"tie":0.5,"vbp":1.9,"pbp":1.9,"rufws":true,
                                "searchAttributeBoosts":["product_brand:ZALORA^2.0"]}
  • Find API searchConfig

    Copier
    &searchConfig.searchAttributeBoosts=["product_effectiveprice_cents:5000^100"
                                    ,"product_brand:ZALORA^5","InvalidField:abc^2"]
                                    &searchConfig.searchAttributeFilters=["product_effectiveprice_cents:500"]
                                    &searchConfig.ngramSearch=true
                                &searchConfig.synonymWeight=1.1
  • Erreurs de service de recherche (le cas échéant)

    invalidField n'existe pas dans le schéma pour la requête de boost avec la valeur :

    Copier
    [invalidField:"abc"^2]

Filtrage et recherche par date

Find est implémenté avec un champ de date permettant aux clients d'utiliser ce champ personnalisé pour effectuer des requêtes sur une plage de dates. Cette fonctionnalité aide les clients à gérer la visibilité des produits dans la collection Solr. Certains clients peuvent nécessiter la prise en charge des opérations mathématiques sur les dates dans leurs requêtes Find afin de répondre à leurs besoins, notamment le tri par date de sortie, le filtrage des nouveaux produits, la période de garantie, etc. Le champ de date est une fonctionnalité activable.

Note: Si vous utilisez l'API de streaming, vous devez créer un nouvel instantané après l'activation de la configuration du site.

Paramètres de configuration du site

Effectuez les étapes suivantes pour configurer le champ de date :

  1. Sur la page Personalization PlatformTableau de bord, accédez à Admin > Configurations du site RR.

    La page Configurations du site s'affiche.

  2. Dans la zone de recherche, tapez 'search' pour afficher uniquement les configurations de recherche.

  3. Dans la section autres configurations du site, cliquez sur correspondant à la configuration content search config json.

  4. Ajoutez l'index suivant et définissez-le sur 'true' pour activer la recherche basée sur les dates.

    Copier
    {
                                            ...
                                            "enableDateIndexing": true,
                                            ...
                                        }
  5. Cliquez sur pour enregistrer la configuration de recherche.

    Voici un exemple où un champ de date est ajouté comme nouveau type de données avec les types existants.

    Copier
    {
                                            "id": 0,
                                            "itemType": "product",
                                            "state": "creating",
                                            "definitions": {
                                            ...
                                            "publish_date": {
                                            "dataType": "date",
                                            "origin": "derived",
                                            "required": false,
                                            "findAttributeSettings": {
                                            "facetable": false,
                                            "storable": true,
                                            "searchable": false,
                                            "filterable": true,
                                            "sortable": false,
                                            "regionAware": false,
                                            "customerAware": false,
                                            "excludeFromSpellcheck": false,
                                            "exactMatch": false,
                                            "queryTaggable": false
                                            }
                                            },
                                            "product_release_date": {
                                            "dataType": "date",
                                            "origin": "derived",
                                            "required": false,
                                            "findAttributeSettings": {
                                            "facetable": false,
                                            "storable": true,
                                            "searchable": false,
                                            "filterable": true,
                                            "sortable": false,
                                            "regionAware": false,
                                            "customerAware": false,
                                            "excludeFromSpellcheck": false,
                                            "exactMatch": false,
                                            "queryTaggable": false
                                            }
                                            }
                                            }
                                        }

Cas d'utilisation

Voici les différents cas d'utilisation où un champ de date est ajouté en tant que nouveau type de données pour différents scénarios :

Cas d'utilisation 1

Champ last_modified indexé dans le type d'article du catalogue lorsque enableDateIndexing est activé.

  • Document final Solr :

    Copier
    {
                                            "id":"1",
                                            "fs_itemType":"product",
                                            "fl_product_id":1,
                                            "fs_product_external_id":"BASIC-Prod-1",
                                            "fd_last_modified":"2022-07-19T22:23:29.282Z"
                                        }
  • Exemple de requête

    last_modified est un champ défini par le système dont la valeur est un horodatage d'ingestion au format date.

    Copier
    rrserver/api/find/v1/c17a665223e4708f?start=0&rows=50& placement=search_page.find&lang=en &query=*
  • Exemple de réponse

    Copier
    {
                                            ...
                                            "docs": [ {
                                            "id": "BASIC-Prod-1",
                                            "id": "BASIC-Prod-2"
                                            }]
                                            ...
                                        }

Cas d'utilisation 2

Champ product_sale_expiry_date (date personnalisée) avec un filtre où le client envoie un horodatage.

  • Document final Solr

    Copier
    {
                                            "id":"2",
                                            "fs_itemType":"product",
                                            "fl_product_id":1,
                                            "fs_product_external_id":"BASIC-Prod-1",
                                            "fd_publish_date":"2022-07-19T22:23:29.282Z"
                                        }
  • Exemple de requête

    Copier
    rrserver/api/find/v1/c17a665223e4708f?start=0&rows=50& placement=search_page.find&lang=en &query=*&fq=publish_date:[2022-05-07T07:57:51.991ZTONOW-11DAY]
  • Exemple de réponse

    Copier
    {
                                            ...
                                            "docs": [ {
                                            "id": "BASIC-Prod-2"    }]
                                            ...
                                        }

Cas d'utilisation 3

Champ product_release_date (date personnalisée) avec un filtre (ENG-21544) - le client envoie une date et une heure

  • Document final Solr

    Copier
    {
                                            "id":"3",
                                            "fl_product_id":63,
                                            "fs_itemType":"product",
                                            "fs_product_external_id":"BASIC-Prod-63",
                                            "sd_release_date":"2022-07-20T22:41:26.326Z",
                                        }
  • Exemple de requête

    Copier
    rrserver/api/find/v1/c17a665223e4708f?start=0&rows=50& placement=search_page.find&lang=en &query=*&fq=publish_date:[2022-02-07T07:57:51.991ZTO2022-02-20T07:57:51.991Z]
  • Exemple de réponse

    Copier
    {
                                            ...
                                            "docs": [ {
                                            "id": "BASIC-Prod-3"    }]
                                            ...
                                        }