Method: query.search

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 d'applications Google Workspace, telles que Gmail ou Google Drive, ou de données que vous avez indexées auprès d'un tiers.

Remarque:L'exécution de cette API nécessite un compte utilisateur final standard. Un compte de service ne peut pas effectuer directement des requêtes API Query. Pour utiliser un compte de service pour effectuer des requêtes, 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 (RequestOptions)
  },
  "query": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
Champs
requestOptions

object (RequestOptions)

Options de requête, telles que l'application de recherche et le fuseau horaire de l'utilisateur
query

string

Chaîne de requête brute. Consultez les opérateurs de recherche compatibles dans Affiner votre recherche avec des opérateurs.
pageSize

integer

Nombre maximal de résultats de recherche à renvoyer 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 des résultats supérieurs à 2 000 sont demandés.
start

integer

Index de départ des résultats.
dataSourceRestrictions[]

object (DataSourceRestriction)

Sources à utiliser pour les requêtes. Si aucune valeur n'est spécifiée, toutes les sources de données de l'application de recherche actuelle sont utilisées.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

Les options de tri des résultats de recherche
queryInterpretationOptions

object (QueryInterpretationOptions)

pour interpréter la requête de l'utilisateur.
contextAttributes[]

object (ContextAttribute)

Attributs de contexte de la requête qui seront utilisés pour 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 Search.

Représentation JSON 
{
  "queryInterpretation": {
    object (QueryInterpretation)
  },
  "results": [
    {
      object (SearchResult)
    }
  ],
  "structuredResults": [
    {
      object (StructuredResult)
    }
  ],
  "spellResults": [
    {
      object (SpellResult)
    }
  ],
  "facetResults": [
    {
      object (FacetResult)
    }
  ],
  "hasMoreResults": boolean,
  "debugInfo": {
    object (ResponseDebugInfo)
  },
  "errorInfo": {
    object (ErrorInfo)
  },
  "resultCounts": {
    object (ResultCounts)
  },

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Champs
queryInterpretation

object (QueryInterpretation)

Résultat de l'interprétation de la requête pour la requête de l'utilisateur. Vide si l'interprétation des requêtes est désactivée.
results[]

object (SearchResult)

Résultats d'une requête de recherche
structuredResults[]

object (StructuredResult)

Résultats structurés pour la requête utilisateur. Ces résultats ne sont pas comptabilisés dans le paramètre "pageSize".
spellResults[]

object (SpellResult)

Suggestion orthographique pour la requête.
facetResults[]

object (FacetResult)

Résultats répétés des attributs.
hasMoreResults

boolean

Indique si d'autres résultats de recherche correspondent à la requête.
debugInfo

object (ResponseDebugInfo)

Informations de débogage sur la réponse.
errorInfo

object (ErrorInfo)

Informations d'erreur sur la réponse.
resultCounts

object (ResultCounts)

Informations développées sur le nombre de résultats.

Champ d'union result_count. Nombre total de résultats pour toutes les sources de données demandées. Omis si des sources prédéfinies sont incluses dans l'ensemble de sources de données interrogées. Le nombre de résultats peut être renvoyé sous forme d'estimation plutôt que sous forme exacte dans les cas suivants:

  • Lorsque la requête contient plus de deux termes dans une expression (par exemple, "nombre de résultats exact" entre guillemets).

  • Lorsque le nombre de LCA de résultats de recherche uniques à évaluer est trop élevé pour être calculé avec une latence raisonnable.

Dans les rares cas où le système ne parvient pas à rechercher dans tous les documents, exécutez à nouveau la requête. result_count ne peut être qu'un des éléments suivants :
resultCountEstimate

string (int64 format)

Estimation du nombre de résultats pour cette requête.
resultCountExact

string (int64 format)

Le 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 relatif aux autorisations.

QueryInterpretationOptions

pour interpréter la requête de l'utilisateur.

Représentation JSON 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
Champs
disableNlInterpretation

boolean

Indicateur pour désactiver l'interprétation en langage naturel des requêtes. La valeur par défaut est "false". Définissez cette valeur sur "true" pour désactiver l'interprétation en langage naturel. L'interprétation des Pays-Bas ne s'applique qu'aux sources de données prédéfinies.
enableVerbatimMode

boolean

Activez cet indicateur pour désactiver toutes les optimisations internes, telles que l'interprétation des requêtes en langage naturel (NL), la récupération supplémentaire des résultats et l'utilisation de synonymes, y compris des synonymes personnalisés. L'interprétation NS est désactivée si l'un des deux indicateurs est vrai.
disableSupplementalResults

boolean

Utilisez cet indicateur pour désactiver les résultats supplémentaires pour une requête. Les paramètres des résultats supplémentaires choisis au niveau de SearchApplication sont prioritaires s'ils sont définis sur "True".

QueryInterpretation

Représentation JSON 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Champs
interpretedQuery

string

Interprétation de la requête utilisée dans la recherche. Par exemple, les requêtes dont l'intent en langage naturel est "e-mail de jean" seront interprétées comme "from:jean source:mail". Ce champ ne sera pas renseigné si la raison est NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

Motif d'interprétation de la requête. Ce champ ne sera pas UNSPECIFIED si le type d'interprétation n'est pas NONE.

QueryInterpretation.InterpretationType

Enums
NONE Ni l'interprétation en langage naturel, ni une version plus large de la requête ne sont utilisées pour extraire les résultats de recherche.
BLEND Les résultats de la requête d'origine sont mélangés à d'autres résultats. La raison pour laquelle ces autres résultats sont fusionnés avec ceux de la requête d'origine est indiquée dans le champ "Motif" ci-dessous.
REPLACE Les résultats de la requête d'origine sont remplacés. Le motif du remplacement des résultats de la requête d'origine est indiqué dans le champ "Motif" ci-dessous.

QueryInterpretation.Reason

Enums
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT L'interprétation en langage naturel de la requête est utilisée pour récupérer les résultats de la recherche.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY La similarité entre les termes de requête et de document permet d'élargir de manière sélective la requête afin d'extraire des résultats de recherche supplémentaires, car le nombre de résultats pour la requête de l'utilisateur est insuffisant. La requête interprétée sera vide dans ce cas.

SearchResult

Résultats contenant des informations indexées pour un document.

Représentation JSON 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Champs
title

string

Titre du résultat de recherche.
url

string

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

object (Snippet)

Concaténation de tous les extraits (résumés) disponibles pour ce résultat.
metadata

object (Metadata)

les métadonnées du résultat de recherche.
clusteredResults[]

object (SearchResult)

Si la source est en cluster, fournissez la liste des résultats mis en cluster. Il n'y aura qu'un seul niveau de résultats groupés. Si le clustering n'est pas activé pour la source actuelle, ce champ sera vide.
debugInfo

object (ResultDebugInfo)

Informations de débogage sur 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 (MatchRange)
    }
  ]
}
Champs
snippet

