Verwenden des abfrageparameters $search

Artikel
03/09/2023
11 Minuten Lesedauer

Neben anderen OData-Abfrageparametern unterstützt Microsoft Graph den $search-Abfrageparameter, um die Ergebnisse einer Anforderung so zu beschränken, dass sie einem Suchkriterium entsprechen.

Die Unterstützung für den $search-Abfrageparameter variiert je nach Entität, wobei einige, wie z. B. Azure AD-Ressourcen, die sich von directoryObject ableiten, $search nur in erweiterten Abfragen unterstützen.

Hinweis

Der $search-Abfrageparameter steht auf Azure AD B2C-Mandanten derzeit nicht zur Verfügung.

Verwenden von $search in Nachrichtensammlungen

Sie können nach Nachrichten auf Grundlage eines Werts in einer bestimmten Eigenschaften suchen. Die Suchergebnisse sind nach Datum und Uhrzeit sortiert, zu dem bzw. der die Nachricht gesendet wurde. Eine $search Anforderung gibt bis zu 1000 Ergebnisse zurück.

Wenn Sie eine Suche nach Nachrichten durchführen und nur einen Wert ohne bestimmte Nachrichteneigenschaften angeben, wird die Suche anhand der Standardsucheigenschaftenfrom, subject und body ausgeführt.

Im folgenden Beispiel werden alle Nachrichten im Posteingang des angemeldeten Benutzers zurückgegeben, die das Wort „Pizza“ in einer der drei Standardsucheigenschaften enthalten:

GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Search = "\"pizza\"";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.search('pizza')
	.get();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new QueryOption("$search", "\"pizza\""));

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest( requestOptions )
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestSearch := "\"pizza\""

requestParameters := &graphconfig.MeMessagesRequestBuilderGetQueryParameters{
	Search: &requestSearch,
}
configuration := &graphconfig.MeMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Search '"pizza"'


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();

$queryParameters = new MessagesRequestBuilderGetQueryParameters();
$queryParameters->search = "\"pizza\"";

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->me()->messages()->get($requestConfiguration);

Alternativ können Sie eine Suche nach Nachrichten durchführen, indem Sie die Nachrichteneigenschaftennamen in der folgenden Tabelle angeben, die durch die KQL-Syntax erkannt werden. Diese Eigenschaftennamen entsprechen den in der message-Entität von Microsoft Graph definierten Eigenschaften. Outlook und andere Microsoft 365-Anwendungen wie SharePoint unterstützen die KQL-Syntax und bieten den Komfort einer gemeinsamen Discovery-Domäne für ihre Datenspeicher.

