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. En este artículo se describe la sintaxis y el comportamiento de búsqueda en las tres áreas principales siguientes:
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"
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Search = "\"pizza\"";
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestSearch := "\"pizza\""
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Search: &requestSearch,
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.search = "\"pizza\"";
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
search = "\"pizza\"",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
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.
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.
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:
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"
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.People.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Search = "\"Irene McGowen\"";
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestSearch := "\"Irene McGowen\""
requestParameters := &graphusers.ItemPeopleRequestBuilderGetQueryParameters{
Search: &requestSearch,
}
configuration := &graphusers.ItemPeopleRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
people, err := graphClient.Me().People().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
PersonCollectionResponse result = graphClient.me().people().get(requestConfiguration -> {
requestConfiguration.queryParameters.search = "\"Irene McGowen\"";
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.people.people_request_builder import PeopleRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = PeopleRequestBuilder.PeopleRequestBuilderGetQueryParameters(
search = "\"Irene McGowen\"",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.people.get(request_configuration = request_configuration)
Usar $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 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 diferentes⁽1⁾: HelloWorld o helloWORLD =>hello, 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.
GET https://graph.microsoft.com/v1.0/groups/?$search="displayName:OneVideo" OR "mail:onevideo"
ConsistencyLevel: eventual
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Search = "\"displayName:OneVideo\" OR \"mail:onevideo\"";
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
requestSearch := "\"displayName:OneVideo\" OR \"mail:onevideo\""
requestParameters := &graphgroups.GroupsRequestBuilderGetQueryParameters{
Search: &requestSearch,
}
configuration := &graphgroups.GroupsRequestBuilderGetRequestConfiguration{
Headers: headers,
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
GroupCollectionResponse result = graphClient.groups().get(requestConfiguration -> {
requestConfiguration.queryParameters.search = "\"displayName:OneVideo\" OR \"mail:onevideo\"";
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.groups.groups_request_builder import GroupsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters(
search = "\"displayName:OneVideo\" OR \"mail:onevideo\"",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")
result = await graph_client.groups.get(request_configuration = request_configuration)
GET https://graph.microsoft.com/v1.0/groups/?$filter=mailEnabled eq true&$search="displayName:OneVideo"
ConsistencyLevel: eventual
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "mailEnabled eq true";
requestConfiguration.QueryParameters.Search = "\"displayName:OneVideo\"";
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
GroupCollectionResponse result = graphClient.groups().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "mailEnabled eq true";
requestConfiguration.queryParameters.search = "\"displayName:OneVideo\"";
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.groups.groups_request_builder import GroupsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters(
filter = "mailEnabled eq true",
search = "\"displayName:OneVideo\"",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")
result = await graph_client.groups.get(request_configuration = request_configuration)
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
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.