Cette page a été traduite par l'API Cloud Translation.

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 des résultats de recherche dans une application.

Pour les applications Web avec une configuration minimale requise, 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 implique plusieurs étapes:

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

Vous pouvez améliorer 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

Outre les étapes décrites dans la section 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 searchApplicationId identifiant l'ID de l'application de recherche à utiliser.

L'extrait suivant montre une requête vers 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 encore l'affichage des résultats de recherche en exploitant des informations supplémentaires présentes dans ces résultats, telles que 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 lorsqu'il n'y a pas suffisamment de résultats pour la requête de l'utilisateur. 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 les 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 qu'ils ont été renvoyés. Par exemple, dans le cas d'une requête REPLACE, vous pouvez afficher la chaîne "Votre recherche 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 suivante : "Votre recherche pour votre requête d'origine ne correspond pas à suffisamment de résultats. Inclure les résultats pour des requêtes similaires. »

Gérer les résultats de recherche de contacts

Cloud Search renvoie deux types de "résultats de personnes": des documents concernant une personne dont le nom est utilisé dans la requête et des 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 sont disponibles dans le champ structuredResults de la réponse d'une API de requête:

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

Correspondance directe avec les rapports

La mise en correspondance directe des rapports est une fonctionnalité de recherche de contacts de Cloud Search qui permet aux utilisateurs de voir 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 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 réelle. Elle contient les subject (personne incluse dans la requête) et relatedPeople, qui correspondent à 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 rapports directs correspondant:

{
  "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:

Pour désactiver toutes les optimisations au niveau de l'application de recherche, y compris les résultats supplémentaires, les synonymes et les corrections orthographiques, définissez QueryInterpretationConfig.force_verbatim_mode sur true dans les applications de recherche.
Pour désactiver toutes les optimisations au niveau de la requête de recherche, y compris les résultats supplémentaires, les synonymes et les corrections orthographiques, définissez QueryInterpretationOptions.enableVerbatimMode sur true dans la requête de recherche.
Pour désactiver les résultats supplémentaires au niveau de l'application de recherche, définissez QueryInterpretationOptions.forceDisableSupplementalResults sur true dans la requête de recherche.
Pour désactiver les résultats supplémentaires au niveau de la requête de recherche, définissez QueryInterpretationOptions.disableSupplementalResults sur true dans la requête de recherche.

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 JavaScript suivant convertit l'extrait en un balisage HTML dans lequel chaque plage correspondante est encadrée 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;
}

D'après 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 retourné qui peuvent être pertinentes pour les utilisateurs. Le champ metadata inclut les attributs createTime et updateTime de l'article, ainsi que toutes les données structurées qui lui sont associées.

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 métaligne est un tableau d'étiquettes 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. En fonction de la taille de l'ensemble de résultats, la valeur réelle ou 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 pour le tri. Pour les propriétés comportant plusieurs opérateurs, vous ne pouvez effectuer le 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 sont classés uniquement par pertinence.

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

Ajouter des filtres

En plus des expressions de requête, vous pouvez restreindre davantage 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 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'objet, 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 facettes 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 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 limitent les résultats des requêtes suivantes.

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

Effectuez une requête initiale spécifiant les propriétés à inclure dans les résultats des attributs.
Affichez les résultats de recherche et d'attributs.
L'utilisateur sélectionne une ou plusieurs valeurs d'attribut pour affiner les résultats.
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"
  }
]

Vous pouvez également définir des attributs pour les résultats des requêtes avec des champs basés sur des entiers. Par exemple, vous pouvez marquer une propriété d'entier appelée book_pages comme attributable pour affiner les résultats d'une recherche sur les livres comportant "100-200".

Lorsque vous configurez le schéma de votre 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é d'attributs 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 des plages comme 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 les 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 n'ont d'options d'attributs définies. Les attributs définis dans la requête sont prioritaires sur ceux définis dans l'application de recherche, et ceux définis dans l'application de recherche sont prioritaires sur ceux définis dans le schéma.

Vous pouvez utiliser des opérateurs réservés pour affiner les résultats de 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 FacetOptions de votre application de recherche.

Pour effectuer des facettes en fonction de la taille du document, utilisez itemsize et définissez les options de binning.
Pour les facettes par date de création du document, utilisez createddatetimestamp.
Pour les facettes en fonction de la date de modification du document, utilisez lastmodified.

Interpréter les buckets d'attributs

La propriété facetResults de la réponse à la requête de recherche inclut la requête de filtre exacte de l'utilisateur dans le champ filter de 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 nouvelle requête avec les filtres sélectionnés et interrogez à nouveau l'API.

Ajouter des suggestions

Utilisez l'API suggest pour permettre la saisie semi-automatique des requêtes en fonction de l'historique des requêtes personnelles de l'utilisateur, ainsi que de ses 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 correspondant à votre application.