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 la section 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 comprend 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 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 attributs. 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 la page 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 client, 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: un texte query à comparer aux éléments indexés et un searchApplicationId identifiant l'ID 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'élément title, 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 lorsque les résultats de la requête de l'utilisateur sont insuffisants. 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 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 des résultats supplémentaires sont renvoyés, envisagez d'ajouter 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 pour votre requête d'origine n'a renvoyé aucun résultat. Affichage des 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. y compris les résultats pour des requêtes similaires."

Gérer les résultats de personnes

Cloud Search renvoie deux types de "résultats de recherche de personnes": les documents liés à une personne dont le nom est utilisé dans la requête et les informations sur les employés 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 personnes de Cloud Search. Les résultats d'une telle requête se trouvent dans le champ structuredResults d'une réponse d'API de requête:

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

Correspondance des collaborateurs directs

La mise en correspondance des collaborateurs directs est une fonctionnalité de la recherche de contacts de Cloud Search qui permet aux utilisateurs de voir les collaborateurs 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 contient un assistCardProtoHolder dans structuredResults. assistCardProtoHolder possède un champ appelé cardType qui sera égal à RELATED_PEOPLE_ANSWER_CARD. assistCardProtoHolder contient une fiche appelée relatedPeopleAnswerCard qui contient la réponse réelle. Il contient subject (la personne incluse dans la requête) et relatedPeople, qui sont l'ensemble des personnes associées à l'objet. Le champ relationType renvoie la valeur MANAGER ou DIRECT_REPORTS.

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

Mettre en évidence 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.

Utilisez matchRanges pour 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 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 requête 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.

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 attributs

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

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

Lorsqu'il demande des attributs, 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-les 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 attributs:

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

Vous pouvez également facetter les résultats de la requête avec des champs basés sur des entiers. Par exemple, vous pouvez marquer une propriété d'entier appelée book_pages comme facettable pour affiner les résultats d'une recherche sur les livres de 100 à 200 pages.

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

Lorsque vous définissez la logique des options de bucketing, fournissez un tableau de valeurs incrémentielles signifiant des plages. Par exemple, si l'utilisateur final spécifie des plages sous la forme 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 entiers en définissant les mêmes options de regroupement sur facetOptions dans la requête. Si nécessaire, Cloud Search utilise les options de bucketing définies dans le schéma lorsque ni l'application de recherche ni la requête ne comportent d'options de facette définies. Les facettes définies dans la requête prévalent sur celles définies dans l'application de recherche, et celles définies dans l'application de recherche prévalent sur celles définies dans le schéma.

Filtrer les résultats par taille ou date des documents

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 de la date de création ou de modification d'un document. Vous n'avez pas besoin de définir de schéma personnalisé, mais vous devez spécifier la valeur operatorName dans le FacetOptions de votre application de recherche.

  • Pour facetter par taille de document, utilisez itemsize et définissez des options de regroupement.
  • Pour facetter par date de création du document, utilisez createddatetimestamp.
  • Pour facetter 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 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.