Use el parámetro de consulta de búsqueda para coincidir con un criterio de búsqueda

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 consulta $search varía según la entidad, ya que algunas, como los recursos de Azure AD que derivan de directoryObject, solo soportan $search con las consultas avanzadas.

Nota

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

Uso de $search en colecciones de mensajes

Puede buscar mensajes con un valor en las propiedades de los mensajes específicos. Los resultados de la búsqueda se ordenan por la fecha y la hora en que se ha enviado el mensaje. Una solicitud $search devuelve hasta 250 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 Verdadero si un mensaje contiene datos adjuntos que no son un archivo adjunto en línea, falso en caso 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 especificados como una dirección SMTP, alias o nombre para mostrar. 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 de 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 usar la API de contactos de Microsoft Graph para recuperar los contactos más relevantes para un usuario. La relevancia viene determinada por las relaciones empresariales y los patrones de comunicación y colaboración del usuario. La API de contactos admite el parámetro de consulta $search. Una solicitud $search devuelve hasta 250 resultados.

Las búsquedas de contactos se realizan en las propiedades displayName y emailAddress del recurso person.

La solicitud siguiente busca una persona llamada "Irene McGowen" en las propiedades displayName y emailAddress de todos los miembros de la colección people del usuario que ha iniciado sesión. Dado que existe una persona llamada "Irene McGowan" relevante para el usuario que ha iniciado sesión, se devuelve la información de "Irene McGowan".

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.onmicrosoft.com",
           "imAddress": "sip:irenem@contoso.onmicrosoft.com",
           "scoredEmailAddresses": [
               {
                   "address": "irenem@contoso.onmicrosoft.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 Azure AD y sus relaciones que derivan de directoryObject admiten el $search parámetro de consulta solo en las consultas avanzadas. La búsqueda usa un enfoque de tokenización que funciona extrayendo palabras de su cadena de entrada y salida, usando espacios, números, diferentes mayúsculas o minúsculas y símbolos para separar las palabras, como se muestra a continuación:

  • Espacios:hello world => hello``world,
  • Cambios entre mayúscula y minúscula⁽¹⁾: HelloWorld o helloWORLD => hello, world
  • Símbolos⁽²⁾: hello.world => hello, ., world, helloworld
  • Números: hello123world => hello, 123, world

⁽¹⁾ Actualmente, la tokenización solo funciona cuando los caracteres cambian de minúsculas a mayúsculas, por lo que HELLOworld se considera un único token: helloworld. HelloWORld son dos tokens: hello y world. ⁽²⁾ La lógica de la tokenización también combina palabras que se separan mediante símbolos; por ejemplo, la búsqueda de helloworld dará como resultado hello-world y hello.world.

Nota: después de la tokenización, los tokens se hacen coincidir independientemente de la grafía original y se hacen coincidir en cualquier orden.

La compatibilidad con la búsqueda por tokens solo funciona en los campos displayName y description. Se puede poner cualquier campo de tipo cadena en los campos $search que no sean displayName y description de forma predeterminada a $filter startswith. Por ejemplo:

https://graph.microsoft.com/v1.0/groups/?$search="displayName:OneVideo"

Busca todos los grupos con nombres para mostrar que sean similares a "OneVideo". $search también puede usarse conjuntamente con $filter. Por ejemplo:

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

Busca todos los grupos con correo habilitado con nombres para mostrar que sean similares a "OneVideo". Los resultados se restringen en función de una conjunción lógica ("Y") de $filter y la consulta completa en $search. El texto de búsqueda se ajusta por token en función de las mayúsculas y minúsculas, pero las coincidencias se ejecutan sin distinguir entre mayúsculas y minúsculas. Por ejemplo, "OneVideo" se divide en dos tokens de entrada ("uno" y "vídeo"), pero coincide con propiedades que no distinguen entre mayúsculas y minúsculas.

La sintaxis de la búsqueda sigue estas reglas:

  • Formato genérico: $search="clause1" [Y | O] "[clauseX]".
  • Se admite cualquier número de cláusulas. También se admite paréntesis para la prioridad.
  • La sintaxis para cada cláusula es "<property>:<text to search>".
  • El nombre de la propiedad debe especificarse en la cláusula. Las propiedades que se pueden usar en $filter también se pueden usar dentro de $search. Dependiendo de la propiedad, el comportamiento de búsqueda es "Buscar" o "StartsWith", si la búsqueda no es compatible con la propiedad.
  • La parte completa de la cláusula debe incluirse entre comillas dobles.
  • El operador lógico "Y" o "O" debe escribirse fuera de las comillas dobles. Deben escribirse en mayúsculas.
  • Dado que toda la parte de la cláusula debe colocarse entre comillas dobles, si contiene comillas dobles y barra invertida, debe escaparse con una barra invertida. No es necesario escapar ningún otro carácter.

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"

Tanto las entradas de cadena que se proporcionan en $search, como las propiedades que se pueden buscar, se dividen en partes por espacios, uso diferente de mayúsculas y minúsculas y tipos de caracteres (números y caracteres especiales).

Vea también