Durchsuchbare E-Mail-Eigenschaft	Beschreibung	Beispiel
Anlage	Die Namen der an eine E-Mail angefügten Dateien.	ABRUFEN`../me/messages?$search="attachment:api-catalog.md"`
bcc	Das bcc-Feld einer E-Mail-Nachricht, das als SMTP-Adresse, Anzeigename oder Alias angegeben ist.	ABRUFEN`../me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients`
Text	Text einer E-Mail.	ABRUFEN`../me/messages?$search="body:excitement"`
cc	Das cc-Feld einer E-Mail-Nachricht, das als SMTP-Adresse, Anzeigename oder Alias angegeben ist.	ABRUFEN`../me/messages?$search="cc:danas"&$select=subject,ccRecipients`
Von	Der Absender einer E-Mail-Nachricht, der als SMTP-Adresse, Anzeigename oder Alias angegeben ist.	ABRUFEN`../me/messages?$search="from:randiw"&$select=subject,from`
hasAttachment	„True“, wenn eine E-Mail eine Anlage enthält, die keine Inlineanlage ist, andernfalls „false“.	ABRUFEN`../me/messages?$search="hasAttachments:true"`
Wichtigkeit	Die Wichtigkeit einer E-Mail-Nachricht, die ein Absender festlegen kann, wenn er eine Nachricht sendet. Die möglichen Werte sind `low`, `medium` oder `high`.	ABRUFEN`../me/messages?$search="importance:high"&$select=subject,importance`
Art	Der Typ der Nachricht. Die möglichen Werte sind `contacts`, `docs`, `email`, `faxes`, `im`, `journals`, `meetings`, `notes`, `posts`, `rssfeeds`, `tasks` oder `voicemail`.	ABRUFEN`../me/messages?$search="kind:voicemail"`
Teilnehmer	Die von-, an-, cc- und bcc-Felder einer E-Mail-Nachricht, die als SMTP-Adressen, Anzeigenamen oder Aliase angegeben sind.	ABRUFEN`../me/messages?$search="participants:danas"`
Empfangen	Das Datum, an dem eine E-Mail-Nachricht von einem Empfänger empfangen wurde.	ABRUFEN`../me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime`
recipients	Die an-, cc- und bcc-Felder einer E-Mail-Nachricht, die als SMTP-Adressen, Anzeigenamen oder Aliase angegeben sind.	ABRUFEN`../me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients`
Gesendet	Das Datum, an dem eine E-Mail vom Absender gesendet wurde.	ABRUFEN`../me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime`
size	Die Größe eines Elements in Byte.	ABRUFEN`../me/messages?$search="size:1..500000"`
Betreff	Der Text in der Betreffzeile einer E-Mail. .	ABRUFEN`../me/messages?$search="subject:has"&$select=subject`
An	Das An-Feld einer E-Mail-Nachricht, das als SMTP-Adresse, Anzeigename oder Alias angegeben ist.	ABRUFEN`.../me/messages?$search="to:randiw"&$select=subject,toRecipients`

Weitere Informationen zu durchsuchbaren E-Mail-Eigenschaften, zu KQL-Syntax, unterstützten Operatoren und Tipps für die Suche finden Sie in den folgenden Artikeln:

Verwenden von $search in Personensammlungen

Sie können die Personen-API von Microsoft Graph verwenden, um Personen abzurufen, die für einen Benutzer am relevantesten sind. Relevanz wird durch die Kommunikations- und Zusammenarbeitsmuster und Geschäftsbeziehungen des Benutzers bestimmt. Die Personen-API unterstützt den $search-Abfrageparameter. Eine $search-Anforderung gibt bis zu 250 Ergebnisse zurück.

Personensuchen werden sowohl für die Eigenschaft displayName als auch für die Eigenschaft emailAddress der Ressource vom Typ person ausgeführt.

Die folgende Anforderung führt eine Suche nach einer Person mit dem Namen „Irene McGowen“ in den Eigenschaften displayName und emailAddress für jede Person in der Sammlung people des angemeldeten Benutzers durch. Da eine Person mit dem Namen „Irene McGowan“ für den angemeldeten Benutzer relevant ist, werden die Informationen für „Irene McGowan“ zurückgegeben.

GET https://graph.microsoft.com/v1.0/me/people/?$search="Irene McGowen"


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.People.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Search = "\"Irene McGowen\"";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let people = await client.api('/me/people/')
	.search('Irene McGowen')
	.get();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new QueryOption("$search", "\"Irene McGowen\""));

PersonCollectionPage people = graphClient.me().people()
	.buildRequest( requestOptions )
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestSearch := "\"Irene McGowen\""

requestParameters := &graphconfig.MePeopleRequestBuilderGetQueryParameters{
	Search: &requestSearch,
}
configuration := &graphconfig.MePeopleRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().People().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.People

# A UPN can also be used as -UserId.
Get-MgUserPerson -UserId $userId -Search '"Irene McGowen"'


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new PeopleRequestBuilderGetRequestConfiguration();

$queryParameters = new PeopleRequestBuilderGetQueryParameters();
$queryParameters->search = "\"Irene McGowen\"";

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->me()->people()->get($requestConfiguration);

Das folgende Beispiel zeigt die Antwort.

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"
           }
       }
   ]
}

Weitere Informationen zur Personen-API finden Sie unter Abrufen von Informationen über die entsprechenden Personen.