string

Extrait du document. Extrait du document. Peut contenir un caractère HTML avec échappement qui ne doit pas être échappé avant l'affichage.
matchRanges[]

object (MatchRange)

Plages correspondantes dans l'extrait.

MatchRange

Plage correspondante d'un extrait [début, fin).

Représentation JSON 
{
  "start": integer,
  "end": integer
}
Champs
start

integer

Position de départ de la correspondance dans l'extrait.
end

integer

Fin de la correspondance dans l'extrait.

Métadonnées

les métadonnées d'un résultat de recherche correspondant.

Représentation JSON 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
Champs
source

object (Source)

Source nommée pour le résultat, par exemple Gmail.
mimeType

string

Type MIME du résultat de recherche.
thumbnailUrl

string

URL de la vignette du résultat.
owner

object (Person)

propriétaire (généralement le créateur) du document ou de l'objet du résultat de recherche.
createTime

string (Timestamp format)

Date et heure de création de ce document ou de cet objet dans les résultats de recherche.

Code temporel au format RFC3339 UTC "Zulu", avec une résolution à la nanoseconde et jusqu'à neuf chiffres fractionnaires. Exemples: "2014-10-02T15:01:23Z" et "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Date de la dernière modification de l'objet dans le résultat de recherche. Si elle n'est pas définie dans l'élément, la valeur renvoyée est vide. Lorsque updateTime est utilisé pour calculer la fraîcheur et n'est pas défini, cette valeur par défaut est définie sur deux ans à partir de l'heure actuelle.

Code temporel au format RFC3339 UTC "Zulu", avec une résolution à la nanoseconde et jusqu'à neuf chiffres fractionnaires. Exemples: "2014-10-02T15:01:23Z" et "2014-10-02T15:01:23.045123456Z".
fields[]

object (NamedProperty)

Champs indexés dans les données structurées, renvoyés sous la forme d'une propriété nommée générique
displayOptions

object (ResultDisplayMetadata)

