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 de recherche dans une application.

Pour les applications Web qui n'ont pas d'exigences particulières, 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 procédure de création d'une interface de recherche minimale comprend les étapes suivantes :

  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 facettes 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 ajoutez. 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 facettes à demander. Si nécessaire, vous pouvez ignorer 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.

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 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

La méthode search permet d'effectuer des recherches dans l'index.

Chaque requête doit inclure deux informations : le texte query à comparer aux éléments indexés et l'ID searchApplicationId de l'application de recherche à utiliser.

L'extrait suivant montre une requête visant la source de données du film Titanic :

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

Afficher les résultats de la requête

Au minimum, 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 enrichir les résultats de recherche en affichant les informations supplémentaires disponibles, telles que l'extrait et les métadonnées.

Gérer les résultats complémentaires

Par défaut, Cloud Search renvoie des résultats supplémentaires lorsqu'il n'y en a pas assez pour la requête de l'utilisateur. Le champ queryInterpretation de la réponse indique quand des résultats supplémentaires sont renvoyés. Si seuls des 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 complémentaires sont renvoyés, pensez à fournir du texte pour indiquer que des résultats complémentaires ont été renvoyés. Par exemple, dans le cas d'un REPLACE, vous pouvez afficher la chaîne "Aucun résultat ne correspond à votre requête d'origine. Résultats pour des requêtes similaires".

Dans le cas d'un BLEND, vous pouvez afficher la chaîne "Votre recherche pour votre requête d'origine n'a pas trouvé suffisamment de résultats. Résultats, y compris pour les requêtes similaires."

Gérer les résultats de personnes

Cloud Search renvoie deux types de résultats "Personnes" : les documents associés à une personne dont le nom est utilisé dans la requête et les informations sur les employés dont le nom est utilisé dans une requête. Ce dernier type de résultat est une fonction de la fonctionnalité Recherche de personnes de Cloud Search. Les résultats d'une telle requête se trouvent dans le champ structuredResults d'une réponse de l'API Query :

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

Correspondance des collaborateurs directs

La fonctionnalité "Correspondance des subordonnés directs" de la recherche de contacts Cloud Search permet aux utilisateurs de voir les subordonnés directs d'une personne dans leur organisation. Le résultat est disponible dans le champ structuredResults.

Pour les requêtes concernant le responsable ou les collaborateurs directs d'une personne, la réponse comporte un assistCardProtoHolder dans structuredResults. assistCardProtoHolder comporte un champ appelé cardType, qui sera égal à RELATED_PEOPLE_ANSWER_CARD. assistCardProtoHolder contient une fiche appelée relatedPeopleAnswerCard, qui contient la réponse proprement dite. Il contient subject (la personne incluse dans la requête) et relatedPeople, qui correspond à l'ensemble des personnes liées au sujet. Le champ relationType renvoie la valeur MANAGER ou DIRECT_REPORTS.

Le code suivant montre un exemple de réponse pour une requête de correspondance des collaborateurs directs :

{
  "results": [],
  "structuredResults": [{
    "assistCardProtoHolder": {
      "extensions": {
        "@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
        "cardMetadata": {
          "cardCategory": "ANSWER"
        },
        "cardType": "RELATED_PEOPLE_ANSWER_CARD",
        "relatedPeopleAnswerCard": {
          "subject": {
            "email": "AdamStanford@psincs-test01.newjnj.com",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "simonsais@psincs-test01.newjnj.com"
            }
          },
          "relatedPeople": [{
            "email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
            "displayName": "Francisco Jose Martinez"
          }],
          "relationType": "DIRECT_REPORTS",
        }
      }
    }
  }]
}

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. Vous pouvez toutefois désactiver toutes les optimisations ou uniquement les résultats supplémentaires au niveau de l'application de recherche et de la requête :

Mettre en surbrillance les extraits

Les éléments renvoyés contenant du texte indexé ou du contenu HTML sont accompagnés d'un extrait de leur contenu. Ce contenu aide les utilisateurs à déterminer la pertinence de l'élément renvoyé.

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

matchRanges vous permet de mettre en évidence le texte correspondant dans les résultats affichés. L'exemple de script JavaScript suivant convertit l'extrait concerné en un code HTML dans lequel les plages de correspondance sont encadrées par 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;
}

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

