Verwenden von Abfrageparametern zum Anpassen von AntwortenUse query parameters to customize responses

Microsoft Graph unterstützt optionale Abfrageparameter, die Sie zum Festlegen und Steuern der in einer Antwort zurückgegebenen Datenmenge verwenden können.Microsoft Graph supports optional query parameters that you can use to specify and control the amount of data returned in a response. Die Unterstützung der Abfrageparameter ist je nach API-Vorgang unterschiedlich, und je nach API sind v1.0- oder Beta-Endpunkte verfügbar.The support for the exact query parameters varies from one API operation to another, and depending on the API, can differ between the v1.0 and beta endpoints.

Tipp

Am Beta-Endpunkt ist das $-Präfix optional.$ On the v1.0 and beta endpoints, the prefix is optional. Sie können z. B. filter anstelle von $filter verwenden.For example, instead of $filter, you can use filter. Beim v1-Endpunkt ist das $-Präfix für nur eine Teilmenge der APIs optional.On the v1 endpoint, the $ prefix is optional for only a subset of APIs. Verwenden Sie zur Vereinfachung immer $ wenn Sie den v1-Endpunkt verwenden.For simplicity, always include $ if using the v1 endpoint.

Abfrageparameter können OData-System-Abfrageoptionen oder andere Abfrageparameter sein.Query parameters can be OData system query options or other query parameters.

OData-System-AbfrageoptionenOData system query options

Ein Microsoft Graph-API-Vorgang kann eine oder mehrere der folgenden OData-System-Abfrageoptionen unterstützen.A Microsoft Graph API operation might support one or more of the following OData system query options. Diese Abfrageparameter sind mit der OData V4-Abfragesprache kompatibel.These query options are compatible with the OData V4 query language.

Hinweis: Klicken Sie auf die Beispiele, um sie im Graph-Tester auszuprobieren.Note: Click the examples to try them in Graph Explorer.

NameName BeschreibungDescription BeispielExample
$count$count Dient zum Abrufen der Gesamtzahl übereinstimmender Ressourcen.Retrieves the total count of matching resources. /me/messages?$top=2&$count=true
$expand$expand Dient zum Abrufen von verwandten Ressourcen.Retrieves related resources. /groups?$expand=members
$filter$filter Dient zum Filtern von Ergebnissen (Zeilen).Filters results (rows). /users?$filter=startswith(givenName,'J')
$format$format Dient zum Zurückgeben der Ergebnisse im angegebenen Medienformat.Returns the results in the specified media format. /users?$format=json
$orderby$orderby Dient zum Sortieren von Ergebnissen.Orders results. /users?$orderby=displayName desc
$search$search Dient zum Zurückgeben von Ergebnissen basierend auf Suchkriterien. Wird derzeit in messages- und person-Sammlungen unterstützt.Returns results based on search criteria. Currently supported on messages and person collections. /me/messages?$search=pizza
$select$select Dient zum Filtern von Eigenschaften (Spalten).Filters properties (columns). /users?$select=givenName,surname
$skip$skip Dient zum Indizieren in einem Resultset. Wird auch von einigen APIs zum Implementieren von Paging verwendet und kann zusammen mit $top zum manuellen Auslagern von Ergebnissen verwendet werden.Indexes into a result set. Also used by some APIs to implement paging and can be used together with $top to manually page results. /me/messages?$skip=11
$top$top Dient zum Festlegen der Seitengröße von Ergebnissen.Sets the page size of results. /users?$top=2

Andere AbfrageparameterOther query parameters

NameName BeschreibungDescription BeispielExample
$skipToken$skipToken Dient zum Abrufen der nächsten Seite von Ergebnissen aus Resultsets, die mehrere Seiten umfassen. (Einige APIs verwenden stattdessen $skip.)Retrieves the next page of results from result sets that span multiple pages. (Some APIs use $skip instead.) /users?$skiptoken=X%274453707402000100000017...

Codieren von AbfrageparameternEncoding query parameters

