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, comme Gmail ou Google Drive, ou de données que vous avez indexées à partir d'un tiers.

Remarque : Cette API nécessite un compte utilisateur final standard pour s'exécuter. Un compte de service ne peut pas effectuer directement de requêtes d'API de requête. 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 la recherche à l'aide d'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 de 50 lorsque des résultats au-delà de 2 000 sont demandés.
start

integer

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

object (DataSourceRestriction)

Sources à utiliser pour les requêtes. Si aucune 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)

Options de tri des résultats de recherche
queryInterpretationOptions

object (QueryInterpretationOptions)

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

object (ContextAttribute)

Attributs de contexte pour la requête qui seront utilisés pour ajuster le classement des résultats de recherche. Le nombre maximal d'éléments est de 10.

Corps de la réponse

Réponse de l'API Search. ID SUIVANT : 19

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

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 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 la taille de page.
spellResults[]

object (SpellResult)

Orthographe suggérée pour la requête.
facetResults[]

object (FacetResult)

Résultats d'attributs répétés.
hasMoreResults

boolean

Indique s'il existe d'autres résultats de recherche correspondant à la requête.
debugInfo

object (ResponseDebugInfo)

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

object (ErrorInfo)

Informations sur les erreurs concernant la réponse.
resultCounts

object (ResultCounts)

Informations détaillé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. Omitted if predefined sources are included in the set of data sources queried. Dans les cas suivants, le nombre de résultats peut être renvoyé sous forme d'estimation plutôt que de valeur exacte :

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

  • Lorsque le nombre de LCA de résultats de recherche uniques à évaluer est trop important pour être calculé dans un délai raisonnable.

Dans le cas rare où le système ne parvient pas à effectuer une recherche 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)

Nombre de résultats estimé pour cette requête.
resultCountExact

string (int64 format)

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 d'autorisation.

QueryInterpretationOptions

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

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

boolean

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

boolean

Activez ce flag pour désactiver toutes les optimisations internes, comme l'interprétation en langage naturel des requêtes, la récupération de résultats supplémentaires et l'utilisation de synonymes, y compris personnalisés. L'interprétation du langage naturel sera désactivée si l'un des deux indicateurs est défini sur "true".
disableSupplementalResults

boolean

Utilisez cet indicateur pour désactiver les résultats supplémentaires pour une requête. Le paramètre de résultats supplémentaires choisi au niveau SearchApplication prévaudra s'il est défini sur "True".

QueryInterpretation

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

string

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

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

Raison de l'interprétation de la requête. Ce champ ne sera pas défini sur "UNSPECIFIED" si le type d'interprétation n'est pas "NONE".
interpretedQueryActualResultCount

integer

Nombre réel de résultats renvoyés par la requête interprétée.
interpretedQueryEstimatedResultCount

string (int64 format)

Nombre estimé de résultats renvoyés par la requête interprétée.

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 fusionnés avec 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 "Raison" ci-dessous.
REPLACE Les résultats de la requête d'origine sont remplacés. La raison pour laquelle les résultats de la requête d'origine ont été remplacés est indiquée dans le champ "Raison" 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 recherche.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY La similarité entre les termes de la requête et ceux du document est utilisée pour élargir sélectivement la requête afin de récupérer des résultats de recherche supplémentaires, car aucun résultat suffisant n'a été trouvé pour la requête de l'utilisateur. La requête interprétée sera vide dans ce cas.

SearchResult

Résultats contenant des informations indexées pour un document. ID suivant : 16

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'élément 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 regroupée, fournissez la liste des résultats regroupés. Il n'y aura qu'un seul niveau de résultats groupés. Si la source actuelle n'est pas activée pour le clustering, ce champ sera vide.
debugInfo

object (ResultDebugInfo)

Informations de débogage concernant ce résultat de recherche.

Extrait

Extrait du résultat de recherche, qui résume le contenu de la page correspondante.

Représentation JSON 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
Champs
snippet

string

Extrait du document. Peut contenir un caractère HTML échappé qui doit être déséchappé avant le rendu.
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 du match dans l'extrait.

Métadonnées

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)

Nom de la source du résultat, comme 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)

Heure de création de ce document ou objet dans le résultat de recherche.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

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

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
fields[]

object (NamedProperty)

Champs indexés dans les données structurées, renvoyés sous forme de propriété nommée générique.
displayOptions

object (ResultDisplayMetadata)

Options qui spécifient comment afficher un résultat de recherche de 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é à afficher pour 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

Champs d'affichage pour les résultats de query.search

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

string

Libellé à afficher pour la propriété.
operatorName

string

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

object (NamedProperty)

Paire nom/valeur pour la propriété.

ResultDebugInfo

