Compartir a través de

Uso del parámetro de consulta $search en las API de Microsoft Graph

El $search parámetro de consulta es un eficaz mecanismo de filtrado en Microsoft Graph que permite encontrar datos específicos mediante la coincidencia de criterios de búsqueda.

La compatibilidad con este parámetro de consulta varía según la entidad. Algunas entidades, como Microsoft Entra recursos que derivan de directoryObject, solo admiten $searchconsultas avanzadas.

En este artículo se explica cómo usar el parámetro de $search consulta de forma eficaz con tres tipos de recursos clave: mensajes de correo, personas y objetos Microsoft Entra ID (objetos de directorio). Obtenga información sobre los requisitos de sintaxis específicos, las propiedades admitidas y los comportamientos de búsqueda de cada tipo de recurso.

Uso de $search en colecciones de mensajes

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

Al buscar mensajes sin especificar propiedades de mensaje, la búsqueda tiene como destino estas propiedades predeterminadas: de, asunto y cuerpo.

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 propiedad de mensaje que reconoce la sintaxis del Lenguaje de 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, que proporciona un dominio de detección común para sus almacenes de datos.

Propiedades del correo electrónico que permiten búsquedas Descripción Ejemplo
attachment Nombres de 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

GET../me/messages?$search="from:adelev OR from:alexw OR from: allanD"&$select=subject, from
hasAttachment true si un mensaje de correo electrónico contiene datos adjuntos que no son datos adjuntos insertados; false de otra manera. 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 son low, mediumo 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, taskso 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 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 que el 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 se pueden buscar, la sintaxis de KQL, los operadores admitidos y las sugerencias de búsqueda, consulte estos artículos:

Uso de $search en colecciones de personas

Puede aplicar $search a las propiedades displayName y emailAddresses del recurso person . Las solicitudes devuelven hasta 250 resultados de forma predeterminada.

La siguiente solicitud busca "Irene McGowan" en la colección de objetos person para el usuario que ha iniciado sesión. Microsoft Graph busca en las propiedades displayName y 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.

Uso de $search en colecciones de objetos de directorio

Microsoft Entra ID recursos 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 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, usa un enfoque de tokenización que extrae palabras de valores de propiedad y cadenas de búsqueda mediante espacios, números, mayúsculas y minúsculas diferentes y símbolos, como se muestra en estos 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⁾ Para mayúsculas y minúsculas diferentes, la tokenización solo funciona actualmente cuando las mayúsculas y minúsculas cambian de minúsculas a mayúsculas. Por ejemplo, HELLOworld es un solo token: helloworldy HelloWORld es de 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 se comparan independientemente de las mayúsculas y minúsculas originales y en cualquier orden. Por ejemplo, displayName 李四(David Li) coincide con cadenas de búsqueda como 李四(David Li), 李四, David, Li, David), , (李四. Li 李 Un cambio en el alfabeto (por ejemplo, del latín al cirílico o chino) no crea un nuevo token. Por ejemplo, displayName 蓝色group coincide con las 蓝色group cadenas y 蓝色 de búsqueda, pero no groupcon . DisplayName group蓝色 coincide con las group蓝色 cadenas y group de búsqueda, pero no 蓝色 o 蓝.

La búsqueda tokenizada solo funciona en los campos displayName y description . Cualquier campo de tipo de cadena se puede usar en $search, pero los campos distintos de displayName y description son los valores predeterminados del $filterstartswith 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 y video tokens, o correo a partir de onevideo.

Puede usar $search junto con $filter:

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

Esto busca todos los grupos habilitados para correo con nombres para mostrar que se parezcan a "OneVideo". Los resultados se filtran en función de una conjunción lógica (AND) de $filter y toda la consulta en .$search

La sintaxis de búsqueda sigue estas reglas:

  • Formato general: $search="clause1" [AND | OR] "clauseX"
  • Número de cláusulas: se admite cualquier número de cláusulas. También se admiten paréntesis de prioridad.
  • Sintaxis de cláusula: "<property>:<text to search>"
    • Debe especificar el nombre de propiedad en la cláusula .
    • La cláusula completa debe incluirse entre comillas dobles. Si contiene comillas dobles o barra diagonal inversa, escídala con una barra diagonal inversa. Todos los demás caracteres especiales deben estar codificados con dirección URL.
  • Operadores lógicos: AND y OR los operadores deben estar fuera de comillas dobles y en mayúsculas.
  • Comportamiento de búsqueda: la búsqueda verdadera solo se admite para las propiedades displayName y description . Las propiedades que se pueden usar en $filter también se pueden usar dentro de $search. Las propiedades distintas de displayName y description tienen como valor predeterminado $filter el comportamiento "startsWith" si no se admite la búsqueda.
  • Tokenización: tanto las entradas de cadena que proporciona como $search 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"

Contenido relacionado