Die Werte von Abfrageparametern sollten als Prozentwert codiert werden.The values of query parameters should be percent-encoded. Viele HTTP-Clients, Browser und Tools (z. B. der Graph-Tester) sind Ihnen dabei behilflich.Many HTTP clients, browsers, and tools (such as the Graph Explorer) will help you with this. Wenn bei einer Abfrage ein Fehler auftritt, kann eine der möglichen Ursachen dafür sein, dass die Werte von Abfrageparametern nicht ordnungsgemäß codiert wurden.If a query is failing, one possible cause is failure to encode the query parameter values appropriately.

Eine nicht codierte URL sieht folgendermaßen aus:An unencoded URL looks like this:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')

Eine korrekt codierte URL sieht folgendermaßen aus:A properly encoded URL looks like this:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')

Escapezeichen für einfache AnführungszeichenEscaping single quotes

Für Anfragen, die einfache Anführungszeichen verwenden, müssen doppelte Escapezeichen verwendet werden, wenn andere Parameterwerte auch einfache Anführungszeichen enthalten. Andernfalls tritt bei der Anfrage ein Fehler aufgrund einer ungültigen Syntax auf.For requests that use single quotes, if any parameter values also contain single quotes, those must be double escaped; otherwise, the request will fail due to invalid syntax. Im Beispiel wurden für den Zeichenfolgenwert let''s meet for lunch? Escapezeichen für das einfache Anführungszeichen verwendet.In the example, the string value let''s meet for lunch? has the single quote escaped.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq 'let''s meet for lunch?'

count-Parametercount parameter

Verwenden Sie $count als Abfrageparameter, um die Gesamtzahl der Elemente in einer Sammlung zusammen mit der Seite der Datenwerte anzugeben, die von Microsoft Graph zurückgegeben werden.Use the $count query parameter to include a count of the total number of items in a collection alongside the page of data values returned from Microsoft Graph.

Die folgende Anforderung gibt beispielsweise sowohl die contact-Sammlung des aktuellen Benutzers sowie die Anzahl von Elementen in der contact-Sammlung in der @odata.count-Eigenschaft zurück.For example, the following request will return both the contact collection of the current user, and the number of items in the contact collection in the @odata.count property.

GET  https://graph.microsoft.com/v1.0/me/contacts?$count=true

Im Graph-Tester ausprobierenTry in Graph Explorer

Hinweis: $count wird für Sammlungen von Ressourcen, die von directoryObject abgeleitet werden, wie Sammlungen von Benutzern oder Gruppen, nicht unterstützt.Note: $count is not supported for collections of resources that derive from directoryObject like collections of users or groups.

expand-Parameterexpand parameter

Viele Microsoft Graph-Ressourcen machen sowohl deklarierte Eigenschaften der Ressource als auch deren Beziehungen zu anderen Ressourcen verfügbar.Many Microsoft Graph resources expose both declared properties of the resource as well as its relationships with other resources. Diese Beziehungen werden auch als Verweiseigenschaften oder Navigationseigenschaften bezeichnet und können auf eine einzelne Ressource oder auf eine Sammlung von Ressourcen verweisen.These relationships are also called reference properties or navigation properties, and they can reference either a single resource or a collection of resources. Beispielsweise werden die E-Mail-Ordner, die Vorgesetzten und die direkten Mitarbeiter eines Benutzers alle als Beziehungen verfügbar gemacht.For example, the mail folders, manager, and direct reports of a user are all exposed as relationships.

Normalerweise können Sie die Eigenschaften einer Ressource oder eine ihrer Beziehungen in einer einzelnen Anforderung abfragen, aber nicht beides gleichzeitig. Sie können den $expand-Zeichenfolgen-Abfrageparameter verwenden, um die erweiterte Ressource oder die Sammlung, auf die von einer einzigen Beziehung verwiesen wird (Navigationseigenschaft) in Ihre Ergebnisse einzuschließen.Normally, you can query either the properties of a resource or one of its relationships in a single request, but not both. You can use the $expand query string parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results.

Im folgenden Beispiel werden Informationen des Stammlaufwerks zusammen mit den untergeordneten Elementen der obersten Ebene in einem Laufwerk abgerufen:The following example gets root drive information along with the top-level child items in a drive:

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children

