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

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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

Pour les applications Web avec des exigences minimales, envisagez d'utiliser le widget Recherche. Pour en savoir plus, consultez Créer une interface de recherche avec le widget Recherche.

Créer une interface de recherche

La création d'une interface de recherche minimale nécessite plusieurs étapes:

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

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

Configurer une application de recherche

Vous devez créer au moins une application de recherche à associer à chaque interface de recherche que vous créez. Une application de recherche fournit les paramètres par défaut d'une requête, tels que les sources de données à utiliser, l'ordre de tri, les filtres et les attributs à demander. Si nécessaire, vous pouvez remplacer ces paramètres à l'aide de l'API Query.

Pour en savoir plus sur les applications de recherche, consultez Personnaliser l'expérience de recherche dans Cloud Search.

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

Outre les étapes décrites sur la page Configurer l'accès à l'API Google Cloud Search, vous devez également générer des identifiants OAuth pour l'application Web. Le type d'identifiants que vous créez dépend du contexte dans lequel l'API est utilisée.

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 lorsque vous demandez une autorisation.

Pour en savoir plus sur les options OAuth et les bibliothèques clientes, consultez la page [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}).

Interroger l'index

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

Chaque requête doit inclure deux informations: un texte query qui correspond aux éléments et un identifiant searchApplicationId identifiant l'application de recherche à utiliser.

L'extrait suivant présente une requête portant sur la source de données du film Titanic:

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

Afficher les résultats de la requête

Les interfaces de recherche doivent au minimum afficher l'élément title ainsi qu'un lien vers l'élément d'origine. Vous pouvez améliorer encore davantage l'affichage des résultats de recherche en exploitant des informations supplémentaires, comme l'extrait et les métadonnées.

Gérer les résultats supplémentaires

Par défaut, Cloud Search renvoie des résultats supplémentaires lorsque les résultats de la requête de l'utilisateur sont insuffisants. Le champ queryInterpretation de la réponse indique à quel moment des résultats supplémentaires sont renvoyés. Si seuls les résultats supplémentaires sont renvoyés, InterpretationType est défini sur REPLACE. Si quelques résultats pour la requête d'origine sont renvoyés avec des résultats supplémentaires, InterpretationType est défini sur BLEND. Dans les deux cas, QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.

Lorsque des résultats supplémentaires sont renvoyés, envisagez de fournir du texte pour indiquer qu'ils ont été renvoyés. Par exemple, dans le cas d'un REPLACE, vous pouvez afficher la chaîne "Votre recherche de votre requête d'origine ne correspond à aucun résultat. Affichage des résultats pour des requêtes similaires."

Dans le cas d'une requête BLEND, vous pouvez afficher la chaîne "Votre recherche de votre requête d'origine ne correspondait pas à suffisamment de résultats. y compris les résultats pour des requêtes similaires."

Gérer les résultats des personnes

Cloud Search renvoie deux types de résultats de recherche de personnes : documents liés à une personne dont le nom est utilisé dans la requête et informations sur l'employé pour une personne dont le nom est utilisé dans une requête. Ce dernier type est une fonction de la fonctionnalité de recherche de personnes de Cloud Search. Les résultats de cette requête sont disponibles dans le champ structuredResults d'une réponse d'API de requête:

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

Désactiver les optimisations, y compris les résultats supplémentaires

Par défaut, les optimisations, telles que les résultats supplémentaires, sont activées. Toutefois, vous pouvez désactiver toutes les optimisations ou simplement obtenir des résultats supplémentaires au niveau de l'application de recherche et de la requête:

Mettre en avant des extraits

Pour les éléments renvoyés qui contiennent du texte indexé ou du contenu HTML, un extrait du contenu est renvoyé. Ce contenu aide les utilisateurs à déterminer la pertinence de l'article retourné.

Si des termes de requête sont présents dans l'extrait, une ou plusieurs plages de correspondance identifiant l'emplacement des termes sont également renvoyées.

