- Requête HTTP
- Corps de la requête
- Corps de la réponse
- Champs d'application des autorisations
- QueryInterpretationOptions
- Interprétation de requête
- QueryInterprétation.Interprétation
- QueryInterprétation.Reason
- SearchResult
- Extrait
- MatchRange
- Métadonnées
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo
- StructuredResult
- Orthographe
- FacetResult
- FacetBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts
- SourceResultCount
- Essayer
L'API Cloud Search Query fournit la méthode de recherche, qui renvoie les résultats les plus pertinents à partir d'une requête utilisateur. Les résultats peuvent provenir des applications Google Workspace telles que Gmail ou Google Drive, ou des données que vous avez indexées auprès d'un tiers.
Remarque:L'exécution de cette API nécessite un compte utilisateur standard. Un compte de service ne peut pas effectuer de requêtes API de requête directement. Pour utiliser des requêtes de ce type, configurez la délégation d'autorité au niveau du domaine Google Workspace.
Requête HTTP :
POST https://cloudsearch.googleapis.com/v1/query/search
L'URL utilise la syntaxe de transcodage gRPC.
Corps de la requête
Le corps de la requête contient des données présentant la structure suivante :
Représentation JSON |
---|
{ "requestOptions": { object ( |
Champs | |
---|---|
requestOptions |
Options de requête, telles que l'application de recherche et le fuseau horaire de l'utilisateur. |
query |
Chaîne de requête brute. Consultez les opérateurs de recherche compatibles dans Affiner votre recherche avec des opérateurs. |
pageSize |
Nombre maximal de résultats de recherche à afficher sur une page. Les valeurs valides sont comprises entre 1 et 100 inclus. La valeur par défaut est 10. La valeur minimale est 50 lorsque les résultats supérieurs à 2 000 sont demandés. |
start |
Index de départ des résultats. |
dataSourceRestrictions[] |
Sources à utiliser pour les requêtes. Si cette option n'est pas spécifiée, toutes les sources de données de l'application de recherche actuelle sont utilisées. |
facetOptions[] |
|
sortOptions |
Options de tri des résultats de recherche |
queryInterpretationOptions |
pour interpréter la requête de l'utilisateur. |
contextAttributes[] |
Attributs de contexte de la requête, qui serviront à ajuster le classement des résultats de recherche. Le nombre d'éléments est limité à 10. |
Corps de la réponse
Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :
Réponse de l'API de recherche.
Représentation JSON |
---|
{ "queryInterpretation": { object ( |
Champs | |
---|---|
queryInterpretation |
Résultat d'interprétation de la requête utilisateur. Ce champ est vide si l'interprétation de la requête est désactivée. |
results[] |
Résultats d'une requête de recherche. |
structuredResults[] |
Résultats structurés de la requête de l'utilisateur. Ces résultats ne sont pas comptabilisés dans la taille de page. |
spellResults[] |
Suggestion orthographique pour la requête. |
facetResults[] |
Résultats d'attributs répétés. |
hasMoreResults |
Indique s'il existe d'autres résultats de recherche correspondant à la requête. |
debugInfo |
Informations de débogage sur la réponse. |
errorInfo |
Informations d'erreur sur la réponse. |
resultCounts |
Informations sur le nombre de résultats étendu. |
Champ d'union
Dans les rares cas où le système ne peut pas effectuer de recherches dans tous les documents, exécutez à nouveau la requête. |
|
resultCountEstimate |
Nombre estimé de résultats pour cette requête. |
resultCountExact |
Nombre exact de résultats pour cette requête. |
Champs d'application des autorisations
Nécessite l'un des champs d'application OAuth suivants :
https://www.googleapis.com/auth/cloud_search.query
https://www.googleapis.com/auth/cloud_search
Pour en savoir plus, consultez le guide sur les autorisations.
Options d'interprétation des requêtes
pour interpréter la requête de l'utilisateur.
Représentation JSON |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
Champs | |
---|---|
disableNlInterpretation |
Indicateur permettant de désactiver l'interprétation des requêtes en langage naturel (NL). La valeur par défaut est "false". Définissez cette valeur sur "true" pour désactiver l'interprétation du langage naturel. L'interprétation de NL ne s'applique qu'aux sources de données prédéfinies. |
enableVerbatimMode |
Activez cette option pour désactiver toutes les optimisations internes comme l'interprétation du langage naturel (NL) pour les requêtes, la récupération de résultats supplémentaires et l'utilisation de synonymes, y compris les synonymes personnalisés. L'interprétation de Nl sera désactivée si l'une des deux options est vraie. |
disableSupplementalResults |
Utilisez cet indicateur pour désactiver les résultats supplémentaires d'une requête. Le paramètre des résultats supplémentaires choisis au niveau de SearchApplication sera prioritaire s'il est défini sur "True". |
Interprétation de requête
Représentation JSON |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
Champs | |
---|---|
interpretedQuery |
Interprétation de la requête utilisée dans la recherche. Par exemple, les requêtes dont le langage est de type "e-mail de jean" seront interprétées comme des requêtes "from:john source:mail". Ce champ ne sera pas renseigné lorsque la raison est NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY. |
interpretationType |
|
reason |
Motif de l'interprétation de la requête. Ce champ ne sera pas UNSPECIFIED si le type d'interprétation n'est PAS AUCUN. |
QueryInterprétation.Interprétation
Enums | |
---|---|
NONE |
Ni l'interprétation du langage naturel, ni une version plus large de la requête ne sont utilisées pour récupérer les résultats de recherche. |
BLEND |
Les résultats de la requête d'origine sont combinés à d'autres résultats. La raison de la combinaison de ces autres résultats avec les résultats de la requête d'origine est indiquée dans le champ "Reason" (Motif) ci-dessous. |
REPLACE |
Les résultats de la requête d'origine sont remplacés. Le motif de remplacement des résultats de la requête d'origine est renseigné dans le champ "Motif" ci-dessous. |
QueryInterprétation.Reason
Enums | |
---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
L'interprétation du langage naturel pour la requête permet d'extraire les résultats de recherche. |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY |
La similarité des termes utilisés dans les requêtes et les documents permet d'élargir de manière sélective la requête, afin d'extraire des résultats de recherche supplémentaires. La requête interprétée sera vide pour ce cas. |
Résultat de recherche
Résultats contenant des informations indexées pour un document.
Représentation JSON |
---|
{ "title": string, "url": string, "snippet": { object ( |
Champs | |
---|---|
title |
Titre du résultat de recherche. |
url |
URL du résultat de recherche. L'URL contient une redirection Google vers l'article réel. Cette URL est signée et ne doit pas être modifiée. |
snippet |
Concaténation de tous les extraits (résumés) disponibles pour ce résultat. |
metadata |
des métadonnées du résultat de recherche. |
clusteredResults[] |
Si la source est en cluster, fournissez la liste des résultats en cluster. Il n'y aura qu'un seul niveau de résultats en cluster. Si le clustering n'est pas activé pour la source actuelle, ce champ sera vide. |
debugInfo |
Informations de débogage concernant ce résultat de recherche. |
Snippet
Extrait du résultat de recherche, qui résume le contenu de la page obtenue.
Représentation JSON |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
Champs | |
---|---|
snippet |
Extrait du document. Extrait du document. Peut contenir des caractères HTML avec échappement avant le rendu. |
matchRanges[] |
Plages mises en correspondance dans l'extrait. |
Plage de correspondance
Plage correspondante d'un extrait [début, fin]
Représentation JSON |
---|
{ "start": integer, "end": integer } |
Champs | |
---|---|
start |
Position de départ de la correspondance dans l'extrait. |
end |
Fin de la correspondance dans l'extrait. |
Métadonnées
des métadonnées d'un résultat de recherche avec correspondance.
Représentation JSON |
---|
{ "source": { object ( |
Champs | |
---|---|
source |
Source nommée du résultat, par exemple Gmail. |
mimeType |
Type MIME du résultat de recherche. |
thumbnailUrl |
URL de vignette du résultat. |
owner |
propriétaire (généralement du créateur) du document ou de l'objet du résultat de recherche. |
createTime |
Heure de création de ce document ou de cet objet dans le résultat de recherche. Horodatage au format RFC3339 UTC "Zulu", avec une résolution à la nanoseconde et jusqu'à neuf chiffres après la virgule. Exemples: |
updateTime |
Date de la dernière modification de l'objet dans les résultats de recherche. Si cet élément n'est pas défini, la valeur renvoyée ici est vide. Lorsque Horodatage au format RFC3339 UTC "Zulu", avec une résolution à la nanoseconde et jusqu'à neuf chiffres après la virgule. Exemples: |
fields[] |
Champs indexés dans les données structurées, renvoyés en tant que propriété générique. |
displayOptions |
qui spécifient comment afficher un résultat de recherche de données structurées. |
objectType |
Type d'objet du résultat de recherche. |
ResultDisplayMetadata
Représentation JSON |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
Champs | |
---|---|
objectTypeLabel |
Libellé d'affichage pour l'objet. |
metalines[] |
Contenu des métadonnées à afficher avec le résultat. |
ResultDisplayMetadata.ResultDisplayLine
Ensemble de champs constitués d'une ligne affichée
Représentation JSON |
---|
{
"fields": [
{
object ( |
Champs | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
Afficher les champs des résultats de query.search
Représentation JSON |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
Champs | |
---|---|
label |
Libellé d'affichage pour la propriété. |
operatorName |
Nom d'opérateur de la propriété. |
property |
Paire de valeurs nom de la propriété. |
Informations sur le débogage
Informations de débogage sur le résultat.
Représentation JSON |
---|
{ "formattedDebugInfo": string } |
Champs | |
---|---|
formattedDebugInfo |
Informations de débogage générales mises en forme pour l'affichage. |
StructuredResult
Résultats structurés renvoyés dans la requête de recherche.
Représentation JSON |
---|
{
"person": {
object ( |
Champs | |
---|---|
person |
Représentation d'une personne |
Résultat orthographique
Représentation JSON |
---|
{ "suggestedQuery": string } |
Champs | |
---|---|
suggestedQuery |
L'orthographe suggérée de la requête. |
FacetResult
Réponse pour un attribut spécifique à la source
Représentation JSON |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
Champs | |
---|---|
sourceName |
Nom source pour lequel des résultats d'attribut sont renvoyés. Ce champ est obligatoire. |
objectType |
Type d'objet pour lequel des résultats d'attribut sont renvoyés. Ce champ est vide. |
operatorName |
Nom de l'opérateur choisi pour les attributs. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
FacetBuckets pour les valeurs en réponse contenant au moins un résultat avec le filtre correspondant. |
Ensemble de facettes
Un bucket dans un attribut est l'unité de fonctionnement de base. Un bucket peut comprendre une seule valeur OU une plage de valeurs contiguës, en fonction du type de champ inclus dans le bucket. FacetBucket n'est actuellement utilisé que pour renvoyer l'objet de réponse.
Représentation JSON |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
Champs | |
---|---|
count |
Nombre de résultats correspondant à la valeur du bucket. Les chiffres ne sont renvoyés que pour les recherches dont la précision est assurée. Cloud Search ne garantit pas le nombre d'attributs pour une requête, et il peut arriver que le nombre d'attributs soit présent par intermittence, même pour des requêtes identiques. Ne créez pas de dépendances sur l'existence du nombre d'attributs. Utilisez plutôt les pourcentages d'attributs qui sont toujours renvoyés. |
percentage |
Pourcentage de résultats correspondant à la valeur du bucket. La valeur renvoyée est comprise entre 0 et 100, et est arrondie à un nombre entier si elle est fractionnaire. Si la valeur n'est pas explicitement renvoyée, elle représente un pourcentage arrondi à 0. Ils sont indiqués sous forme de pourcentage pour toutes les recherches. Étant donné que les pourcentages sont toujours renvoyés, vous devez afficher les pourcentages au lieu des totaux. |
filter |
Filtre à transmettre dans la requête de recherche si le bucket correspondant est sélectionné. |
value |
|
RéponseDébogage
Informations de débogage sur la réponse.
Représentation JSON |
---|
{ "formattedDebugInfo": string } |
Champs | |
---|---|
formattedDebugInfo |
Informations de débogage générales mises en forme pour l'affichage. |
Information sur l'erreur
Informations d'erreur sur la réponse.
Représentation JSON |
---|
{
"errorMessages": [
{
object ( |
Champs | |
---|---|
errorMessages[] |
|
ErrorMessage
Message d'erreur par réponse source.
Représentation JSON |
---|
{
"source": {
object ( |
Champs | |
---|---|
source |
|
errorMessage |
|
Nombre de résultats
Informations sur le nombre de résultats
Représentation JSON |
---|
{
"sourceResultCounts": [
{
object ( |
Champs | |
---|---|
sourceResultCounts[] |
Le nombre de résultats pour chaque source avec les résultats. |
Nombre de résultats de source
Informations sur le nombre de résultats par source.
Représentation JSON |
---|
{ "source": { object ( |
Champs | |
---|---|
source |
Source à laquelle les informations sur le nombre de résultats sont associées. |
hasMoreResults |
Indique s'il y a d'autres résultats de recherche pour cette source. |
Champ d'union
|
|
resultCountEstimate |
Estimation du nombre de résultats pour cette source. |
resultCountExact |
Nombre exact de résultats pour cette source. |