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

L'API Query fournit des méthodes de recherche et de suggestion pour créer une interface de recherche ou intégrer les 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 améliorer encore 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 l'article Personnaliser l'expérience de recherche dans Cloud Search.

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

En plus des é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 dans l'index.

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

L'extrait suivant montre une requête envoyée à 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'élément title ainsi qu'un lien vers l'élément d'origine. Vous pouvez améliorer l'affichage des résultats de recherche en exploitant les informations supplémentaires présentes dans les résultats de recherche, telles que l'extrait et les métadonnées.

Gérer les résultats supplémentaires

Par défaut, Cloud Search affiche 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 des résultats supplémentaires sont renvoyés, InterpretationType est défini sur REPLACE. Si quelques résultats de 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 certains résultats supplémentaires sont renvoyés, envisagez de fournir du texte pour indiquer que des résultats supplémentaires ont été renvoyés. Par exemple, dans le cas d'une requête REPLACE, vous pouvez afficher la chaîne "La recherche effectuée pour votre requête d'origine n'a donné 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 "La recherche effectuée pour votre requête d'origine n'a pas renvoyé suffisamment de résultats. Inclure les résultats de requêtes similaires. »

Gérer les résultats des utilisateurs

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

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

Mise en correspondance des supérieurs directs

La mise en correspondance des rapports directs est une fonctionnalité de recherche de contacts de Cloud Search qui permet aux utilisateurs d'afficher les subordonnés directs d'un membre de leur organisation. Le résultat est disponible dans le champ structuredResults.

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

Le code suivant montre un exemple de réponse à une requête de correspondance de rapports 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 simplement les résultats supplémentaires au niveau de l'application de recherche et de la requête:

Mettre les extraits en surbrillance

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

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 lors de l'affichage des résultats. L'exemple de code JavaScript suivant convertit l'extrait en code HTML dans lequel chaque plage correspondante est enveloppé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;
}

Voici l'extrait de code:

{
  "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 champs createTime et updateTime de l'article, ainsi que toutes les données structurées associées à l'article qui peuvent être retournés.

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 valeurs metalines. Chaque métaligne 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. En fonction de 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 articles retournés. La valeur sortOptions est un objet comportant deux champs:

  • operatorName : opérateur utilisé pour le tri de la propriété de données structurées. 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 : sens 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 également restreindre les résultats en appliquant des filtres. 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 application de requête ou de recherche, ajoutez-les dans le champ dataSourceRestrictions.filterOptions[].

Il existe deux façons principales de 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 limiter 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 à l'aide d'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 les attributs pour aider les utilisateurs à affiner leurs requêtes de manière interactive et à trouver plus rapidement des éléments pertinents.

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

Lorsque vous demandez des attributs, Cloud Search calcule les valeurs les plus fréquentes des 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 réduisent les résultats des requêtes ultérieures.

Le modèle d'interaction typique avec les attributs est le suivant:

  1. Effectuez une requête initiale spécifiant les propriétés à inclure dans les résultats des attributs.
  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 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 demander des résultats avec des champs basés sur des nombres entiers. Par exemple, vous pouvez marquer une propriété de nombre entier appelée book_pages comme ajout d'attributs pour affiner les résultats d'une recherche sur les livres comportant "100-200" pages.

Lorsque vous configurez votre schéma de champ de propriété d'entier, 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é pouvant contenir des entiers.

Lorsque vous définissez la logique des options de binning, fournissez un tableau de valeurs incrémentielles indiquant des plages. Par exemple, si l'utilisateur final spécifie les plages en tant que 2, 5, 10, 100, les attributs pour <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 sur facetOptions dans la requête. Si nécessaire, Cloud Search utilise les options de binning définies dans le schéma lorsque ni l'application de recherche, ni la requête de requête ne disposent d'options d'attribut définies. Les attributs définis dans la requête sont prioritaires sur les attributs définis dans l'application de recherche, et les attributs définis dans l'application de recherche sont prioritaires sur les attributs définis dans le schéma.

Résultats d'attributs par taille ou date de document

Vous pouvez utiliser des opérateurs réservés pour affiner les résultats de la recherche en fonction de la taille de fichier du document (mesurée en octets) ou de 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 fichier FacetOptions de votre application de recherche.

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

Interpréter les buckets d'attributs

La propriété facetResults dans la réponse à la requête de recherche inclut la requête de filtrage 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

Utilisez l'API suggest pour proposer la saisie semi-automatique pour les requêtes en fonction de l'historique des requêtes personnelles de l'utilisateur, ainsi que des contacts et de 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 obtenues en fonction de votre application.