Informations de débogage sur le résultat.

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

string

Informations de débogage générales mises en forme pour l'affichage.

StructuredResult

Résultats structurés renvoyés dans le cadre d'une requête de recherche.

Représentation JSON 
{

  // Union field structured_result can be only one of the following:
  "person": {
    object (Person)
  }
  // End of list of possible types for union field structured_result.
}
Champs

Champ d'union structured_result.

structured_result ne peut être qu'un des éléments suivants :
person

object (Person)

Représentation d'une personne

SpellResult

Représentation JSON 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
Champs
suggestedQuery

string

Orthographe suggérée de la requête.
suggestionType

enum (SpellResult.SuggestionType)

suggestion déclenchée pour la requête actuelle.
suggestedQueryHtml

object (SafeHtmlProto)

Code HTML nettoyé représentant la requête corrigée par le correcteur orthographique, qui peut être utilisé dans l'UI. Il comporte généralement des balises spécifiques à la langue pour marquer les parties de la requête qui ont été vérifiées orthographiquement.

SpellResult.SuggestionType

Type de suggestion déclenché pour la requête.

Enums
SUGGESTION_TYPE_UNSPECIFIED Type de vérification orthographique par défaut
NON_EMPTY_RESULTS_SPELL_SUGGESTION Modification de la suggestion orthographique sans aucun résultat. Les résultats sont toujours affichés pour la requête d'origine (qui a des résultats non nuls), avec une suggestion d'orthographe qui aurait des résultats.
ZERO_RESULTS_FULL_PAGE_REPLACEMENT Suggestion orthographique déclenchée lorsque la requête d'origine ne renvoie aucun résultat. Lorsque la requête d'origine ne renvoie aucun résultat et que la suggestion orthographique en renvoie, nous affichons les résultats pour la requête corrigée.

SafeHtmlProto

IMPORTANT : Il est dangereux d'accepter ce message provenant d'une source non fiable, car il est très facile pour un pirate informatique de falsifier des messages sérialisés qui ne respectent pas le contrat de sécurité du type. Par exemple, il pourrait contenir un script contrôlé par un pirate informatique. Un système qui reçoit un SafeHtmlProto fait implicitement confiance au producteur du SafeHtmlProto. Il est donc généralement sûr de renvoyer ce message dans les réponses RPC, mais généralement dangereux de l'accepter dans les requêtes RPC.

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

string

IMPORTANT : Ne définissez ni ne lisez jamais ce champ, même à partir de tests, car il est privé. Consultez la documentation en haut du fichier .proto pour connaître les packages de langage de programmation permettant de créer ou de lire ce message.

FacetResult

Réponse de facette 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. Ce champ ne sera pas vide.
objectType

string

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

string

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

object (FacetBucket)

FacetBuckets pour les valeurs de la réponse contenant au moins un résultat avec le filtre correspondant.

FacetBucket

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

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

  // Union field bucket_value can be only one of the following:
  "value": {
    object (Value)
  }
  // End of list of possible types for union field bucket_value.
}
Champs
count

integer

Nombre de résultats correspondant à la valeur du bucket. Les nombres ne sont renvoyés pour les recherches que lorsque la précision du nombre est assurée. Cloud Search ne garantit pas le nombre de facettes pour les requêtes. Il est possible que le nombre de facettes ne soit présent que de manière intermittente, même pour des requêtes identiques. Ne créez pas de dépendances sur l'existence du nombre de facettes. Utilisez plutôt les pourcentages de nombre de facettes, qui sont toujours renvoyés.
percentage

integer

Pourcentage de résultats correspondant à la valeur du bucket. La valeur renvoyée est comprise entre 0 et 100 (exclus) et est arrondie à l'entier inférieur si elle est fractionnaire. Si la valeur n'est pas explicitement renvoyée, elle représente un pourcentage arrondi à 0. Des 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 les afficher plutôt que les nombres.
filter

object (Filter)

Filtre à transmettre dans la requête de recherche si le bucket correspondant est sélectionné.
Champ d'union bucket_value. La plage ou la valeur du bucket facetté bucket_value ne peut être que l'une des suivantes :
value

object (Value)

ResponseDebugInfo

Informations de débogage sur la réponse.

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

string

Informations de débogage générales mises en forme pour l'affichage.

Information sur l'erreur

Informations sur les erreurs concernant la réponse.

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

object (ErrorMessage)

ErrorMessage

Message d'erreur par réponse de 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 avec des résultats.

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 sur le nombre de résultats sont associées.
hasMoreResults

boolean

Indique s'il existe d'autres 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)

Nombre de résultats estimés pour cette source.
resultCountExact

string (int64 format)

Nombre exact de résultats pour cette source.