Method: spaces.messages.search

Busca mensajes en Google Chat a los que tiene acceso el usuario que llama. Devuelve una lista de mensajes que coinciden con los criterios de búsqueda.

Para buscar en todos los espacios a los que tiene acceso el usuario, establece parent en spaces/-. Si usas cualquier otro valor para parent, se producirá un error de INVALID_ARGUMENT. Los mensajes devueltos tienen su campo name completado con el nombre completo del recurso, que incluye el space específico en el que reside el mensaje.

Esta API no devuelve todos los tipos de mensajes. Los tipos de mensajes que se indican a continuación no se incluyen en la respuesta. Usa messages.list para enumerar todos los mensajes.

  • Son los mensajes privados que son visibles para el usuario autenticado.
  • Son los mensajes que publican las apps de Chat en espacios o chats grupales.
  • Mensajes en un MD de una app de Chat
  • Mensajes de usuarios bloqueados
  • Mensajes en espacios que el llamante silenció

Requiere autenticación del usuario con uno de los siguientes alcances de autorización:

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

Solicitud HTTP

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

La URL usa la sintaxis de la transcodificación gRPC.

Parámetros de ruta

Parámetros
parent

string

Obligatorio. Es el nombre del recurso del espacio en el que se realizará la búsqueda.

Para buscar en todos los espacios a los que tiene acceso el usuario, establece este campo en spaces/-. Si usas cualquier otro valor para parent, se producirá un error de INVALID_ARGUMENT.

Para limitar la búsqueda a uno o más espacios, usa space.name o space.display_name en filter.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Representación JSON 
{
  "filter": string,
  "pageSize": integer,
  "pageToken": string,
  "orderBy": string,
  "view": enum (SearchMessagesView)
}
Campos
filter

string

Obligatorio. Es una búsqueda.

La búsqueda puede especificar una o más palabras clave de búsqueda, que se usan para filtrar los resultados.

También puedes filtrar los resultados con los siguientes campos de mensaje:

  • createTime: Acepta una marca de tiempo en formato RFC-3339. Los operadores de comparación admitidos son: < y >=.
  • sender.name: Es el nombre del recurso del remitente (users/{user}). Solo admite =. Puedes usar el correo electrónico como alias de {user}. Por ejemplo, users/example@gmail.com, en el que example@gmail.com es el correo electrónico del usuario de Google Chat.
  • space.name: Es el nombre del recurso del espacio en el que se publica el mensaje. (spaces/{space}). Solo admite =. Si no se establece este filtro, la búsqueda se realizará en todos los mensajes directos y espacios a los que el usuario tenga acceso como miembro del espacio.
  • space.display_name: Admite el operador : (tiene) y filtra los espacios en función de una coincidencia parcial de su nombre visible. Los resultados se limitan a las cinco coincidencias de espacio más relevantes. Por ejemplo, space.display_name:Project busca mensajes en los cinco primeros espacios que contienen la palabra "Proyecto" en sus nombres visibles.
  • attachment: Admite el operador :* (tiene alguno) para verificar la presencia de archivos adjuntos. Si se especifica attachment:*, solo se devuelven los mensajes que tienen al menos un adjunto.
  • annotations.user_mentions.user.name: Es el nombre del recurso del usuario mencionado (users/{user}). Solo admite : (tiene). Por ejemplo, annotations.user_mentions.user.name:"users/1234567890" solo devuelve mensajes que contienen una mención al usuario especificado. Como alternativa, se puede usar el alias me para filtrar los mensajes que mencionan al usuario que llama, por ejemplo: annotations.user_mentions.user.name:users/me. También puedes usar el correo electrónico como alias para {user}, por ejemplo, users/example@gmail.com.

Para el filtrado avanzado, también están disponibles las siguientes funciones:

  • has_link(): Devuelve solo los mensajes que tienen al menos un hipervínculo en el texto del mensaje.
  • is_unread(): Filtra los mensajes que leyó el usuario que llama.

Para usar el filtro space.display_name, las credenciales de llamada deben incluir uno de los siguientes alcances de autorización:

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

Para usar el filtro is_unread(), las credenciales de llamada deben incluir uno de los siguientes alcances de autorización:

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

En diferentes campos, solo se admiten los operadores AND. Un ejemplo válido es sender.name = "users/1234567890" AND is_unread(). La palabra AND es opcional y se da por implicada si se omite. Por ejemplo, sender.name = "users/1234567890" is_unread() es válido y equivale al ejemplo anterior. Un ejemplo no válido es sender.name = "users/1234567890" OR is_unread() porque OR no se admite entre diferentes campos.

