Outre les autres paramètres de requête OData, Microsoft Graph prend en charge le paramètre de requête $search pour limiter les résultats d’une requête qui répondent à un critère de recherche.
La prise en charge du paramètre de requête varie selon l’entité$search, certaines, telles que les ressources Microsoft Entra qui dérivent de directoryObject, prenant en charge $search uniquement les requêtes avancées. Cet article décrit la syntaxe et le comportement de recherche dans les trois domaines main suivants :
Utilisation du critère $search dans les collections de messages
Vous pouvez rechercher des messages en fonction d’une valeur dans des propriétés de message spécifiques. Les résultats de la recherche sont triés par date et heure d’envoi du message. Une $search requête retourne jusqu’à 1 000 résultats.
Si vous effectuez une recherche sur des messages et que vous spécifiez une valeur sans propriété de message spécifique, la recherche est effectuée sur les propriétés de recherche par défaut des éléments from, subject et body.
L’exemple suivant renvoie tous les messages de la boîte de réception de l’utilisateur connecté dont l’une des trois propriétés de recherche par défaut contient « pizza » :
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)
Vous pouvez également rechercher des messages en spécifiant les noms de propriété des messages dans le tableau suivant, qui seront reconnus par la syntaxe de langage de requête de mot clé (KQL). Ces noms de propriété correspondent aux propriétés définies dans l’entité de message de Microsoft Graph. Outlook et d’autres applications Microsoft 365, telles que SharePoint, prennent en charge la syntaxe KQL et procurent le confort d’un domaine de découverte en commun pour leurs magasins de données.
Propriété de messagerie utilisable dans une requête
Description
Exemple
attachment
Nom des fichiers joints à un message électronique.
Pour plus d’informations sur les propriétés de messagerie utilisables dans une requête, la syntaxe KQL et les opérateurs pris en charge, et pour bénéficier de conseils sur la recherche, consultez les articles suivants :
Utilisation du critère $search dans les collections person
Vous pouvez appliquer $search aux propriétés displayName et emailAddresses de la ressource person . La requête retourne jusqu’à 250 résultats par défaut.
La requête suivante recherche « Irene McGowan » dans les objets de personne de collection de l’utilisateur connecté. Microsoft Graph étend la recherche aux propriétés displayName ou 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)
Utilisation de $search sur les collections d’objets de l’annuaire
Microsoft Entra ID ressources et leurs relations qui dérivent de directoryObject prennent en charge le $search paramètre de requête uniquement dans les requêtes avancées.
Remarque
Le paramètre de requête $search n’est actuellement pas disponible dans les clients Azure AD B2C.
Il existe un problème connu lié aux $search objets de répertoire pour les valeurs qui contiennent un symbole esperluette (&).
L’implémentation de recherche ne prend pas en charge la logique « contains ». Au lieu de cela, il utilise une approche de création de jetons qui fonctionne en extrayant des mots de la valeur de la propriété et de la chaîne de recherche à l'aide d'espaces, de chiffres, de casse différente et de symboles, comme le montrent les exemples suivants :
Espaces : hello world =>hello, world
Casse différente⁽1⁾ : HelloWorld ou helloWORLD =>hello, world
⁽1⁾ Pour une casse différente, la création de jetons ne fonctionne actuellement que lorsque la casse passe de minuscules à majuscules. Elle est donc HELLOworld considérée comme un jeton unique : helloworld, et HelloWORld est deux jetons : hello, world.
⁽2⁾ La logique de tokenisation combine également des mots séparés uniquement par des symboles ; par exemple, la helloworld recherche de finds hello-world et hello.world.
Après la création de jetons, les jetons sont mis en correspondance indépendamment de la casse d’origine, et ils sont mis en correspondance dans n’importe quel ordre. Par exemple, displayName 李四(David Li) correspond à des chaînes de recherche telles que 李四(David Li), 李四, David, Li, David), (李四, , Li 李. Une modification de l’alphabet, par exemple du latin au cyrillique ou au chinois, ne crée pas de jeton. Par exemple, displayName 蓝色group correspond aux 蓝色group chaînes de recherche et 蓝色 , mais pas group; tandis que displayName group蓝色 correspond aux group蓝色 chaînes de recherche et group , mais pas 蓝色 ou 蓝.
Le support de recherche à jeton fonctionne uniquement sur les champs Nom complet et description. Tout champ de type String peut être placé dans $search; les champs autres que displayName et description sont par défaut de $filterstartswith comportement.
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)
Cette fonction recherche tous les groupes de messagerie dont les noms complets ressemblent à « OneVideo ».
Les résultats sont limités en fonction d’une conjonction logique (« AND ») de et $filter de l’ensemble de la requête dans le $search.
La syntaxe de la recherche respecte les règles suivantes :
Un nombre quelconque de clauses est pris en charge. Les parenthèses pour la préséance sont également prises en charge.
La syntaxe de chaque clause est la suivante : «< property> :<text to search> ».
Le nom de la propriété doit être spécifié dans la clause.
La clause entière doit être déclarée entre guillemets doubles. S’il contient des guillemets doubles ou une barre oblique inverse, il doit être placé dans une séquence d’échappement avec une barre oblique inverse. Tous les autres caractères spéciaux doivent être encodés en URL.
Les opérateurs logiques AND et OR doivent être placés en dehors des guillemets doubles et en majuscules.
La recherche true est prise en charge uniquement par les propriétés displayName et description ; mais toute propriété pouvant être utilisée dans $filter peut également être utilisée dans $search. Selon la propriété, le comportement de recherche est « search » ou $filter « startsWith » si la recherche n’est pas prise en charge sur la propriété.
Les entrées de chaîne que vous fournissez dans $searchet les propriétés pouvant faire l’objet d’une recherche sont divisées en parties par espaces, casses différentes et types de caractères (nombres et caractères spéciaux).
Le tableau ci-dessous vous montre quelques exemples.
Classe d’objet
Description
Exemple
Utilisateur
Nom complet du carnet d'adresses de l'utilisateur.