Verwenden von $search für Verzeichnisobjektsammlungen

Azure AD-Ressourcen und ihre Beziehungen, die von directoryObject abgeleitet sind, unterstützen den $search Abfrageparameter nur in erweiterten Abfragen. Die Suchimplementierung unterstützt keine "contains"-Logik. Stattdessen wird ein Tokenisierungsansatz verwendet, bei dem Wörter aus dem Eigenschaftswert und der Suchzeichenfolge extrahiert werden, wobei Leerzeichen, Zahlen, unterschiedliche Groß- und Kleinschreibung und Symbole verwendet werden, wie in den folgenden Beispielen gezeigt:

Leerzeichen: hello world =>hello, world
Andere Groß-/Kleinschreibung⁽¹⁾: HelloWorld oder helloWORLD =>hello, world
Symbole⁽²⁾: hello.world =>hello, ., world, helloworld
Zahlen: hello123world =>hello, 123, world

⁽¹⁾ Zurzeit funktioniert die Tokenisierung nur, wenn die Groß-/Kleinschreibung von Klein- zu Großbuchstaben wechselt. Deshalb wird HELLOworld als einzelnes Token betrachtet, helloworld und HelloWORld hingegen als zwei Token: hello, world. ⁽²⁾ Bei der Tokenisierung werden außerdem Wörter kombiniert, die nur durch Symbole getrennt sind. Wenn Sie beispielsweise nach helloworld suchen, werden hello-world und hello.world gefunden.

Hinweis

Nach der Tokenisierung werden die Token unabhängig von der ursprünglichen Groß- und Kleinschreibung und in beliebiger Reihenfolge abgeglichen. Beispielsweise entspricht displayName 李四(David Li) Suchzeichenfolgen wie 李四(David Li), 李四, David, Li, David), (李四, Li 李.
Die Unterstützung für die tokenbasierte Suche funktioniert nur für die Felder displayName und description. Jedes Feld vom Typ String kann in $searcheingefügt werden. Andere Felder als displayName und description werden standardmäßig auf $filterstartswith Verhalten festgelegt. Beispiel:

GET https://graph.microsoft.com/v1.0/groups/?$search="displayName:OneVideo" OR "mail:onevideo"
ConsistencyLevel: eventual


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Search = "\"displayName:OneVideo\" OR \"mail:onevideo\"";
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});

Snippet not available

Snippet not available


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)

headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestSearch := "\"displayName:OneVideo\" OR \"mail:onevideo\""

requestParameters := &graphconfig.GroupsRequestBuilderGetQueryParameters{
	Search: &requestSearch,
}
configuration := &graphconfig.GroupsRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

result, err := graphClient.Groups().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Groups

Get-MgGroup -Search '"displayName:OneVideo" OR "mail:onevideo"' -ConsistencyLevel eventual


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new GroupsRequestBuilderGetRequestConfiguration();

$queryParameters = new GroupsRequestBuilderGetQueryParameters();
$queryParameters->search = "\"displayName:OneVideo\" OR \"mail:onevideo\"";

$headers = [
'ConsistencyLevel' => 'eventual',
];

$requestConfiguration->queryParameters = $queryParameters;
$requestConfiguration->headers = $headers;


$requestResult = $graphServiceClient->groups()->get($requestConfiguration);

Dadurch wird nach allen Gruppen mit Anzeigenamen gesucht, die onevideo über Token oder E-Mails verfügen, die mit onevideo beginnen.

$search kann auch zusammen mit $filter verwendet werden:

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "mailEnabled eq true";
	requestConfiguration.QueryParameters.Search = "\"displayName:OneVideo\"";
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});


const options = {
	authProvider,
};

const client = Client.init(options);

let groups = await client.api('/groups/')
	.header('ConsistencyLevel','eventual')
	.filter('mailEnabled eq true')
	.search('displayName:OneVideo')
	.get();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("ConsistencyLevel", "eventual"));
