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 :

Configurez une application de recherche.
Générez des identifiants OAuth pour l'application.
Interrogez l'index.
Affichez les résultats de requête.

Vous pouvez enrichir l'interface avec des fonctionnalités telles que la pagination, le tri, le filtrage, les facettes 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 facettes. 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.

Les identifiants permettent de 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 Google Identity Platform.

Interroger l'index

Utilisez la méthode search pour effectuer des recherches dans l'index.

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

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

{
  "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 complémentaires

Cloud Search renvoie des résultats supplémentaires lorsqu'il n'y a pas assez de correspondances pour une requête. Le champ queryInterpretation indique cette information. Si seuls des résultats supplémentaires sont renvoyés, InterpretationType est défini sur REPLACE. Si elles sont mélangées, il s'agit de BLEND.

Lorsque vous renvoyez des résultats supplémentaires, pensez à en informer l'utilisateur. Pour une REPLACE, vous pouvez dire : "Aucun résultat ne correspond à votre recherche. Résultats pour des requêtes similaires".

Gérer les résultats de personnes

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

{
  "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, comme les résultats supplémentaires, sont activées par défaut. Vous pouvez les désactiver :

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

Mettre en surbrillance les extraits

Cloud Search renvoie un extrait pour le texte ou le code HTML indexés. Si des termes de requête sont présents, matchRanges identifie leur emplacement. Utilisez ces plages pour mettre en surbrillance du 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;
}

Avec cet extrait :

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

La chaîne HTML résultante est :

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

Afficher les métadonnées

Utilisez le champ metadata pour des informations telles que createTime, updateTime et les 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 plus de résultats, définissez le champ start 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 les estimations.

Trier les résultats

Utilisez sortOptions pour spécifier l'ordre :

operatorName : propriété à utiliser comme critère de tri.
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 ou la requête de recherche. Si les deux spécifient des filtres pour une source, les deux doivent renvoyer la valeur "true".

Appliquez des filtres dans dataSourceRestrictions.filterOptions[]. Types de filtres principaux :

Filtres d'objet : limitent les correspondances à un type spécifique.
Filtres de valeur : ils restreignent 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 facettes

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

Schéma type : 1. Requête spécifiant les propriétés des facettes. 1. Affichez les résultats de la recherche et des facettes. 1. L'utilisateur sélectionne des valeurs d'attribut. 1. Répétez la requête avec un filtre basé sur les sélections.

Marquez une propriété entière comme pouvant être utilisée pour créer des facettes afin d'affiner les résultats par plages (par exemple, "100-200" pages). Définissez isFacetable sur true et définissez les options de répartition par défaut dans le schéma.

Utilisez des opérateurs réservés :

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

Ajouter des suggestions

Utilisez l'API suggest pour la saisie semi-automatique basée sur l'historique des requêtes, les contacts et le contenu des documents.

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