Uso del parámetro de consulta $search

Además de otros parámetros de consulta de OData, Microsoft Graph admite el parámetro de consulta $search para restringir los resultados de una solicitud para que coincidan con un criterio de búsqueda.

La compatibilidad con el parámetro de $search consulta varía según la entidad, y algunas, como los recursos de Microsoft Entra que derivan de directoryObject, $search admiten solo en consultas avanzadas. En este artículo se describe la sintaxis y el comportamiento de búsqueda en las tres áreas principales siguientes:

Uso de $search en colecciones de mensajes

Puede buscar mensajes en función de un valor en propiedades de mensaje específicas. Los resultados de la búsqueda se ordenan por la fecha y la hora en que se ha enviado el mensaje. Una $search solicitud devuelve hasta 1000 resultados.

Si realiza una búsqueda en mensajes y especifica solo un valor sin las propiedades de mensaje específicas, la búsqueda se lleva a cabo con las propiedades de búsqueda predeterminadas de from, subject y body.

En el ejemplo siguiente, se devuelven todos los mensajes del buzón del usuario que ha iniciado sesión que contienen la palabra "pizza" en cualquiera de las tres propiedades de búsqueda predeterminadas:

GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"

Como alternativa, puede buscar mensajes especificando los nombres de propiedades de mensaje en la tabla siguiente, que se reconocen por la sintaxis de la consulta de palabras clave (KQL). Estos nombres de propiedad corresponden a las propiedades que se definen en la entidad de mensaje de Microsoft Graph. Outlook y otras aplicaciones de Microsoft 365, como SharePoint, admiten la sintaxis KQL, proporciona la comodidad de un dominio de detección común para los almacenes de datos.

Propiedades del correo electrónico que permiten búsquedas Descripción Ejemplo
attachment Los nombres de los archivos adjuntos a un mensaje de correo electrónico. GET../me/messages?$search="attachment:api-catalog.md"
bcc El campo bcc de un mensaje de correo electrónico, especificado como una dirección SMTP, alias o nombre para mostrar. GET../me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients
body El cuerpo de un mensaje de correo electrónico. GET../me/messages?$search="body:excitement"
cc El campo cc de un mensaje de correo electrónico, especificado como una dirección SMTP, alias o nombre para mostrar. GET../me/messages?$search="cc:danas"&$select=subject,ccRecipients
from El remitente de un mensaje de correo electrónico, especificado como una dirección SMTP, alias o nombre para mostrar. GET../me/messages?$search="from:randiw"&$select=subject,from
hasAttachment true si un mensaje de correo electrónico contiene datos adjuntos que no son datos adjuntos insertados, false de lo contrario. GET../me/messages?$search="hasAttachments:true"
importance La importancia de un mensaje de correo electrónico, que un remitente puede especificar al enviar un mensaje. Los valores posibles sonlow, medium o high. GET../me/messages?$search="importance:high"&$select=subject,importance
kind El tipo de mensaje. Los valores posibles son contacts, docs, email, faxes, im, journals, meetings, notes, posts, rssfeeds, tasks o voicemail. GET../me/messages?$search="kind:voicemail"
participants Los campos from, to, cc y bcc de un mensaje de correo electrónico, especificados como una dirección SMTP, alias o nombre para mostrar. GET../me/messages?$search="participants:danas"
received La fecha en la que un destinatario recibió un mensaje de correo electrónico. GET../me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime
recipients Los campos to, cc y bcc de un mensaje de correo electrónico, especificados como una dirección SMTP, un nombre para mostrar o un alias. GET../me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients
sent La fecha en la que un remitente envió un mensaje de correo electrónico. GET../me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime
size El tamaño de un elemento, en bytes. GET../me/messages?$search="size:1..500000"
subject El texto en la línea de asunto de un mensaje de correo electrónico. GET../me/messages?$search="subject:has"&$select=subject
to El campo to de un mensaje de correo electrónico, especificado como una dirección SMTP, alias o nombre para mostrar. GET.../me/messages?$search="to:randiw"&$select=subject,toRecipients

Para obtener más información sobre las propiedades de correo electrónico que permiten búsquedas, la sintaxis KQL, los operadores compatibles y las sugerencias de búsqueda, vea los artículos siguientes:

Uso de $search en colecciones de usuarios

Puede aplicar $search a las propiedades displayName y emailAddresses del recurso person . La solicitud devuelve hasta 250 resultados de forma predeterminada.

La siguiente solicitud busca "Irene McGowan" en los objetos de persona de colección del usuario que ha iniciado sesión. Microsoft Graph limita la búsqueda a las propiedades displayName o emailAddresses .

GET https://graph.microsoft.com/v1.0/me/people/?$search="Irene McGowen"

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
       {
           "id": "C0BD1BA1-A84E-4796-9C65-F8A0293741D1",
           "displayName": "Irene McGowan",
           "givenName": "Irene",
           "surname": "McGowan",
           "birthday": "",
           "personNotes": "",
           "isFavorite": false,
           "jobTitle": "Auditor",
           "companyName": null,
           "yomiCompany": "",
           "department": "Finance",
           "officeLocation": "12/1110",
           "profession": "",
           "userPrincipalName": "irenem@contoso.com",
           "imAddress": "sip:irenem@contoso.com",
           "scoredEmailAddresses": [
               {
                   "address": "irenem@contoso.com",
                   "relevanceScore": -16.446060612802224
               }
           ],
           "phones": [
               {
                   "type": "Business",
                   "number": "+1 412 555 0109"
               }
           ],
           "postalAddresses": [],
           "websites": [],
           "personType": {
               "class": "Person",
               "subclass": "OrganizationUser"
           }
       }
   ]
}

