L'API Query fournit des méthodes de recherche et de suggestion pour créer une recherche. l'interface ou l'intégration de 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:
- 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 grâce à 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 de recherche que vous avez créée. Une application de recherche fournit paramètres d'une requête, tels que les sources de données à utiliser, l'ordre de tri des filtres et des 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
En plus des étapes décrites dans 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
le champ d'application https://www.googleapis.com/auth/cloud_search.query
lors de la demande
une autorisation.
Pour en savoir plus sur les options OAuth et les bibliothèques clientes, consultez [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}).
Interroger l'index
Utilisez le search
pour effectuer des recherches par rapport à l'index.
Chaque requête doit inclure deux informations: un texte query
pour faire correspondre les éléments et un searchApplicationId
identifiant l'identifiant
l'application de recherche à 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
Les interfaces de recherche doivent au minimum afficher l'élément title
sous la forme
ainsi qu'un lien vers
l'élément d'origine. Vous pouvez améliorer l'affichage
Résultats de recherche en exploitant les informations supplémentaires présentes dans les résultats de recherche
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 en cas de
de résultats insuffisants pour la requête de l'utilisateur. La
queryInterpretation
dans la réponse indique quand des résultats supplémentaires sont renvoyés. Si seulement
résultats supplémentaires sont renvoyés, InterpretationType
est défini sur REPLACE
. Si
quelques résultats de la requête initiale s'affichent, ainsi que
résultats, 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, pensez à fournir du texte
pour indiquer que des résultats
supplémentaires ont été renvoyés. Par exemple, dans le cas d'une
REPLACE
, vous pouvez afficher la chaîne "La recherche correspondant à votre requête d'origine a
aucun résultat. Affichage des résultats pour des requêtes similaires."
Dans le cas d'une BLEND
, vous pouvez afficher la chaîne "Votre recherche pour
La requête d'origine ne correspondait pas à suffisamment de résultats. Inclusion des résultats pour des termes similaires
requêtes."
Gérer les résultats des utilisateurs
Cloud Search renvoie deux types de "résultats de contacts" : les documents associés à un
personne dont le nom est utilisé dans la requête et les informations sur l'employé concernant une personne
dont le nom est utilisé dans une requête. Ce dernier type de résultat est une fonction
la fonctionnalité Recherche de contacts. Les résultats de ce type de requête sont disponibles dans
la
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 directe des rapports est une fonctionnalité de recherche de contacts de Cloud Search qui permet
les utilisateurs voient les subordonnés directs
d'une personne de leur organisation.
Le résultat est disponible dans le champ structuredResults
.
Pour les questions concernant le responsable ou les subordonnés d'une personne, la réponse contient une
assistCardProtoHolder
dans le structuredResults
. La
assistCardProtoHolder
comporte un champ appelé cardType
, qui sera égal à
RELATED_PEOPLE_ANSWER_CARD
L'élément assistCardProtoHolder
contient une carte.
appelé relatedPeopleAnswerCard
, qui contient la réponse réelle.
Elle contient subject
(la personne qui a été incluse dans la requête) et
relatedPeople
, qui correspondent à l'ensemble de personnes associées au sujet. La
Le champ relationType
renvoie la valeur MANAGER
ou DIRECT_REPORTS
.
Le code suivant présente un exemple de réponse pour une correspondance requête:
{
"results": [],
"structuredResults": [{
"assistCardProtoHolder": {
"extensions": {
"@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
"cardMetadata": {
"cardCategory": "ANSWER"
},
"cardType": "RELATED_PEOPLE_ANSWER_CARD",
"relatedPeopleAnswerCard": {
"subject": {
"email": "[email protected]",
"displayName": "Adam Stanford"
"manager": {
"email": "[email protected]"
}
},
"relatedPeople": [{
"email": "[email protected]",
"displayName": "Edgar Mountain Ramirez"
}, {
"email": "[email protected]",
"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 Vous devez toutefois désactiver toutes les optimisations ou simplement les résultats supplémentaires application de recherche et niveau des requêtes:
Pour désactiver toutes les optimisations au niveau de l'application de recherche, y compris y compris les résultats supplémentaires, les synonymes, et corrections orthographiques, définissez
QueryInterpretationConfig.force_verbatim_mode
àtrue
dans les applications de recherche.Pour désactiver toutes les optimisations au niveau de la requête de recherche, y compris résultats supplémentaires, synonymes et corrections orthographiques, définissez
QueryInterpretationOptions.enableVerbatimMode
à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
àtrue
dans la requête de recherche.Pour désactiver les résultats supplémentaires au niveau des requêtes de recherche, définissez
QueryInterpretationOptions.disableSupplementalResults
àtrue
dans la requête de recherche.
Mettre les extraits en surbrillance
Pour les articles renvoyés contenant du texte ou du contenu HTML indexé, un extrait du contenu est renvoyé. Ce contenu aide les utilisateurs à déterminer la pertinence de l'article renvoyé.
Si l'extrait contient des termes de requête, une ou plusieurs plages de correspondance identifiant l'emplacement des termes sont également renvoyés.
Utiliser matchRanges
pour mettre en surbrillance le texte correspondant lors de l'affichage
les résultats. L'exemple de code JavaScript suivant convertit l'extrait en
Balisage HTML avec chaque plage correspondante 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;
}
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 metadata
pour afficher des informations supplémentaires sur l'article renvoyé qui peuvent être pertinentes
aux utilisateurs. Le champ metadata
inclut les champs createTime
et
updateTime
de l'article, ainsi que toute donnée structurée pouvant être retournée associée
avec l'article.
Pour afficher les données structurées, utilisez la méthode displayOptions
.
. Le champ displayOptions
contient le libellé d'affichage du type d'objet
et un ensemble de metalines
. Chaque métaligne est un tableau
de libellés d'affichage et
des paires de valeurs, comme indiqué dans le schéma.
Récupérer des résultats supplémentaires
Pour récupérer des résultats supplémentaires, définissez start
dans la requête au décalage souhaité. Vous pouvez ajuster la taille
de chaque page avec le paramètre pageSize
.
Pour afficher le nombre d'éléments renvoyés ou pour afficher les commandes de pagination
les articles retournés, utilisez la méthode
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 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é des données structurées. Pour les propriétés comportant plusieurs opérateurs, vous ne pouvez trier qu'en utilisant l'égalité principale .sortOrder
: sens du tri (ASCENDING
ouDESCENDING
).
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
Outre les expressions de requête, vous pouvez restreindre davantage les résultats en appliquant filtres Vous pouvez spécifier des filtres application de recherche ainsi que dans la requête de recherche.
Pour ajouter des filtres à une application de requête ou de recherche, ajoutez-les dans la section
dataSourceRestrictions.filterOptions[]
.
Il existe deux façons principales de filtrer davantage une source de données:
- Filtres d'objets, via la propriété
filterOptions[].objectType
: restreignent des éléments correspondants au type spécifié, tel que défini dans un schéma personnalisé. - Filtres de valeur — limite les éléments correspondants en fonction d'une opérateur de requête et la valeur fournie.
Filtres composites permettent de combiner plusieurs filtres de valeur dans des expressions logiques pour obtenir des requêtes 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 la recherche résultats. Utilisez les facettes pour aider les utilisateurs à affiner leurs requêtes de manière interactive et à trouver les articles pertinents plus rapidement.
Les attributs peuvent être définis application de recherche Google. 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 pour les attributs les propriétés demandées parmi les éléments correspondants. Ces sont renvoyées dans la réponse. Utiliser ces valeurs pour créer des filtres qui restreignent les résultats lors des requêtes suivantes.
Le modèle d'interaction typique avec les attributs est le suivant:
- Effectuer une requête initiale spécifiant les propriétés à inclure dans l'attribut résultats.
- 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 affiner les requêtes de films
par année et classification MPAA,
inclure 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 :
peut marquer une propriété de nombre entier appelée book_pages
comme attribut permettant de l'affiner
résultats pour une recherche de livres avec "100-200" .
Lorsque vous configurez le schéma de votre champ de propriété d'entier, définissez
isFacetable
à true
et ajouter les options de binning correspondantes à la
integerPropertyOptions
Cela garantit que chaque propriété pouvant contenir un nombre entier dispose d'un binning par défaut
définies.
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
2, 5, 10, 100
, puis les facettes pour <2
, [2-5)
, [5-10)
, [10-100)
, >=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 demande. 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 comportent d'attribut
définies. Les attributs définis dans la requête prévalent sur les attributs définis
dans l'application de recherche, et les attributs définis dans celle-ci prennent
sur les attributs définis dans le schéma.
Résultats d'attributs par taille ou date de document
Vous pouvez utiliser
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 du moment
un document a été créé ou modifié. Vous n'avez pas besoin de définir un schéma personnalisé,
Toutefois, vous devez spécifier la valeur operatorName
dans le fichier
FacetOptions
- 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
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 fourni. 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 avec avec les filtres sélectionnés et interroger l'API à nouveau.
Ajouter des suggestions
Utiliser l'API suggest pour proposer une saisie semi-automatique pour les requêtes en fonction des requêtes, des contacts et de leur corpus de documents.
Par exemple, l'appel suivant donne des suggestions pour l'appel partiel pour l'expression jo.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Vous pouvez ensuite afficher les suggestions en fonction de votre application.