Im Graph-Tester ausprobierenTry in Graph Explorer

Bei einigen Ressourcensammlungen können Sie auch die Eigenschaften angeben, die in den erweiterten Ressourcen zurückgegeben werden sollen, indem Sie einen $select-Parameter hinzufügen. Im folgenden Beispiel wird die gleiche Abfrage wie im vorherigen Beispiel ausgeführt, hier wird jedoch eine $select-Anweisung verwendet, um die für die erweiterten untergeordneten Elemente zurückgegebenen Eigenschaften auf die id- und name-Eigenschaften einzuschränken.With some resource collections, you can also specify the properties to be returned in the expanded resources by adding a $select parameter. The following example performs the same query as the previous example but uses a $select statement to limit the properties returned for the expanded child items to the id and name properties.

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)

Ausprobieren im Graph-TesterTry in Graph Explorer

Hinweis: Nicht alle Beziehungen und Ressourcen unterstützen den $expand-Abfrageparameter. Sie können z. B. die Beziehungen directReports, manager und memberOf für einen Benutzer erweitern, aber Sie können nicht seine Beziehungen events, messages oder photo erweitern. Nicht alle Ressourcen oder Beziehungen unterstützen die Verwendung von $select in erweiterten Elementen.Note: Not all relationships and resources support the $expand query parameter. For example, you can expand the directReports, manager, and memberOf relationships on a user, but you cannot expand its events, messages, or photo relationships. Not all resources or relationships support using $select on expanded items.

Bei Azure AD-Ressourcen, die von directoryObject abgeleitet werden, z. B. Benutzer und Gruppe, wird $expand nur für beta unterstützt, und es werden maximal 20 Elemente für die erweiterte Beziehung zurückgegeben.With Azure AD resources that derive from directoryObject, like user and group, $expand is only supported for beta and typically returns a maximum of 20 items for the expanded relationship.

filter-Parameterfilter parameter

Verwenden Sie den $filter-Abfrageparameter, um nur eine Teilmenge einer Sammlung abzurufen.Use the $filter query parameter to retrieve just a subset of a collection.

Um beispielsweise Benutzer zu suchen, deren Anzeigename mit dem Buchstaben „J“ beginnt, verwenden Sie startswith.For example, to find users whose display name starts with the letter 'J', use startswith.

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'J')

Ausprobieren im Graph-TesterTry in Graph Explorer

Die Unterstützung für $filter-Operatoren variiert je nach Microsoft Graph-API.Support for $filter operators varies across Microsoft Graph APIs. Im Allgemeinen werden die folgenden logischen Operatoren unterstützt:The following logical operators are generally supported:

  • gleich (eq)equals (eq)
  • ungleich (ne)not equals (ne)
  • größer als (gt)greater than (gt)
  • größer als oder gleich (ge)greater than or equals (ge)
  • kleiner als (lt), kleiner als oder gleich (le)less than (lt), less than or equals (le)
  • und (and)and (and)
  • oder (or)or (or)
  • nicht (not)not (not)

Der Zeichenfolgenoperator startswith wird häufig unterstützt.The startswith string operator is often supported. Der Lambda-Operator any wird für einige APIs unterstützt.The any lambda operator is supported for some APIs. In der folgenden Tabelle finden Sie einige Verwendungsbeispiele.For some usage examples, see the following table. Weitere Informationen zur $filter-Syntax finden Sie im OData-Protokoll.For more details about $filter syntax, see the OData protocol.

Die folgende Tabelle enthält einige Beispiele zur Verwendung des $filter-Abfrageparameters.The following table shows some examples that use the $filter query parameter.

Hinweis: Klicken Sie auf die Beispiele, um sie im Graph-Tester auszuprobieren.Note: Click the examples to try them in Graph Explorer.

