Method: spaces.messages.search

Recherche les messages dans Google Chat auxquels l'utilisateur appelant a accès. Renvoie une liste de messages correspondant aux critères de recherche.

Pour effectuer une recherche dans tous les espaces auxquels l'utilisateur a accès, définissez parent sur spaces/-. Si vous utilisez une autre valeur pour parent, une erreur INVALID_ARGUMENT se produit. Le champ name des messages renvoyés est renseigné avec le nom complet de la ressource, qui inclut le space spécifique dans lequel réside le message.

Cette API ne renvoie pas tous les types de messages. Les types de messages listés ci-dessous ne sont pas inclus dans la réponse. Utilisez messages.list pour lister tous les messages.

  • Messages privés visibles par l'utilisateur authentifié.
  • Messages publiés par des applications Chat dans des espaces ou des discussions de groupe.
  • Messages dans un message privé d'une application Chat.
  • Messages provenant d'utilisateurs bloqués
  • Messages dans les espaces que l'appelant a mis en sourdine.

Nécessite une authentification de l'utilisateur avec l'un des champs d'application d'autorisation suivants :

  • https://www.googleapis.com/auth/chat.messages.readonly
  • https://www.googleapis.com/auth/chat.messages

Requête HTTP

POST https://chat.googleapis.com/v1/{parent=spaces/*}/messages:search

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
parent

string

Obligatoire. Nom de ressource de l'espace dans lequel effectuer la recherche.

Pour effectuer une recherche dans tous les espaces auxquels l'utilisateur a accès, définissez ce champ sur spaces/-. Si vous utilisez une autre valeur pour parent, une erreur INVALID_ARGUMENT se produit.

Pour limiter la recherche à un ou plusieurs espaces, utilisez space.name ou space.display_name dans filter.

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation JSON 
{
  "filter": string,
  "pageSize": integer,
  "pageToken": string,
  "orderBy": string,
  "view": enum (SearchMessagesView)
}
Champs
filter

string

Obligatoire. Une requête de recherche.

La requête peut spécifier un ou plusieurs mots clés de recherche, qui sont utilisés pour filtrer les résultats.

Vous pouvez également filtrer les résultats à l'aide des champs de message suivants :

  • createTime : accepte un code temporel au format RFC-3339. Les opérateurs de comparaison acceptés sont < et >=.
  • sender.name : nom de ressource de l'expéditeur (users/{user}). Seul = est accepté. Vous pouvez utiliser l'adresse e-mail comme alias pour {user}. Par exemple, users/example@gmail.com, où example@gmail.com est l'adresse e-mail de l'utilisateur Google Chat.
  • space.name : nom de ressource de l'espace dans lequel le message est publié. (spaces/{space}). Ne prend en charge que =. Si ce filtre n'est pas défini, la recherche est effectuée dans tous les messages privés et espaces auxquels l'utilisateur a accès en tant que membre.
  • space.display_name : accepte l'opérateur : (contient) et filtre les espaces en fonction d'une correspondance partielle de leur nom à afficher. Les résultats sont limités aux cinq premiers espaces correspondants. Par exemple, space.display_name:Project recherche les messages dans les cinq premiers espaces dont le nom à afficher contient le mot "Projet".
  • attachment : accepte l'opérateur :* (a un ou plusieurs) pour vérifier la présence de pièces jointes. Si attachment:* est spécifié, seuls les messages comportant au moins une pièce jointe sont renvoyés.
  • annotations.user_mentions.user.name : nom de ressource de l'utilisateur mentionné (users/{user}). N'accepte que : (has). Par exemple, annotations.user_mentions.user.name:"users/1234567890" ne renvoie que les messages qui contiennent une mention de l'utilisateur spécifié. Vous pouvez également utiliser l'alias me pour filtrer les messages qui mentionnent l'utilisateur appelant, par exemple : annotations.user_mentions.user.name:users/me. Vous pouvez également utiliser l'adresse e-mail comme alias pour {user}, par exemple users/example@gmail.com.

Pour le filtrage avancé, les fonctions suivantes sont également disponibles :

  • has_link() : renvoie uniquement les messages dont le texte contient au moins un lien hypertexte.
  • is_unread() : filtre les messages qui ont été lus par l'utilisateur appelant.

Pour utiliser le filtre space.display_name, les identifiants de l'appelant doivent inclure l'un des champs d'application d'autorisation suivants :

  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.spaces

Pour utiliser le filtre is_unread(), les identifiants de l'appelant doivent inclure l'un des champs d'application d'autorisation suivants :

  • https://www.googleapis.com/auth/chat.users.readstate.readonly
  • https://www.googleapis.com/auth/chat.users.readstate

Seuls les opérateurs AND sont acceptés dans les différents champs. sender.name = "users/1234567890" AND is_unread() est un exemple valide. Le mot AND est facultatif et est sous-entendu s'il est omis. Par exemple, sender.name = "users/1234567890" is_unread() est valide et équivaut à l'exemple précédent. sender.name = "users/1234567890" OR is_unread() est un exemple non valide, car OR n'est pas accepté entre différents champs.