requestOptions.add(new QueryOption("$search", "\"displayName:OneVideo\""));

GroupCollectionPage groups = graphClient.groups()
	.buildRequest( requestOptions )
	.filter("mailEnabled eq true")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)

headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestFilter := "mailEnabled eq true"
requestSearch := "\"displayName:OneVideo\""

requestParameters := &graphconfig.GroupsRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Search: &requestSearch,
}
configuration := &graphconfig.GroupsRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

result, err := graphClient.Groups().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Groups

Get-MgGroup -Filter "mailEnabled eq true" -Search '"displayName:OneVideo"' -ConsistencyLevel eventual


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new GroupsRequestBuilderGetRequestConfiguration();

$queryParameters = new GroupsRequestBuilderGetQueryParameters();
$queryParameters->filter = "mailEnabled eq true";
$queryParameters->search = "\"displayName:OneVideo\"";

$headers = [
'ConsistencyLevel' => 'eventual',
];

$requestConfiguration->queryParameters = $queryParameters;
$requestConfiguration->headers = $headers;


$requestResult = $graphServiceClient->groups()->get($requestConfiguration);

Damit wird nach allen E-Mail-aktivierten Gruppen gesucht, deren Anzeigename wie "OneVideo" aussieht. Die Ergebnisse werden basierend auf einer logischen Konjunktion (einem "UND") der $filter und der gesamten Abfrage in der $search eingeschränkt.

Die Syntax der Suche folgt diesen Regeln:

Generisches Format: $search="clause1" [AND | OR] "[clauseX]".
Eine beliebige Anzahl von Klauseln wird unterstützt. Klammern für die Rangfolge werden ebenfalls unterstützt.
Die Syntax für jede Klausel lautet: "<property>:<text to search>".
Der Eigenschaftenname muss in der Klausel angegeben werden. Jede Eigenschaft, die in $filter verwendet werden kann, kann auch innerhalb von $search verwendet werden. Je nach Eigenschaft ist das Suchverhalten entweder „search“ oder „startsWith“, wenn die Suche für die Eigenschaft nicht unterstützt wird.
Die gesamte Klausel muss in doppelten Anführungszeichen deklariert werden. Wenn sie doppelte Anführungszeichen oder umgekehrte Schrägstriche enthält, sollte sie mit einem umgekehrten Schrägstrich mit Escapezeichen versehen werden. Alle anderen Sonderzeichen müssen URL-codiert sein.
Logische AND- und OR-Operatoren müssen außerhalb doppelter Anführungszeichen platziert werden und müssen in Großbuchstaben vorliegen.

Die folgende Tabelle enthält einige Beispiele.

Objektklasse	Beschreibung	Beispiel
Benutzer	Der Anzeigename des Benutzers im Adressbuch.	ABRUFEN`../users?$search="displayName:Guthr"`
Benutzer	Der Anzeigename oder die E-Mail-Adresse des Benutzers im Adressbuch.	ABRUFEN`../users?$search="displayName:Guthr" OR "mail:Guthr"`
Gruppe	Der Anzeigename oder die Beschreibung der Gruppe im Adressbuch.	ABRUFEN`../groups?$search="description:One" AND ("displayName:Video" OR "displayName:Drive"`
Gruppe	Der Anzeigename einer E-Mail-aktivierten Gruppe im Adressbuch.	ABRUFEN`../groups?$filter=mailEnabled eq true&$search="displayName:OneVideo"`

Sowohl die in $search bereitgestellten Zeichenfolgeneingaben als auch die durchsuchbaren Eigenschaften werden durch Leerzeichen, unterschiedliche Groß- und Kleinschreibung und Zeichentypen (Zahlen und Sonderzeichen) aufgeteilt.

Verwenden des abfrageparameters $search

Verwenden von $search in Nachrichtensammlungen

Verwenden von $search in Personensammlungen

Verwenden von $search für Verzeichnisobjektsammlungen

Siehe auch

Zusätzliche Ressourcen

Zusätzliche Ressourcen