BeschreibungDescription BeispielExample
In mehreren Eigenschaften nach Benutzern mit dem Namen „Mary“ suchenSearch for users with the name Mary across multiple properties. https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')
Alle Ereignisse des angemeldeten Benutzers abrufen, die nach dem 01.07.2017 beginnenGet all the signed-in user's events that start after 7/1/2017. https://graph.microsoft.com/v1.0/me/events?$filter=start/dateTime ge '2017-07-01T08:00'
Alle E-Mails von einer bestimmten Adresse abrufen, die der angemeldete Benutzer erhalten hatGet all emails from a specific address received by the signed-in user. https://graph.microsoft.com/v1.0/me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'
Alle E-Mails abrufen, die der angemeldete Benutzer im April 2017 erhalten hatGet all emails received by the signed-in user in April 2017. https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01
Alle ungelesenen E-Mails im Postfach des angemeldeten Benutzers abrufenGet all unread mail in the signed-in user's Inbox. https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages?$filter=isRead eq false
Alle Office 365-Gruppen in einer Organisation auflistenList all Office 365 groups in an organization. https://graph.microsoft.com/v1.0/groups?$filter=groupTypes/any(c:c+eq+'Unified')

Hinweis: Die folgenden $filter-Operatoren werden für Azure AD-Ressourcen nicht unterstützt: ne, gt, ge, lt, le und not. Der contains-Zeichenfolgenoperator wird derzeit nicht für Microsoft Graph-Ressourcen unterstützt.Note: The following $filter operators are not supported for Azure AD resources: ne, gt, ge, lt, le, and not. The contains string operator is currently not supported on any Microsoft Graph resources.

format-Parameterformat parameter

Verwenden Sie zum Festlegen des Medienformats der von Microsoft Graph zurückgegebenen Elemente den $format-Abfrageparameter.Use the $format query parameter to specify the media format of the items returned from Microsoft Graph.

Die folgende Anforderung gibt beispielsweise die Benutzer in der Organisation im JSON-Format zurück:For example, the following request returns the users in the organization in the json format:

GET https://graph.microsoft.com/v1.0/users?$format=json

Ausprobieren im Graph-TesterTry in Graph Explorer

Hinweis: Der $format-Abfrageparameter unterstützt eine Reihe von Formaten (z. B. Atom, XML und JSON), die Ergebnisse werden aber möglicherweise nicht in allen Formaten zurückgegeben.Note: The $format query parameter supports a number of formats (for example, atom, xml, and json) but results may not be returned in all formats.

orderby-Parameterorderby parameter

Verwenden Sie zum Festlegen der Sortierreihenfolge der von Microsoft Graph zurückgegebenen Elemente den $orderby-Abfrageparameter.Use the $orderby query parameter to specify the sort order of the items returned from Microsoft Graph.

Die folgende Anforderung gibt beispielsweise die Benutzer in der Organisation sortiert nach ihrem Anzeigenamen zurück:For example, the following request returns the users in the organization ordered by their display name:

GET https://graph.microsoft.com/v1.0/users?$orderby=displayName

Ausprobieren im Graph-TesterTry in Graph Explorer

Sie können auch nach komplexen Typentitäten sortieren. In der folgenden Anforderung werden Nachrichten abgerufen und nach dem Adresse-Feld der from-Eigenschaft sortiert, die vom komplexen Typ emailAddress ist:You can also sort by complex type entities. The following request gets messages and sorts them by the address field of the from property, which is of the complex type emailAddress:

GET https://graph.microsoft.com/v1.0/me/messages?$orderby=from/emailAddress/address

Im Graph-Tester ausprobierenTry in Graph Explorer

Wenn Sie die Ergebnisse in aufsteigender oder absteigender Reihenfolge sortieren möchten, fügen Sie entweder asc oder desc getrennt durch ein Leerzeichen an den Namen des Felds an, z. B. ?$orderby=name%20desc.To sort the results in ascending or descending order, append either asc or desc to the field name, separated by a space; for example, ?$orderby=name%20desc.

Bei einigen APIs können Sie die Ergebnisse anhand mehrerer Eigenschaften sortieren.With some APIs, you can order results on multiple properties. Die folgende Anforderung sortiert die Nachrichten im Posteingang des Benutzers beispielsweise zuerst nach dem Namen der Person, die die Nachricht gesendet hat, in absteigender Reihenfolge (von Z nach A) und anschließend nach dem Betreff in aufsteigender Reihenfolge (Standard).For example, the following request orders the messages in the user's Inbox, first by the name of the person who sent it in descending order (Z to A), and then by subject in ascending order (default).

