Uso del parámetro de consulta $search

  • Artículo

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 varía según la $search entidad, con algunos, como Microsoft Entra recursos que derivan de directoryObject, que solo admiten $search 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 la codificación desímboloss (&) símbolos en $search expresiones en el v1.0 punto de conexión. Para obtener más información sobre el problema y la solución alternativa recomendada, vea Problema conocido: $search para los objetos de directorio produce un error en los caracteres de & y de amperar codificados.

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 solicitud $search devuelve hasta 1 000 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 camposto, 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 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 usar la API de contactos de Microsoft Graph para recuperar los contactos más relevantes para un usuario. La relevancia viene determinada por los patrones de comunicación y colaboración del usuario y las relaciones empresariales. 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.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

Nota:

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

Microsoft Entra ID recursos y sus relaciones que derivan de directoryObject admiten el parámetro de $search consulta solo en consultas avanzadas. 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 diferentes⁽1⁾: HelloWorld o helloWORLD =>hello, world
  • Símbolos⁽2⁾: hello.world =>hello, ., , worldhelloworld
  • Números: hello123world =>hello, 123, world

⁽1⁾ Actualmente, la tokenización solo funciona cuando el uso de mayúsculas y minú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 helloworld búsqueda buscará hello-world y hello.world.

Nota:

  • Después de la tokenización, los tokens se hacen coincidir sin distinguir mayúsculas de minúsculas y 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 tengan tokens de one y video, o correo que empiece por 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 se restringen en función de una conjunción lógica ("Y") de $filter y la consulta completa 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. 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 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.

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).

Contenido relacionado