Para más información sobre la API de contactos, vea Obtener información sobre contactos relevantes.

Usar $search en colecciones de objetos de directorio

Los recursos de Microsoft Entra ID y sus relaciones que derivan de directoryObject admiten el parámetro de $search consulta solo en consultas avanzadas.

Nota:

El parámetro de consulta $search no está disponible actualmente en los espacios empresariales Azure AD B2C.

Hay un problema conocido relacionado con $search los objetos de directorio para los valores que contienen un símbolo de y comercial (&).

La implementación de búsqueda no admite la lógica "contains". En su lugar, utiliza un enfoque de tokenización que funciona extrayendo palabras del valor de la propiedad y de la cadena de búsqueda usando espacios, números, mayúsculas y minúsculas diferentes, y símbolos, tal y como se muestra en los siguientes ejemplos:

  • Espacios: hello world =>hello, world
  • Mayúsculas y minúsculas diferentes1⁾: HelloWorld o helloWORLD =>hello, world
  • Símbolos2⁾: hello.world =>hello, ., , worldhelloworld
  • Números: hello123world =>hello, 123, world

1⁾ Para mayúsculas y minúsculas diferentes, la tokenización solo funciona actualmente cuando el uso de mayúsculas cambia de minúsculas a mayúsculas, por lo que HELLOworld se considera un solo token: helloworldy HelloWORld es dos tokens: hello, world.

2⁾ La lógica de tokenización también combina palabras separadas solo por símbolos; por ejemplo, la búsqueda de helloworld búsquedas hello-world y hello.world.

Después de la tokenización, los tokens coinciden independientemente del uso de mayúsculas y minúsculas originales y coinciden en cualquier orden. Por ejemplo, displayName 李四(David Li) coincide con cadenas de búsqueda como 李四(David Li), 李四, , DavidLi, David), , (李四, Li 李. Un cambio en el alfabeto, como de latín a cirílico o chino, no crea un nuevo token. Por ejemplo, displayName 蓝色group coincide con las 蓝色group cadenas y 蓝色 de búsqueda, pero no group; mientras displayName group蓝色 coincide con las group蓝色 cadenas y group de búsqueda, pero no 蓝色 con o .

La compatibilidad con la búsqueda por tokens solo funciona en los campos displayName y description. Cualquier campo de tipo String se puede colocar en $search; campos distintos de displayName y description predeterminados para $filterstartswith el comportamiento.

Por ejemplo:

GET https://graph.microsoft.com/v1.0/groups/?$search="displayName:OneVideo" OR "mail:onevideo"
ConsistencyLevel: eventual

Esto busca todos los grupos con nombres para mostrar que tienen one tokens y video , o correo a partir de onevideo.

$search se puede usar junto con $filter:

GET https://graph.microsoft.com/v1.0/groups/?$filter=mailEnabled eq true&$search="displayName:OneVideo"
ConsistencyLevel: eventual

Busca todos los grupos con correo habilitado con nombres para mostrar que sean similares a "OneVideo". Los resultados están restringidos en función de una conjunción lógica ("AND") de $filter y de toda la consulta en .$search

La sintaxis de la búsqueda sigue estas reglas:

  • Formato genérico: $search="clause1" [AND | OR] "\clauseX".
  • Se admite cualquier número de cláusulas. También se admite paréntesis para la prioridad.
  • La sintaxis de cada cláusula es: "<property>:<text to search>".
    • El nombre de la propiedad debe especificarse en la cláusula.
    • La cláusula completa debe declararse entre comillas dobles. Si contiene comillas dobles o barra diagonal inversa, se debe escapar con una barra diagonal inversa. Todos los demás caracteres especiales deben tener la URL codificada.
  • Los operadores lógicos AND y OR deben colocarse fuera de comillas dobles y deben estar en mayúsculas.
  • La búsqueda verdadera solo es compatible con las propiedades displayName y description ; pero cualquier propiedad que se pueda usar en $filter también se puede usar dentro de $search. En función de la propiedad , el comportamiento de búsqueda es "search" o $filter con "startsWith" si la búsqueda no se admite en la propiedad .
  • Tanto las entradas de cadena que se proporcionan en $searchcomo las propiedades que se pueden buscar se dividen en partes por espacios, mayúsculas y minúsculas diferentes y tipos de caracteres (números y caracteres especiales).

En la tabla siguiente se muestran algunos ejemplos.

Clase de objeto Description Ejemplo
Usuario Nombre del usuario para mostrar de la libreta de direcciones. GET../users?$search="displayName:Guthr"
Usuario Nombre o correo del usuario para mostrar de la libreta de direcciones. GET../users?$search="displayName:Guthr" OR "mail:Guthr"
Grupo Nombre o descripción del grupo para mostrar de la libreta de direcciones. GET../groups?$search="description:One" AND ("displayName:Video" OR "displayName:Drive"
Grupo Nombre de la libreta de direcciones para mostrar en un grupo con correo habilitado. GET../groups?$filter=mailEnabled eq true&$search="displayName:OneVideo"