Dans le même champ :

  • createTime n'accepte que AND et ne peut être utilisé que pour représenter un intervalle, tel que createTime >= "2022-01-01T00:00:00+00:00" AND createTime < "2023-01-01T00:00:00+00:00".
  • sender.name n'accepte que l'opérateur OR. Exemple : sender.name = "users/1234567890" OR sender.name = "users/0987654321".
  • space.name n'accepte que l'opérateur OR. Exemple : space.name = "spaces/ABCDEFGH" OR space.name = "spaces/QWERTYUI".
  • space.display_name est compatible avec les opérateurs AND et OR, mais pas avec les deux à la fois. Par exemple, space.display_name:Project AND space.display_name:Tasks renvoie les messages qui se trouvent dans des espaces dont le nom à afficher contient à la fois Project et Tasks, tandis que space.display_name:Project OR space.display_name:Tasks renvoie les messages qui se trouvent dans des espaces dont le nom à afficher contient Project ou Tasks, ou les deux.
  • annotations.user_mentions.user.name est compatible avec les opérateurs AND et OR, mais pas avec les deux à la fois. Par exemple, annotations.user_mentions.user.name:"users/1234567890" AND annotations.user_mentions.user.name:"users/0987654321" ne renvoie que les messages qui mentionnent les deux utilisateurs, tandis que annotations.user_mentions.user.name:"users/1234567890" OR annotations.user_mentions.user.name:"users/0987654321" renvoie les messages qui mentionnent l'un ou l'autre des utilisateurs, ou les deux.

Des parenthèses sont nécessaires pour lever toute ambiguïté concernant la priorité des opérateurs lorsque vous combinez les opérateurs AND et OR dans la même requête. Exemple : (sender.name="users/me" OR sender.name="users/123456") AND is_unread(). Dans les autres cas, les parenthèses sont facultatives.

Voici des exemples de requêtes valides :

"Pending reports" AND createTime >= "2023-01-01T00:00:00Z"

sender.name = "users/example@gmail.com"

annotations.user_mentions.user.name:"users/0987654321"

attachment:* AND space.name = "spaces/ABCDEFGH"

tasks AND is_unread() AND sender.name = "users/1234567890"

"things to do" "urgent"

(sender.name = "users/1234567890")
AND (createTime < "2023-05-01T00:00:00Z")

tasks AND space.name = "spaces/ABCDEFGH" AND has_link()

"project one" is_unread()

space.display_name:Project tasks

La longueur maximale d'une requête est de 1 000 caractères.

Les requêtes non valides sont rejetées par le serveur avec une erreur INVALID_ARGUMENT.
pageSize

integer

Facultatif. Nombre maximal de résultats à renvoyer. Le service peut renvoyer un nombre inférieur à cette valeur.

Si aucune valeur n'est spécifiée, 25 éléments au maximum sont renvoyés.

La valeur maximale est de 100. Si vous utilisez une valeur supérieure à 100, elle est automatiquement remplacée par 100.
pageToken

string

Facultatif. Jeton reçu lors de l'appel précédent pour rechercher des messages. Fournissez ce paramètre pour récupérer la page suivante.

Lors de la pagination, tous les autres paramètres fournis doivent correspondre à l'appel ayant fourni le jeton de page. Transmettre différentes valeurs aux autres paramètres peut entraîner des résultats inattendus.
orderBy

string

Facultatif. Ordre de la liste des résultats.

Les attributs acceptés pour le tri sont les suivants :

  • createTime : trie les résultats par heure de création du message. Valeur par défaut.
  • relevance : trie les résultats par pertinence.

L'ordre par défaut est createTime desc. Une seule commande par requête (createTime ou relevance) est acceptée. Seul l'ordre décroissant (desc) est accepté. Il doit être spécifié après l'attribut d'ordre.
view

enum (SearchMessagesView)

Facultatif. Spécifie le type de vue des résultats de recherche à renvoyer. La valeur par défaut est SEARCH_MESSAGES_VIEW_BASIC.

Corps de la réponse

Message de réponse pour la recherche de messages.

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

Représentation JSON 
{
  "results": [
    {
      object (SearchMessageResult)
    }
  ],
  "nextPageToken": string
}
Champs
results[]

object (SearchMessageResult)

Liste des résultats de recherche correspondant à la requête.
nextPageToken

string

Jeton pouvant être utilisé pour récupérer la page suivante. Si ce champ est vide, il n'y a pas d'autres pages.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

  • https://www.googleapis.com/auth/chat.messages
  • https://www.googleapis.com/auth/chat.messages.readonly

Pour en savoir plus, consultez le guide d'autorisation.

SearchMessagesView

Types de vues compatibles avec les résultats de recherche partiels.

Enums
SEARCH_MESSAGES_VIEW_UNSPECIFIED Valeur par défaut / non définie. L'API affichera par défaut la vue BASIC.
SEARCH_MESSAGES_VIEW_BASIC Inclut uniquement les messages correspondants dans les résultats, mais aucune métadonnée supplémentaire. Il s'agit de la valeur par défaut.
SEARCH_MESSAGES_VIEW_FULL Inclut tous les éléments des résultats : les messages correspondants et les métadonnées supplémentaires.

SearchMessageResult

Élément de résultat unique d'une recherche de message.

Représentation JSON 
{
  "message": {
    object (Message)
  },
  "spaceMuteSetting": enum (MuteSetting),
  "read": boolean
}
Champs
message

object (Message)

Le message correspondant.
spaceMuteSetting

enum (MuteSetting)

Paramètre de désactivation du son de l'utilisateur qui appelle pour l'espace dans lequel le message est publié. L'application d'appelant peut utiliser ces informations pour décider comment traiter le message selon que l'espace est mis en sourdine ou non pour l'utilisateur.

N'est renvoyé que si la vue de la requête est SEARCH_MESSAGES_VIEW_FULL et que les identifiants de l'appelant incluent le champ d'application de l'autorisation suivant :

  • https://www.googleapis.com/auth/chat.users.spacesettings
read

boolean

Indique si le message correspondant a été lu par l'utilisateur appelant.

Cet élément n'est renvoyé que si la vue de la requête est SEARCH_MESSAGES_VIEW_FULL et que les identifiants de l'appelant incluent l'un des niveaux d'autorisation suivants :

  • https://www.googleapis.com/auth/chat.users.readstate.readonly
  • https://www.googleapis.com/auth/chat.users.readstate