Entre los mismos campos:

  • createTime solo admite AND y solo se puede usar para representar un intervalo, como createTime >= "2022-01-01T00:00:00+00:00" AND createTime < "2023-01-01T00:00:00+00:00".
  • sender.name solo admite el operador OR, por ejemplo: sender.name = "users/1234567890" OR sender.name = "users/0987654321".
  • space.name solo admite el operador OR, por ejemplo: space.name = "spaces/ABCDEFGH" OR space.name = "spaces/QWERTYUI".
  • space.display_name admite los operadores AND y OR, pero no una combinación de ambos. Por ejemplo, space.display_name:Project AND space.display_name:Tasks devuelve mensajes que se encuentran en espacios con nombres visibles que contienen Project y Tasks, mientras que space.display_name:Project OR space.display_name:Tasks devuelve mensajes que se encuentran en espacios con nombres visibles que contienen Project o Tasks o ambos.
  • annotations.user_mentions.user.name admite los operadores AND y OR, pero no una combinación de ambos. Por ejemplo, annotations.user_mentions.user.name:"users/1234567890" AND annotations.user_mentions.user.name:"users/0987654321" devuelve solo los mensajes que mencionan a ambos usuarios, mientras que annotations.user_mentions.user.name:"users/1234567890" OR annotations.user_mentions.user.name:"users/0987654321" devuelve los mensajes que mencionan a cualquiera de los usuarios o a ambos.

Se requieren paréntesis para desambiguar la precedencia de los operadores cuando se combinan los operadores AND y OR en la misma consulta. Por ejemplo: (sender.name="users/me" OR sender.name="users/123456") AND is_unread(). De lo contrario, los paréntesis son opcionales.

Las siguientes consultas de ejemplo son válidas:

"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 longitud máxima de la búsqueda es de 1,000 caracteres.

El servidor rechaza las consultas no válidas con un error INVALID_ARGUMENT.
pageSize

integer

Opcional. La cantidad máxima de resultados que se mostrarán. El servicio puede mostrar menos que este valor.

Si no se especifica, se devolverán, como máximo, 25.

El valor máximo es 100. Si usas un valor superior a 100, se cambiará automáticamente a 100.
pageToken

string

Opcional. Es un token que se recibió de la llamada anterior a search messages. Proporciona este parámetro para recuperar la página siguiente.

Cuando se realiza la paginación, todos los demás parámetros proporcionados deben coincidir con la llamada que proporcionó el token de página. Si pasas valores diferentes a los otros parámetros, es posible que obtengas resultados inesperados.
orderBy

string

Opcional. Orden en que se muestra la lista de resultados.

Los atributos admitidos para ordenar son los siguientes:

  • createTime: Ordena los resultados según la hora de creación del mensaje. Valor predeterminado
  • relevance: Ordena los resultados por relevancia.

El orden predeterminado es createTime desc. Solo se admite un orden por consulta (createTime o relevance). Solo se admite el orden descendente (desc), y se debe especificar después del atributo de orden.
view

enum (SearchMessagesView)

Opcional. Especifica qué tipo de vista de resultados de la búsqueda se debe devolver. El valor predeterminado es SEARCH_MESSAGES_VIEW_BASIC.

Cuerpo de la respuesta

Es el mensaje de respuesta para la búsqueda de mensajes.

Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

Representación JSON 
{
  "results": [
    {
      object (SearchMessageResult)
    }
  ],
  "nextPageToken": string
}
Campos
results[]

object (SearchMessageResult)

Es la lista de resultados de la búsqueda que coincidieron con la consulta.
nextPageToken

string

Es un token que se puede usar para recuperar la página siguiente. Si este campo está vacío, no hay páginas siguientes.

Permisos de autorización

Se necesita uno de los siguientes permisos de OAuth:

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

Para obtener más información, consulta la Guía de autorización.

SearchMessagesView

Son los tipos de vistas que se admiten para los resultados de la búsqueda parcial.

Enums
SEARCH_MESSAGES_VIEW_UNSPECIFIED Es el valor predeterminado o no establecido. La API usará la vista BASIC de forma predeterminada.
SEARCH_MESSAGES_VIEW_BASIC Solo incluye los mensajes coincidentes en los resultados, pero no metadatos adicionales. Este es el valor predeterminado.
SEARCH_MESSAGES_VIEW_FULL Incluye todo en los resultados: los mensajes que coinciden y los metadatos adicionales.

SearchMessageResult

Es un solo elemento de resultado de una búsqueda de mensajes.

Representación JSON 
{
  "message": {
    object (Message)
  },
  "spaceMuteSetting": enum (MuteSetting),
  "read": boolean
}
Campos
message

object (Message)

Es el mensaje coincidente.
spaceMuteSetting

enum (MuteSetting)

Es el parámetro de configuración de silencio del usuario que llama para el espacio en el que se publica el mensaje. La app de llamada puede usar esta información para decidir cómo procesar el mensaje según si el espacio está silenciado para el usuario o no.

Solo se devuelve si la vista de la solicitud es SEARCH_MESSAGES_VIEW_FULL y las credenciales de llamada incluyen el siguiente alcance de autorización:

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

boolean

Indica si el usuario que llama leyó el mensaje coincidente.

Solo se devuelve si la vista de la solicitud es SEARCH_MESSAGES_VIEW_FULL y las credenciales de llamada incluyen uno de los siguientes alcances de autorización:

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