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:
- 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 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 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: 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 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": "[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 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 d'orthographe, définissez
QueryInterpretationConfig.force_verbatim_mode
surtrue
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 d'orthographe, définissez
QueryInterpretationOptions.enableVerbatimMode
surtrue
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
surtrue
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
surtrue
dans la requête de recherche.
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
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 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:
- Exécutez une requête initiale spécifiant les propriétés à inclure dans les résultats des attributs.
- Affichez les résultats de la recherche et des 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"
}
]
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 en tant que 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.