des options spécifiant le mode d'affichage des résultats de recherche contenant des données structurées.
objectType

string

Type d'objet du résultat de recherche.

ResultDisplayMetadata

Représentation JSON 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
Champs
objectTypeLabel

string

Libellé d'affichage de l'objet.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

Contenu des métalignes à afficher avec le résultat.

ResultDisplayMetadata.ResultDisplayLine

Ensemble de champs qui composent une ligne affichée

Représentation JSON 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Champs
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Afficher les champs pour les résultats de query.search

Représentation JSON 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
Champs
label

string

Libellé d'affichage de la propriété.
operatorName

string

Nom d'opérateur de la propriété.
property

object (NamedProperty)

Paire nom/valeur de la propriété.

ResultDebugInfo

Informations de débogage sur le résultat.

Représentation JSON 
{
  "formattedDebugInfo": string
}
Champs
formattedDebugInfo

string

Informations générales de débogage mises en forme pour être affichées.

StructuredResult

Résultats structurés renvoyés dans la requête de recherche

Représentation JSON 
{
  "person": {
    object (Person)
  }
}
Champs
person

object (Person)

Représentation d'une personne

SpellResult

Représentation JSON 
{
  "suggestedQuery": string
}
Champs
suggestedQuery

string

Suggestion orthographique de la requête.

FacetResult

Réponse d'attribut spécifique à la source

Représentation JSON 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
Champs
sourceName

string

Nom de la source pour laquelle les résultats d'attribut sont renvoyés. Ne sera pas vide.
objectType

string

Type d'objet pour lequel les résultats d'attribut sont renvoyés. Ce champ peut être vide.
operatorName

string

Nom de l'opérateur choisi pour l'attribut. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

Des objets FacetBucket pour les valeurs d'une réponse contenant au moins un résultat avec le filtre correspondant.

FacetBucket

Un bucket dans un attribut est l'unité d'opération de base. Un bucket peut comprendre une seule valeur OU une plage de valeurs contiguë, en fonction du type du champ concerné. FacetBucket n'est actuellement utilisé que pour renvoyer l'objet de réponse.

Représentation JSON 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
Champs
count

integer

Nombre de résultats correspondant à la valeur du bucket. Les nombres ne sont renvoyés que pour les recherches lorsque la précision des chiffres est garantie. Cloud Search ne garantit pas le nombre d'attributs pour une requête, et le nombre d'attributs peut n'apparaître que 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 des pourcentages de facettes ount qui sont toujours renvoyés.
percentage

integer

Pourcentage de résultats correspondant à la valeur du bucket. La valeur renvoyée est comprise entre (0-100) et est arrondie à un nombre entier si elle est fractionnaire. Si la valeur n'est pas explicitement renvoyée, elle représente une valeur en pourcentage qui arrondit la valeur à 0. Les pourcentages sont renvoyés pour toutes les recherches, mais il s'agit d'une estimation. Étant donné que les pourcentages sont toujours renvoyés, vous devez afficher des pourcentages plutôt que des nombres.
filter

object (Filter)

Filtre à transmettre dans la requête de recherche si le bucket correspondant est sélectionné.
value

object (Value)

ResponseDebugInfo

Informations de débogage sur la réponse.

Représentation JSON 
{
  "formattedDebugInfo": string
}
Champs
formattedDebugInfo

string

Informations générales de débogage mises en forme pour être affichées.

ErrorInfo

Informations d'erreur sur la réponse.

Représentation JSON 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
Champs
errorMessages[]

object (ErrorMessage)

ErrorMessage

Message d'erreur par réponse source.

Représentation JSON 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
Champs
source

object (Source)
errorMessage

string

ResultCounts

Informations sur le nombre de résultats

Représentation JSON 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
Champs
sourceResultCounts[]

object (SourceResultCount)

Informations sur le nombre de résultats pour chaque source.

SourceResultCount

Informations sur le nombre de résultats par source.

Représentation JSON 
{
  "source": {
    object (Source)
  },
  "hasMoreResults": boolean,

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Champs
source

object (Source)

Source à laquelle les informations de comptage des résultats sont associées.
hasMoreResults

boolean

Indique s'il y a plus de résultats de recherche pour cette source.

Champ d'union result_count.

result_count ne peut être qu'un des éléments suivants :
resultCountEstimate

string (int64 format)

Estimation du nombre de résultats pour cette source.
resultCountExact

string (int64 format)

Nombre exact de résultats pour cette source.