Utilisez matchRanges pour mettre en surbrillance le texte correspondant lorsque vous affichez les résultats. L'exemple JavaScript suivant convertit l'extrait en balisage HTML, chaque plage correspondante étant encapsulée dans une balise <span>.

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 obtenue est la suivante:

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

Afficher les métadonnées

Utilisez le champ metadata pour afficher des informations supplémentaires sur l'article renvoyé qui peuvent être pertinentes pour les utilisateurs. Le champ metadata inclut les valeurs createTime et updateTime de l'article, ainsi que les données structurées renvoyées associées à celui-ci.

Pour afficher les données structurées, utilisez le champ displayOptions. Le champ displayOptions contient le libellé d'affichage du type d'objet et un ensemble de metalines. Chaque ligne Metaline est un tableau de libellés d'affichage et de paires de valeurs telles que configurées dans le schéma.

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

Pour récupérer des résultats supplémentaires, définissez le champ start de la requête sur le décalage souhaité. Vous pouvez ajuster la taille de chaque page à l'aide du champ pageSize.

Pour afficher le nombre d'éléments renvoyés ou pour afficher les commandes de pagination permettant de parcourir les éléments renvoyés, utilisez le champ resultCount. Selon la taille de l'ensemble de résultats, la valeur réelle ou une valeur estimée est fournie.

Trier les résultats

Utilisez le champ sortOptions pour spécifier l'ordre des éléments renvoyés. La valeur sortOptions est un objet comportant deux champs:

  • operatorName : opérateur de la propriété de données structurées à utiliser comme critère de tri. Pour les propriétés comportant plusieurs opérateurs, vous ne pouvez effectuer un tri qu'à l'aide de l'opérateur d'égalité principal.
  • sortOrder : direction du tri, ASCENDING ou DESCENDING.

La pertinence est également utilisée comme clé de tri secondaire. Si aucun ordre de tri n'est spécifié dans une requête, les résultats ne sont classés que par pertinence.

"sortOptions": {
  "operatorName": "priority",
  "sortOrder": "DESCENDING"
}

Ajouter des filtres

Outre les expressions de requête, vous pouvez appliquer des filtres pour restreindre les résultats. Vous pouvez spécifier des filtres à la fois dans l'application de recherche et dans la requête de recherche.

Pour ajouter des filtres dans une requête ou une application de recherche, ajoutez le filtre dans le champ dataSourceRestrictions.filterOptions[].

Il existe deux méthodes principales pour filtrer davantage une source de données:

  • Les filtres d'objets, via la propriété filterOptions[].objectType, limitent les éléments correspondants au type spécifié, tel que défini dans un schéma personnalisé.
  • Filtres de valeur : ces filtres restreignent les éléments correspondants en fonction d'un opérateur de requête et de la valeur fournie.

Les filtres composites permettent de combiner plusieurs filtres de valeur dans des expressions logiques pour exécuter des requêtes plus complexes.

Dans l'exemple de schéma de film, vous pouvez appliquer une contrainte d'âge basée sur l'utilisateur actuel et restreindre les films disponibles en fonction de la classification MPAA.