GET https://graph.microsoft.com/v1.0/me/mailFolders/Inbox/messages?$orderby=from/emailAddress/name desc,subject

Im Graph-Tester ausprobierenTry in Graph Explorer

Wenn Sie $filter angeben, leitet der Server eine Sortierreihenfolge für die Ergebnisse ab.When you specify $filter the server will infer a sort order for the results. Wenn Sie sowohl $orderby als auch $filter verwenden, müssen die Eigenschaften in der $filter zuerst in der $orderby vor allen anderen Eigenschaften aufgeführt werden, und sie müssen in der Reihenfolge aufgeführt werden, in der sie im Parameter $filter angezeigt werden, da der Server immer eine Sortierreihenfolge für die Ergebnisse eines $filter ableitet.If you use both $orderby and $filter, because the server always infers a sort order for the results of a $filter, the properties in the $filter must be listed first in the $orderby before any other properties, and they must be listed in the order that they appear in the $filter parameter.

Das folgende Beispiel zeigt eine Abfrage, die nach den Eigenschaften subject und importance gefiltert ist und dann nach den Eigenschaften subject, importance und receivedDateTime in absteigender Reihenfolge sortiert werden.The following example shows a query filtered by the subject and importance properties, and then sorted by the subject, importance, and receivedDateTime properties in descending order.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=Subject eq 'welcome' and importance eq 'normal'&$orderby=subject,importance,receivedDateTime desc

Ausprobieren im Graph-TesterTry in Graph Explorer

Hinweis: Bei Azure AD-Ressourcen, die von directoryObject abgeleitet werden, wie z. B. Benutzer und Gruppe, kann $orderby nicht mit $filter-Ausdrücken verwendet werden.Note: With Azure AD resources that derive from directoryObject, like user and group, you cannot combine $orderby with $filter expressions.

search-Parametersearch parameter

Um die Ergebnisse einer Anforderung so zu beschränken, dass sie einem Suchkriterium entsprechen, verwenden Sie den $search-Abfrageparameter.Use the $search query parameter to restrict the results of a request to match a search criterion.

Hinweis: Sie können derzeit nur Nachrichten- und Personen-Sammlungen suchen. Eine $search-Anforderung gibt bis zu 250 Ergebnisse zurück. Sie können $filter oder $orderby nicht in einer Suchabfrage verwenden.Note: You can currently search only message and person collections. A $search request returns up to 250 results. You cannot use $filter or $orderby in a search request.

Verwenden von $search in NachrichtensammlungenUsing $search on message collections

Sie können nach Nachrichten auf Grundlage eines Werts in einer bestimmten Eigenschaften suchen.You can search messages based on a value in specific message properties. Die Suchergebnisse sind nach Datum und Uhrzeit sortiert, zu dem bzw. der die Nachricht gesendet wurde.The results of the search are sorted by the date and time that the message was sent.

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.If you do a search on messages and specify only a value without specific message properties, the search is carried out on the default search properties of from, subject, and body.

Im folgenden Beispiel werden alle Nachrichten im Posteingang des angemeldeten Benutzers zurückgegeben, die das Wort „Pizza“ in einer der drei Standardsucheigenschaften enthalten:The following example returns all messages in the signed-in user's Inbox that contains "pizza" in any of the three default search properties:

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

Ausprobieren im Graph-TesterTry in Graph Explorer

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.Alternatively, you can search messages by specifying message property names in the following table, that are recognized by the Keyword Query Language (KQL) syntax. Diese Eigenschaftennamen entsprechen den in der message-Entität von Microsoft Graph definierten Eigenschaften.These property names correspond to properties defined in the message entity of Microsoft Graph. Outlook und andere Office 365-Anwendungen wie SharePoint unterstützen die KQL-Syntax und bieten den Komfort einer gemeinsamen Discovery-Domäne für ihre Datenspeicher.Outlook and other Office 365 applications such as SharePoint support KQL syntax, providing the convenience of a common discovery domain for their data stores.

