Créer une interface de recherche avec l'API Query

L'API Query fournit des méthodes de recherche et de suggestion permettant de créer une interface de recherche ou d'intégrer les résultats dans une application.

Pour les applications Web qui n'ont pas d'exigences particulières, envisagez d'utiliser le widget Recherche. Consultez Créer une interface de recherche avec le widget Recherche.

Créer une interface de recherche

La procédure de création d'une interface de recherche minimale comprend les étapes suivantes :

Configurer une application de recherche
Générer des identifiants OAuth pour l'application
Interroger l'index
Afficher les résultats de la requête

Vous pouvez enrichir l'interface avec des fonctionnalités telles que la pagination, le tri, le filtrage, les attributs et la saisie semi-automatique.

Configurer une application de recherche

Vous devez créer au moins une application de recherche pour chaque interface de recherche. Une application de recherche fournit des paramètres par défaut, tels que les sources de données, l'ordre de tri, les filtres et les attributs. Vous pouvez remplacer ces paramètres à l'aide de l'API Query.

Vous ne pouvez pas augmenter le nombre de sources de données utilisées dans une requête au-delà de celles configurées dans l'application de recherche. Vous pouvez limiter une requête à un sous-ensemble de ces sources à l'aide de dataSourceRestrictions.

Pour en savoir plus, consultez Personnaliser l'expérience de recherche.

Générer des identifiants OAuth pour l'application

Outre les étapes décrites sur la page Configurer l'accès à l'API Cloud Search, vous devez générer des identifiants OAuth pour votre application Web.

Utilisez les identifiants pour demander une autorisation au nom de l'utilisateur. Utilisez le champ d'application https://www.googleapis.com/auth/cloud_search.query.

Pour en savoir plus sur les options OAuth, consultez la page Plate-forme Google Identity.

Interroger l'index

Utilisez la search méthode pour effectuer une recherche dans l'index.

Chaque requête doit inclure un query de texte et un searchApplicationId.

Cet exemple interroge une source de données de film :

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  }
}

Afficher les résultats de la requête

Les interfaces de recherche doivent afficher l'attribut title de l'élément, ainsi qu'un lien permettant d'accéder à l'élément original. Vous pouvez également utiliser des extraits et des métadonnées pour améliorer l'affichage.

Gérer les résultats supplémentaires

Cloud Search renvoie des résultats supplémentaires lorsque le nombre de correspondances pour une requête est insuffisant. Le queryInterpretation champ l'indique. Si seuls des résultats supplémentaires sont renvoyés, InterpretationType est REPLACE. S'ils sont combinés, il s'agit de BLEND.

Lorsque vous renvoyez des résultats supplémentaires, pensez à en informer l'utilisateur. Pour un REPLACE, vous pouvez indiquer : "Votre recherche n'a donné aucun résultat. Affichage des résultats pour des requêtes similaires."

Gérer les résultats concernant des personnes

Cloud Search renvoie des documents liés à des personnes et des informations sur les employés à l'aide de la fonctionnalité Recherche de personnes. Les résultats se trouvent dans le structuredResults champ :

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

Correspondance des collaborateurs directs

La fonctionnalité Correspondance des collaborateurs directs permet aux utilisateurs de voir les collaborateurs directs d'une personne. La réponse inclut un assistCardProtoHolder avec un cardType de RELATED_PEOPLE_ANSWER_CARD.

Désactiver les optimisations

Les optimisations telles que les résultats supplémentaires sont activées par défaut. Vous pouvez les désactiver :

Au niveau de l'application de recherche : définissez force_verbatim_mode sur true.
Au niveau de la requête : définissez enableVerbatimMode sur true.

Mettre en évidence les extraits

Cloud Search renvoie un extrait pour le texte ou le code HTML indexé. Si des termes de requête sont présents, matchRanges identifie leur emplacement. Utilisez ces plages pour mettre en évidence le texte.

function highlightSnippet(snippet) {
  let text = snippet.snippet;
  let formattedText = text;
  if (snippet.matchRanges) {
    let parts = [];
    let index = 0;
    for (let match of snippet.matchRanges) {
      let start = match.start || 0; // Default to 0 if omitted
      let end = match.end;
      if (index < start) { // Include any leading text before/between ranges
        parts.push(text.slice(index, start));
      }
      parts.push('<span class="highlight">');
      parts.push(text.slice(start, end));
      parts.push('</span>');
      index = end;
    }
    parts.push(text.slice(index)); // Include any trailing text after last range
    formattedText = parts.join('');
  }
  return formattedText;
}

Compte tenu de l'extrait :

{
  "snippet": "This is an example snippet...",
  "matchRanges": [
    {
      "start": 11,
      "end": 18
    }
  ]
}

La chaîne HTML résultante est la suivante :

This is an <span class="highlight">example</span> snippet...

Afficher les métadonnées

Utilisez le metadata champ pour obtenir des informations telles que createTime, updateTime et des données structurées. Utilisez displayOptions pour afficher des données structurées.

Récupérer des résultats supplémentaires

Pour récupérer d'autres résultats, définissez le start champ sur le décalage sélectionné. Ajustez la taille de la page avec pageSize. Utilisez resultCount pour afficher le nombre total d'éléments ou des estimations.

Trier les résultats

Utilisez sortOptions pour spécifier l'ordre :

operatorName : propriété à trier.
sortOrder : ASCENDING ou DESCENDING.

La pertinence est la clé de tri par défaut et secondaire.

Ajouter des filtres

Limitez les résultats avec des filtres dans l'application de recherche ou la requête. Si les deux spécifient des filtres pour une source, les deux doivent être évalués sur "true".

Appliquez des filtres dans dataSourceRestrictions.filterOptions[]. Principaux types de filtres :

Filtres d'objet : limitent les correspondances à un type spécifique.
Filtres de valeur : limitent les correspondances en fonction d'un opérateur et d'une valeur.

Les filtres composites combinent plusieurs filtres de valeur.

Affiner les résultats avec des attributs

Les attributs aident les utilisateurs à affiner les requêtes de manière interactive. Lorsque vous demandez des attributs, Cloud Search calcule les valeurs les plus fréquentes pour ces propriétés.

Modèle type : 1. Requête spécifiant les propriétés des attributs. 1. Afficher les résultats de la recherche et des attributs. 1. L'utilisateur sélectionne les valeurs des attributs. 1. Répéter la requête avec un filtre basé sur les sélections.

Marquez une propriété d'entier comme pouvant être utilisée comme attribut pour affiner les résultats par plages (par exemple, "100-200" pages). Définissez isFacetable sur true et définissez les options de compartimentation par défaut dans le schéma.

Utilisez des opérateurs réservés :

itemsize : pour la taille du fichier en octets.
createddatetimestamp : pour la date de création.
lastmodified : pour la date de modification.

Ajouter des suggestions

Utilisez l'API Suggest pour la saisie semi-automatique en fonction de l'historique des requêtes, des contacts et du contenu des documents.

Créer une interface de recherche avec l'API Query