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. Einige, z. B. Microsoft Entra Ressourcen, die von directoryObject abgeleitet werden und nur in erweiterten Abfragen unterstützt werden$search.
Hinweis
Der $search-Abfrageparameter steht auf Azure AD B2C-Mandanten derzeit nicht zur Verfügung.
Sie können Nachrichten basierend auf einem Wert in bestimmten Nachrichteneigenschaften durchsuchen. 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"
// 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 version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.search = "\"pizza\"";
});
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.
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.
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:
Sie können die Personen-API von Microsoft Graph verwenden, um Personen abzurufen, die für einen Benutzer am relevantesten sind. Die 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"
// 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 version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
PersonCollectionResponse result = graphClient.me().people().get(requestConfiguration -> {
requestConfiguration.queryParameters.search = "\"Irene McGowen\"";
});
Verwenden von $search für Verzeichnisobjektsammlungen
Hinweis
Es gibt ein bekanntes Problem im Zusammenhang mit $search on-Verzeichnisobjekten für Werte, die ein kaufmännisches Und-Zeichen (&) enthalten.
Microsoft Entra ID Ressourcen und deren Beziehungen, die von directoryObject abgeleitet werden, 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⁽1⁾: HelloWorld oder helloWORLD =>hello, world
⁽1⁾ Derzeit funktioniert die Tokenisierung nur, wenn die Groß-/Kleinschreibung von Kleinbuchstaben in Großbuchstaben geändert wird. HELLOworld Daher wird als einzelnes Token betrachtet: helloworld, und HelloWORld sind zwei Token: hello, world.
⁽2⁾ Tokenisierungslogik kombiniert auch Wörter, die nur durch Symbole getrennt sind; Wenn Sie z. B. nach suchenhelloworld, werden und hello.worldgefundenhello-world.
Hinweis
Nach der Tokenisierung werden die Token unabhängig von der ursprünglichen Groß- und Kleinschreibung und in beliebiger Reihenfolge abgeglichen. Beispielsweise entspricht displayName Suchzeichenfolgen wie 李四(David Li), , 李四, DavidLi, David), (李四, , Li 李.李四(David Li)
Eine Änderung des Alphabets, z. B. von Lateinisch zu Kyrillisch oder Chinesisch, führt nicht zu einem neuen Token. Beispielsweise stimmt displayName 蓝色group mit den 蓝色group Suchzeichenfolgen und 蓝色 überein, aber nicht group; während displayName group蓝色 mit den group蓝色 Suchzeichenfolgen und group übereinstimmt, aber nicht 蓝色 oder 蓝.
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
// 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 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");
});
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");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups list --search ""displayName:OneVideo"" --filter "mailEnabled eq true" --consistency-level "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");
});
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.
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.
Sowohl die in $search bereitgestellten Zeichenfolgeneingaben als auch die durchsuchbaren Eigenschaften werden durch Leerzeichen, unterschiedliche Groß- und Kleinschreibung und Zeichentypen (Zahlen und Sonderzeichen) aufgeteilt.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.