Durchsuchbare E-Mail-EigenschaftSearchable email property BeschreibungDescription BeispielExample
Anlageattachment Die Namen der an eine E-Mail angefügten Dateien.The names of files attached to an email message. me/messages?$search="attachment:api-catalog.md"
bccbcc Das bcc-Feld einer E-Mail-Nachricht, das als SMTP-Adresse, Anzeigename oder Alias angegeben ist.The bcc field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients
Textbody Text einer E-Mail.The body of an email message. me/messages?$search="body:excitement"
cccc Das cc-Feld einer E-Mail-Nachricht, das als SMTP-Adresse, Anzeigename oder Alias angegeben ist.The cc field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="cc:danas"&$select=subject,ccRecipients
Vonfrom Der Absender einer E-Mail-Nachricht, der als SMTP-Adresse, Anzeigename oder Alias angegeben ist.The sender of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="from:randiw"&$select=subject,from
hasAttachmenthasAttachment „True“, wenn eine E-Mail eine Anlage enthält, die keine Inlineanlage ist, andernfalls „false“.True if an email message contains an attachment that is not an inline attachment, false otherwise. me/messages?$search="hasAttachments=true"
Wichtigkeitimportance Die Wichtigkeit einer E-Mail-Nachricht, die ein Absender festlegen kann, wenn er eine Nachricht sendet.The importance of an email message, which a sender can specify when sending a message. Die möglichen Werte sind low, medium oder high.The possible values are low, medium, or high. me/messages?$search="importance:high"&$select=subject,importance
Artkind Der Typ der Nachricht.The type of message. Die möglichen Werte sind contacts, docs, email, faxes, im, journals, meetings, notes, posts, rssfeeds, tasks oder voicemail.The possible values are contacts, docs, email, faxes, im, journals, meetings, notes, posts, rssfeeds, tasks, or voicemail. me/messages?$search="kind:voicemail"
Teilnehmerparticipants Die von-, an-, cc- und bcc-Felder einer E-Mail-Nachricht, die als SMTP-Adressen, Anzeigenamen oder Aliase angegeben sind.The from, to, cc, and bcc fields of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="participants:danas"
Empfangenreceived Das Datum, an dem eine E-Mail-Nachricht von einem Empfänger empfangen wurde.The date that an email message was received by a recipient. me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime
recipientsrecipients Die an-, cc- und bcc-Felder einer E-Mail-Nachricht, die als SMTP-Adressen, Anzeigenamen oder Aliase angegeben sind.The to, cc, and bcc fields of an email meesage, specified as an SMTP address, display name, or alias. me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients
Gesendetsent Das Datum, an dem eine E-Mail vom Absender gesendet wurde.The date that an email message was sent by the sender. me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime
sizesize Die Größe eines Elements in Byte.The size of an item in bytes. me/messages?$search="size:1..500000"
Betreffsubject Der Text in der Betreffzeile einer E-Mail.The text in the subject line of an email message. . me/messages?$search="subject:has"&$select=subject
Anto Das An-Feld einer E-Mail-Nachricht, das als SMTP-Adresse, Anzeigename oder Alias angegeben ist.The to field of an email message, specified as an SMTP address, display name, or alias. 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:For more information about searchable email properties, KQL syntax, supported operators, and tips on searching, see the following articles:

  • [Durchsuchbar Eigenschaften in Exchange](https://docs.microsoft.com/de-DE/Exchange/policy-and-compliance/ediscovery/message-properties-and-search-operators#searchable-properties-in-exchange)[Searchable properties in Exchange](https://docs.microsoft.com/en-us/Exchange/policy-and-compliance/ediscovery/message-properties-and-search-operators#searchable-properties-in-exchange).
  • [Syntaxreferenz für die Keyword Query Language (KQL)](https://docs.microsoft.com/de-DE/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference)[Keyword Query Language (KQL) syntax reference](https://docs.microsoft.com/en-us/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference)
  • [Nachrichteneigenschaften und Suchoperatoren für In-Situ-eDiscovery in Exchange 2016](https://technet.microsoft.com/de-DE/library/dn774955(v=exchg.160).aspx)[Message properties and search operators for In-Place eDiscovery in Exchange 2016](https://technet.microsoft.com/en-us/library/dn774955(v=exchg.160).aspx)

Verwenden von $search in PersonensammlungenUsing $search on person collections

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.You can use the Microsoft Graph People API to retrieve the people who are most relevant to a user. Relevance is determined by the user’s communication and collaboration patterns and business relationships. The People API supports the $search query parameter.

Personensuchen werden sowohl für die Eigenschaft displayName als auch für die Eigenschaft emailAddress der Ressource vom Typ person ausgeführt.Searches on people occur on both the displayName and emailAddress properties of the person resource.

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.The following request does a search for a person named "Irene McGowen" in the displayName and emailAddress properties in each person in the people collection of the signed-in user. Da eine Person mit dem Namen „Irene McGowan“ für den angemeldeten Benutzer relevant ist, werden die Informationen für „Irene McGowan“ zurückgegeben.Because a person named "Irene McGowan" is relevant to the signed-in user, the information for "Irene McGowan" is returned.

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

Das folgende Beispiel zeigt die Antwort.The following example shows the response.

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.To learn more about the People API, see Get information about relevant people.

select-Parameterselect parameter

Verwenden Sie den $select-Abfrageparameter, um eine Reihe von Eigenschaften zurückzugeben, die sich von den Standardeigenschaften für eine einzelne Ressource oder eine Sammlung von Ressourcen unterscheidet.Use the $select query parameter to return a set of properties that are different than the default set for an individual resource or a collection of resources. Mit $select können Sie eine Teilmenge oder eine Obermenge der Standardeigenschaften angeben.With $select, you can specify a subset or a superset of the default properties.

Wenn Sie z. B. die Nachrichten des angemeldeten Benutzers abrufen, können Sie angeben, dass nur die Eigenschaften from und subject zurückgegeben werden:For example, when retrieving the messages of the signed-in user, you can specify that only the from and subject properties be returned:

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

Ausprobieren im Graph-TesterTry in Graph Explorer

Wichtig: Im Allgemeinen wird empfohlen, dass Sie $select verwenden, um die von einer Abfrage zurückgegebenen Eigenschaften auf diejenigen zu beschränken, die von Ihrer App benötigt werden.Important: In general, we recommend that you use $select to limit the properties returned by a query to those needed by your app. Dies gilt insbesondere für Abfragen, die möglicherweise ein großes Resultset zurückgeben.This is especially true of queries that might potentially return a large result set. Durch Beschränken der in den einzelnen Zeilen zurückgegebenen Eigenschaften werden die Netzwerklast reduziert und die Leistung Ihrer App verbessert.Limiting the properties returned in each row will reduce network load and help improve your app's performance.

In v1.0 geben einige Azure AD-Ressourcen, die von directoryObject abgeleitet werden, z.B. Benutzer und Gruppe eine begrenzte, standardmäßige Untermenge von Eigenschaften für Lesevorgänge zurück. Für diese Ressourcen müssen Sie $select verwenden, um Eigenschaften außerhalb des Standardsatzes zurückzugeben.In v1.0, some Azure AD resources that derive from directoryObject, like user and group, return a limited, default subset of properties on reads. For these resources, you must use $select to return properties outside of the default set.

skip-Parameterskip parameter

Verwenden Sie den $skip-Abfrageparameter zum Festlegen der Anzahl der Elemente, die am Anfang einer Sammlung übersprungen werden sollen. Die folgende Anforderung gibt beispielsweise Ereignisse für den Benutzer sortiert nach Erstellungsdatum zurück, beginnend mit dem 21. Ereignis in der Sammlung:Use the $skip query parameter to set the number of items to skip at the start of a collection. For example, the following request returns events for the user sorted by date created, starting with the 21st event in the collection:

GET  https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip=20

Ausprobieren im Graph-TesterTry in Graph Explorer

Hinweis: Einige Microsoft Graph-APIs, z. B. Outlook-Mail und Outlook-Kalender (Nachricht, Ereignis und Kalender), verwenden $skip zur Implementierung von Paging.Note: Some Microsoft Graph APIs, like Outlook Mail and Calendars (message, event, and calendar), use $skip to implement paging. Wenn Ergebnisse einer Abfrage mehrere Seiten umfassen, geben diese APIs eine @odata:nextLink-Eigenschaft mit einer URL zurück, die einen $skip-Parameter enthält.When results of a query span multiple pages, these APIs will return an @odata:nextLink property with a URL that contains a $skip parameter. Sie können diese URL verwenden, um die nächste Seite mit Ergebnissen zurückzugeben.You can use this URL to return the next page of results. Weitere Informationen finden Sie unter Paging.To learn more, see Paging.

skipToken-ParameterskipToken parameter

Einige Abfragen geben mehrere Seiten von Daten zurück, entweder aufgrund von serverseitigem Paging oder aufgrund der Verwendung des $top-Parameters, um die Seitengröße der Antwort zu begrenzen. Viele Microsoft Graph-APIs verwenden den skipToken-Abfrageparameter, um auf nachfolgende Seiten des Ergebnisses zu verweisen. Der $skiptoken-Parameter enthält ein undurchsichtiges Token, das auf die nächste Seite von Ergebnissen verweist und in der URL zurückgegeben wird, die in der @odata.nextLink-Eigenschaft in der Antwort bereitgestellt wird. Weitere Informationen finden Sie unter Paging.Some requests return multiple pages of data either due to server-side paging or due to the use of the $top parameter to limit the page size of the response. Many Microsoft Graph APIs use the skipToken query parameter to reference subsequent pages of the result. The $skiptoken parameter contains an opaque token that references the next page of results and is returned in the URL provided in the @odata.nextLink property in the response. To learn more, see Paging.

top-Parametertop parameter

Verwenden Sie den $top-Abfrageparameter, um die Seitengröße des Resultsets anzugeben.Use the $top query parameter to specify the page size of the result set.

Wenn mehr Elemente im Resultset verbleiben, enthält der Antworttext einen @odata.nextLink-Parameter.If more items remain in the result set, the response body will contain an @odata.nextLink parameter. Dieser Parameter enthält eine URL, die Sie verwenden können, um die nächste Seite mit Ergebnissen abzurufen.This parameter contains a URL that you can use to get the next page of results. Weitere Informationen finden Sie unter Paging.To learn more, see Paging.

Die folgende Anforderung gibt beispielsweise die ersten fünf Nachrichten im Postfach des Benutzers zurück:For example, the following request returns the first five messages in the user's mailbox:

GET https://graph.microsoft.com/v1.0/me/messages?$top=5

Ausprobieren im Graph-TesterTry in Graph Explorer

Fehlerbehandlung für AbfrageparameterError handling for query parameters

Einige Anforderungen geben eine Fehlermeldung zurück, wenn ein angegebener Abfrageparameter nicht unterstützt wird. $expand kann zum Beispiel nicht in der user/photo-Beziehung verwendet werden.Some requests will return an error message if a specified query parameter is not supported. For example, you cannot use $expand on the user/photo relationship.

https://graph.microsoft.com/beta/me?$expand=photo
{
    "error":{
        "code":"ExpandNotSupported",
        "message":"Expand is not allowed for property 'Photo' according to the entity schema.",
        "innerError":{
            "request-id":"1653fefd-bc31-484b-bb10-8dc33cb853ec",
            "date":"2017-07-31T20:55:01"
        }
    }
}

Beachten Sie jedoch, dass Abfrageparameter, die in einer Anforderung angegeben sind, im Hintergrund einen Fehler verursachen können.However, it is important to note that query parameters specified in a request might fail silently. Dies gilt für nicht unterstützte Abfrageparameter sowie für nicht unterstützte Kombinationen von Abfrageparametern.This can be true for unsupported query parameters as well as for unsupported combinations of query parameters. In diesen Fällen sollten Sie die von der Anforderung zurückgegebenen Daten überprüfen, um zu ermitteln, ob die angegebenen Abfrageparameter den gewünschten Effekt erzielt haben.In these cases, you should examine the data returned by the request to determine whether the query parameters you specified had the desired effect.