Le champ metadata permet d'afficher des informations supplémentaires sur l'élément renvoyé qui sont susceptibles d'intéresser les utilisateurs. Le champ metadata comprend les informations createTime et updateTime de l'élément, ainsi que les éventuelles données structuré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 propriété 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 demande sur le décalage souhaité. Vous pouvez ajuster la taille de chaque page avec le 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

Le champ sortOptions vous permet de spécifier l'ordre des éléments renvoyés. La valeur sortOptions est un objet composé de deux champs :

  • operatorName : opérateur déterminant la propriété des données structurées sur laquelle le tri est basé. Pour les propriétés comportant plusieurs opérateurs, vous ne pouvez trier les résultats qu'à l'aide de l'opérateur d'égalité principal.
  • sortOrder : direction du tri, ASCENDING ou DESCENDING (croissant ou décroissant).

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 sont classés uniquement par ordre de pertinence.

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

Ajouter des filtres

Outre les expressions de requête, vous pouvez utiliser 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.

Si vous souhaitez ajouter un filtre à une requête ou à une application de recherche, ajoutez-le au champ dataSourceRestrictions.filterOptions[].

Vous disposez de deux options principales pour appliquer des filtres supplémentaires à une source de données :

  • Filtres d'objet via la propriété filterOptions[].objectType : ces filtres restreignent 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 pourriez appliquer une contrainte d'âge basée sur l'utilisateur actuel et limiter les films disponibles en fonction de leur 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 facettes

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

Les facettes peuvent être définies dans votre application de recherche et être remplacées par des paramètres dans votre requête.

Lorsqu'il demande des facettes, Cloud Search identifie les valeurs les plus fréquentes des propriétés requises parmi les éléments correspondants. Ces valeurs sont renvoyées dans la réponse. Utilisez ces valeurs pour construire des filtres permettant de réduire les résultats des requêtes ultérieures.

Voici le modèle le plus courant d'interaction avec les facettes :

  1. Exécutez une requête initiale spécifiant les propriétés à inclure dans les résultats des facettes.
  2. Affichez les résultats de la recherche et des facettes.
  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 films 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'attributs avec des champs basés sur des nombres entiers

Vous pouvez également facetter les résultats des requêtes avec des champs basés sur des nombres entiers. Par exemple, vous pouvez marquer une propriété d'entier appelée book_pages comme pouvant être utilisée pour créer des facettes afin d'affiner les résultats d'une recherche sur les livres de "100 à 200" pages.

Lorsque vous configurez le schéma de votre champ de propriété entier, définissez isFacetable sur true et ajoutez les options de répartition correspondantes à integerPropertyOptions. Cela garantit que des options de mise en bucket par défaut sont définies pour chaque propriété pouvant être filtrée par facettes entières.

Lorsque vous définissez la logique des options de mise en buckets, fournissez un tableau de valeurs incrémentielles indiquant les plages. Par exemple, si l'utilisateur final spécifie des plages comme 2, 5, 10, 100, les facettes pour <2, [2-5), [5-10), [10-100) et >=100 sont calculées.

Vous pouvez remplacer les facettes basées sur des nombres entiers en définissant les mêmes options de répartition dans facetOptions dans la requête. Si nécessaire, Cloud Search utilise les options de répartition en buckets définies dans le schéma lorsque ni l'application de recherche ni la requête de recherche n'ont d'options de facette définies. Les facettes définies dans la requête sont prioritaires sur celles définies dans l'application de recherche, et les facettes définies dans l'application de recherche sont prioritaires sur celles définies dans le schéma.

Afficher les résultats par taille ou date du document

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

  • Pour la segmentation par taille de document, utilisez itemsize et définissez les options de segmentation.
  • Pour la segmentation par date de création du document, utilisez createddatetimestamp.
  • Pour créer des facettes par date de modification du document, utilisez lastmodified.

Interpréter les buckets de facettes

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

Pour les facettes qui ne sont pas basées 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ées buckets est fournie. Les valeurs les plus fréquentes apparaissent en premier.

Lorsqu'un utilisateur sélectionne une ou plusieurs valeurs pour le filtrage, construisez une nouvelle requête associée aux filtres sélectionnés et interrogez à nouveau l'API.

Ajouter des suggestions

L'API suggest vous permet de proposer pour les requêtes une saisie semi-automatique basée sur l'historique des requêtes personnelles de l'utilisateur, ainsi que sur ses contacts et son 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 appropriées en fonction de votre application.