{
  "query": "adventure",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>"
  },
  "dataSourceRestrictions": [
    {
      "source": {
        "name": "datasources/<data_source_id>"
      },
      "filterOptions": [
        {
          "objectType": "movie",
          "filter": {
            "compositeFilter": {
              "logicOperator": "AND"
              "subFilters": [
                {
                  "compositeFilter": {
                  "logicOperator": "OR"
                  "subFilters": [
                    {
                      "valueFilter": {
                        "operatorName": "rated",
                        "value": {
                          "stringValue": "G"
                        }
                      }
                    },
                    {
                      "valueFilter": {
                        "operatorName": "rated",
                        "value": {
                          "stringValue": "PG"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Affiner les résultats avec des attributs

Les attributs sont des propriétés indexées qui représentent des catégories permettant d'affiner les résultats de recherche. Utilisez des attributs pour aider les utilisateurs à affiner leurs requêtes de manière interactive et à trouver ainsi des éléments pertinents plus rapidement.

Les attributs peuvent être définis dans votre application de recherche et être remplacés par des paramètres dans votre requête.

Lorsque vous demandez des attributs, Cloud Search calcule les valeurs les plus fréquentes pour les propriétés demandées parmi les éléments correspondants. Ces valeurs sont renvoyées dans la réponse. Utilisez ces valeurs pour créer des filtres qui restreignent les résultats des requêtes suivantes.

Le schéma d'interaction classique avec les attributs est le suivant:

  1. Effectuez une requête initiale spécifiant les propriétés à inclure dans les résultats de l'attribut.
  2. Affichez les résultats de recherche et d'attributs.
  3. L'utilisateur sélectionne une ou plusieurs valeurs d'attribut pour affiner les résultats.
  4. Répétez la requête avec un filtre basé sur les valeurs sélectionnées.

Par exemple, pour permettre l'affinement des requêtes de film par année et par classification MPAA, incluez la propriété facetOptions dans la requête.

"facetOptions": [
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "year"
  },
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "rated"
  }
]

Résultats d'attribut avec des champs entiers

Vous pouvez également utiliser les champs de type entier pour obtenir des résultats de requête d'attribut. Par exemple, vous pouvez marquer une propriété entière appelée book_pages comme une table de face pour affiner les résultats d'une recherche sur les livres avec des pages "100-200".

Lorsque vous configurez votre schéma de champ de propriété entière, définissez isFacetable sur true et ajoutez les options de binning correspondantes à integerPropertyOptions. Cela garantit que des options de binning par défaut sont définies pour chaque propriété d'entier.

Lorsque vous définissez la logique des options de binning, fournissez un tableau de valeurs incrémentielles désignant des plages. Par exemple, si l'utilisateur final spécifie des plages 2, 5, 10, 100, les attributs <2, [2-5), [5-10), [10-100) et >=100 sont calculés.

Vous pouvez remplacer les attributs basés sur des entiers en définissant les mêmes options de binning pour facetOptions dans la requête. Si nécessaire, Cloud Search utilise les options de binning définies dans le schéma lorsque les options d'attribut ne sont définies ni pour l'application de recherche, ni pour la requête. Les attributs définis dans la requête prévalent sur ceux définis dans l'application de recherche, et les attributs définis dans l'application de recherche prévalent sur ceux définis dans le schéma.

Résultats des attributs par taille ou par date

Vous pouvez utiliser des opérateurs réservés pour affiner les résultats de recherche en fonction de la taille du fichier du document, mesurée en octets, ou selon la date de création ou de modification d'un document. Vous n'avez pas besoin de définir un schéma personnalisé, mais vous devez spécifier la valeur operatorName dans le FacetOptions de votre application de recherche.

  • Pour les attributs par taille de document, utilisez itemsize et définissez des options de binning.
  • Pour les facettes par date de création des documents, utilisez createddatetimestamp.
  • Pour l'attribut par date de modification du document, utilisez lastmodified.

Interpréter les buckets d'attributs

La propriété facetResults de la réponse de requête de recherche inclut la requête de filtre exacte de l'utilisateur dans le champ filter pour chaque bucket.

Pour les attributs qui ne sont pas basés sur des entiers, facetResults inclut une entrée pour chaque propriété demandée. Pour chaque propriété, une liste de valeurs ou de plages, appelée buckets, est fournie. Les valeurs les plus fréquentes apparaissent en premier.

Lorsqu'un utilisateur sélectionne une ou plusieurs valeurs à filtrer, créez une requête avec les filtres sélectionnés et interrogez à nouveau l'API.

Ajouter des suggestions

Utiliser l'API suggest pour permettre la saisie semi-automatique des requêtes en fonction de l'historique des requêtes personnelles de l'utilisateur, des contacts et du corpus de documents

Par exemple, l'appel suivant donne des suggestions pour l'expression partielle jo.

{
  "query": "jo",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>",
    "peoplePhotoOptions": {
      "peoplePhotoUrlSizeInPx": 32
    },
    "timeZone": "America/Denver"
  }
}

Vous pouvez ensuite afficher les suggestions obtenues en fonction de votre application.