使用查询参数自定义响应Use query parameters to customize responses

Microsoft Graph 支持可选的查询参数,可用于指定和控制响应中返回的数据量。Microsoft Graph supports optional query parameters that you can use to specify and control the amount of data returned in a response. 对准确查询参数的支持因 API 操作不同而不同,并且可能会在 v1.0 和数据终结点之间不同,具体取决于 API。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.

提示

在 beta 终结点上,$ 前缀是可选的。On the beta endpoint, the $ prefix is optional. 例如,可使用 filter 来代替 $filterFor example, instead of $filter, you can use filter. 在 v1 终结点上, $前缀仅对 API 的一个子集是可选的。On the v1 endpoint, the $ prefix is optional for only a subset of APIs. 为简单起见, 如果使用 v1 终结点, 请始终包含$For simplicity, always include $ if using the v1 endpoint.

查询参数可以是 OData 系统查询选项,也可以是其他查询参数。Query parameters can be OData system query options or other query parameters.

OData 系统查询选项OData system query options

Microsoft Graph API 操作可以支持以下一个或多个 OData 系统查询选项。A Microsoft Graph API operation might support one or more of the following OData system query options. 这些查询选项与 OData V4 查询语言兼容。These query options are compatible with the OData V4 query language.

注意: OData 4.0 仅在 GET 操作中支持系统查询选项。Note: OData 4.0 supports system query options in only GET operations.

单击示例可以在 Graph 浏览器中试调用它们。Click the examples to try them in Graph Explorer.

名称Name 说明Description 示例Example
$count$count 检索匹配资源的总数。Retrieves the total count of matching resources. /me/messages?$top=2&$count=true
$expand$expand 检索相关资源。Retrieves related resources. /groups?$expand=members
$filter$filter 筛选结果(行)。Filters results (rows). /users?$filter=startswith(givenName,'J')
$format$format 返回指定媒体格式的结果。Returns the results in the specified media format. /users?$format=json
$orderby$orderby 对结果进行排序。Orders results. /users?$orderby=displayName desc
$search$search 返回基于搜索条件的结果。Returns results based on search criteria. /me/messages?$search=pizza
$select$select 筛选属性(列)。Filters properties (columns). /users?$select=givenName,surname
$skip$skip 对结果集建立索引。一些 API 也使用它来实现分页,并且可以与 $top 一起使用来手动对结果分页。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 设置结果的页面大小。Sets the page size of results. /users?$top=2

其他查询参数Other query parameters

名称Name 说明Description 示例Example
$skipToken$skipToken 从跨多页的结果集中检索下一页结果。(但某些 API 改为使用 $skip。)Retrieves the next page of results from result sets that span multiple pages. (Some APIs use $skip instead.) /users?$skiptoken=X%274453707402000100000017...

其他 OData URL 功能Other OData URL capabilities

下列 OData 4.0 功能是 URL 区段,不是查询参数。The following OData 4.0 capabilities are URL segments, not query parameters.

名称Name 说明Description 示例Example
$ref$ref 更新实体成员身份至集合。Updates entities membership to a collection. POST /groups/{id}/members/$ref
$value$value 检索或更新项的二进制值。Retrieves or updates the binary value of an item. GET /me/photo/$value

对查询参数进行编码Encoding query parameters

应对查询参数的值进行百分比编码。The values of query parameters should be percent-encoded. 许多 HTTP 客户端、浏览器和工具(如 Graph 浏览器)将在这方面帮助你。Many HTTP clients, browsers, and tools (such as the Graph Explorer) will help you with this. 如果查询失败,可能原因之一是未正确编码查询参数值。If a query is failing, one possible cause is failure to encode the query parameter values appropriately.

未编码的 URL 如下所示:An unencoded URL looks like this:

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

正确解码的 URL 如下所示:A properly encoded URL looks like this:

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

转义单引号Escaping single quotes

对于使用单引号的请求,如果任何参数值也包含单引号,则必须进行双转义;否则,由于语法无效,请求将失败。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. 在示例中,字符串值 let''s meet for lunch? 进行了单引号转义。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 参数count parameter

使用 $count 查询参数以包括集合中项总数的计数,以及从 Microsoft Graph 返回的数据值页。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.

例如,下面的请求返回当前用户的 contact 集合,以及 @odata.count 属性中 contact 集合内的项数。For example, the following request returns 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

在 Graph 浏览器中试调用Try in Graph Explorer

$count查询参数支持这些资源集合和它们的关系派生自directoryObjectThe $count query parameter is supported for these collections of resources and their relationships that derive from directoryObject:

expand 参数expand parameter

许多 Microsoft Graph 资源都会公开资源的已声明属性以及与其他资源的关系。Many Microsoft Graph resources expose both declared properties of the resource as well as its relationships with other resources. 这些关系也称为引用属性或导航属性,它们可以引用单个资源或资源集合。These relationships are also called reference properties or navigation properties, and they can reference either a single resource or a collection of resources. 例如,用户的邮件文件夹、管理者和直接下属都将作为关系公开。For example, the mail folders, manager, and direct reports of a user are all exposed as relationships.

通常情况下,可以在单个请求中查询资源属性或其关系之一,但不能同时查询。可以使用 $expand 查询字符串参数以包含结果中单个关系(导航属性)引用的扩展资源或集合。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.

以下示例在驱动器中获取根驱动器信息以及顶级子项: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

在 Graph 浏览器中试调用Try in Graph Explorer

使用一些资源集合,还可以添加 $select 参数,指定要在扩展资源中返回的属性。下面的示例执行与上一示例几乎相同的查询,不同之处在于使用 $select 语句将为扩展子项返回的属性限制为 idname 属性。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)

在 Graph 浏览器中试调用Try in Graph Explorer

注意: 并不是所有关系和资源都支持 $expand 查询参数。例如,可以扩展用户的 directReportsmanagermemberOf 关系,但无法扩展其 eventsmessagesphoto 关系。并非所有资源或关系都支持对扩展项使用 $selectNote: 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.

使用从 directoryObject 派生的 Azure AD 资源(如usergroup),$expand 仅支持 beta,并且通常最多为扩展关系返回 20 个项。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 参数filter parameter

使用 $filter 查询参数,以仅检索集合的子集。Use the $filter query parameter to retrieve just a subset of a collection. $filter查询参数还可以用于检索关系,例如members、memberOf、transitiveMembers和transitiveMemberOf。The $filter query parameter can also be used to retrieve relationships like members, memberOf, transitiveMembers, and transitiveMemberOf. 例如,获取我所属的所有安全组。For example, get all the security groups I'm a member of.

以下例子可用于查找显示名称以子母“J”开头的用户,请使用 startswithThe following example can be used 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')

在 Graph 浏览器中试调用Try in Graph Explorer

$filter 运算符的支持因 Microsoft Graph API 不同而异。Support for $filter operators varies across Microsoft Graph APIs. 通常支持下列逻辑运算符:The following logical operators are generally supported:

  • 等于 (eq)equals (eq)
  • 在 (in) 中in (in)
  • 不等于 (ne)not equals (ne)
  • 大于 (gt)greater than (gt)
  • 大于或等于 (ge)greater than or equals (ge)
  • 小于 (lt),小于或等于 (le)less than (lt), less than or equals (le)
  • 且 (and)and (and)
  • 或 (or)or (or)
  • 非 (not)not (not)

通常支持 startswith 字符串运算符。The startswith string operator is often supported. 某些 API 支持 any lambda 运算符。The any lambda operator is supported for some APIs.

注意: 在同一查询中同时使用 $filter$orderby 获取消息时,必须以特定的方式指定属性Note: You must specify properties in certain ways when using both $filter and $orderby in the same query to get messages.

有关一些用法示例的信息,请参阅下表。For some usage examples, see the following table. 如需了解 $filter 语法的更多详情,请参阅 OData 协议For more details about $filter syntax, see the OData protocol.

下表展示了一些使用 $filter 查询参数的示例。The following table shows some examples that use the $filter query parameter.

注意: 单击示例可以在 Graph 浏览器中试调用。Note: Click the examples to try them in Graph Explorer.

说明Description 示例Example
跨多个属性搜索名为 Mary 的用户。Search 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')
获取 2017 年 7 月 1 日之后开始的所有登录用户的事件。Get 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'
获取登录用户收到的来自特定地址的所有电子邮件。Get 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'
获取登录用户在 2017 年 4 月收到的所有电子邮件。Get 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
获取登录用户收件箱中的所有未读邮件。Get all unread mail in the signed-in user's Inbox. https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages?$filter=isRead eq false
列出组织中的所有 Microsoft 365 组。List all Microsoft 365 groups in an organization. https://graph.microsoft.com/v1.0/groups?$filter=groupTypes/any(c:c+eq+'Unified')
使用 OData 转换可实现显示名称以“ a”开头(包括返回的对象数)的组中的临时成员资格。Use OData cast to get transitive membership in groups with a display name that starts with 'a' including a count of returned objects. https://graph.microsoft.com/beta/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a')

注意: 请阅读特定目录对象(Azure AD 资源)的文档,了解有关 $filter 运算符支持的详细信息。Note: Please read the documentation for the specific directory objects (Azure AD resources) to learn more about $filter operator support. 所有 Microsoft Graph 资源目前均不支持 contains 字符串运算符。The contains string operator is currently not supported on any Microsoft Graph resources.

format 参数format parameter

使用 $format 查询参数,指定 Microsoft Graph 返回的项的媒体格式。Use the $format query parameter to specify the media format of the items returned from Microsoft Graph.

例如,下面的请求以 json 格式返回组织中的用户: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

在 Graph 浏览器中试调用Try in Graph Explorer

注意:$format 查询参数支持许多格式(例如,atom、xml 和 json),但可能无法返回所有格式的结果。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 参数orderby parameter

使用 $orderby 查询参数指定从 Microsoft Graph 返回的项的排序顺序。Use the $orderby query parameter to specify the sort order of the items returned from Microsoft Graph.

例如,以下请求返回按用户显示名称进行排序的组织中的用户: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

在 Graph 浏览器中试调用Try in Graph Explorer

还可以按复杂类型实体进行排序。下面的请求获取邮件,并按 from 属性的 address 字段(复杂类型为 emailAddress)进行排序: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

在 Graph 浏览器中试调用Try in Graph Explorer

若要以升序或降序对结果进行排序,请向字段名称追加 ascdesc,并用空格隔开。例如,?$orderby=name%20descTo 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.

通过一些 API,可以对多个属性的结果进行排序。With some APIs, you can order results on multiple properties. 例如,以下请求首先按发件人名称以降序(Z 到 A)排序用户收件箱中的邮件,然后按主题以升序(默认)排序邮件。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

在 Graph 浏览器中试调用Try in Graph Explorer

注意: 如果指定 $filter,服务器会推断结果的排序顺序。Note: When you specify $filter the server will infer a sort order for the results. 如果同时使用 $orderby$filter 获取消息,因为服务器始终会推断 $filter 结果的排序顺序,必须以特定的方式指定属性If you use both $orderby and $filter to get messages, because the server always infers a sort order for the results of a $filter, you must specify properties in certain ways.

下面的示例展示了如何按 subjectimportance 属性筛选查询,再按 subjectimportancereceivedDateTime 属性进行降序排序。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

在 Graph 浏览器中试调用Try in Graph Explorer

注意: 对于以下 AD 资源及其从 directoryObject 派生的关系,在 Beta 终结点上支持组合 $orderby$filter 查询参数:Note: Combining $orderby and $filter query parameters is supported on the beta endpoint for the following AD resources and their relationships that derive from directoryObject:

要同时使用 $orderby$filter,需要:To use $orderby and $filter together, you need to:

  • $count=true 添加到查询参数Add $count=true to the query parameters
  • 添加 ConsistencyLevel: eventual 请求标题Add ConsistencyLevel: eventual request header

有关更多信息,请参见可选用户查询参数See optional user query parameters for more information.

search 参数search parameter

使用 $search 查询参数限制与搜索条件匹配的请求结果。Use the $search query parameter to restrict the results of a request to match a search criterion.

对 message 集合使用 $searchUsing $search on message collections

可根据特定邮件属性值搜索邮件。You can search messages based on a value in specific message properties. 搜索结果按邮件发送日期和时间进行排序。The results of the search are sorted by the date and time that the message was sent. $search 请求最多可返回 250 个结果。A $search request returns up to 250 results.

如果确实要搜索邮件,且仅指定值,而未指定特定邮件属性,搜索依据为默认搜索属性 fromsubjectbodyIf 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.

下面的示例返回登录用户收件箱中三个默认搜索属性中有任意一个包含“pizza”的所有邮件: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"

在 Graph 浏览器中试调用Try in Graph Explorer

也可以指定下表中的邮件属性名来搜索邮件,这些属性名可由关键字查询语言 (KQL) 语法识别。Alternatively, you can search messages by specifying message property names in the following table, that are recognized by the Keyword Query Language (KQL) syntax. 这些属性名对应于 Microsoft Graph message 实体中定义的属性。These property names correspond to properties defined in the message entity of Microsoft Graph. Outlook 和其他 Microsoft 365 应用程序(如 SharePoint)支持 KQL 语法,从而为数据存储提供了方便使用的公共发现域。Outlook and other Microsoft 365 applications such as SharePoint support KQL syntax, providing the convenience of a common discovery domain for their data stores.

可搜索的电子邮件属性Searchable email property 说明Description 示例Example
attachmentattachment 电子邮件附件的文件名。The names of files attached to an email message. me/messages?$search="attachment:api-catalog.md"
bccbcc 电子邮件的 bcc 字段,可指定为 SMTP 地址、显示名称或别名。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
bodybody 电子邮件正文。The body of an email message. me/messages?$search="body:excitement"
cccc 电子邮件的 cc 字段,可指定为 SMTP 地址、显示名称或别名。The cc field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="cc:danas"&$select=subject,ccRecipients
fromfrom 电子邮件的发件人,可指定为 SMTP 地址、显示名称或别名。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;否则,为 false。True if an email message contains an attachment that is not an inline attachment, false otherwise. me/messages?$search="hasAttachments:true"
importanceimportance 发件人在发送邮件时可以指定的电子邮件重要性。The importance of an email message, which a sender can specify when sending a message. 可取值包括 lowmediumhighThe possible values are low, medium, or high. me/messages?$search="importance:high"&$select=subject,importance
Kindkind 邮件类型。The type of message. 可取值包括 contactsdocsemailfaxesimjournalsmeetingsnotespostsrssfeedstasksvoicemailThe possible values are contacts, docs, email, faxes, im, journals, meetings, notes, posts, rssfeeds, tasks, or voicemail. me/messages?$search="kind:voicemail"
participantsparticipants 电子邮件的 fromtoccbcc 字段,可指定为 SMTP 地址、显示名称或别名。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"
receivedreceived 收件人接收电子邮件的日期。The date that an email message was received by a recipient. me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime
recipientsrecipients 电子邮件的 toccbcc 字段,可指定为 SMTP 地址、显示名称或别名。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
sentsent 发件人发送电子邮件的日期。The date that an email message was sent by the sender. me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime
sizesize 邮件大小(以字节为单位)。The size of an item in bytes. me/messages?$search="size:1..500000"
subjectsubject 电子邮件主题行中的文本。The text in the subject line of an email message. .. me/messages?$search="subject:has"&$select=subject
toto 电子邮件的 to 字段,可指定为 SMTP 地址、显示名称或别名。The to field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="to:randiw"&$select=subject,toRecipients

若要详细了解 可搜索的电子邮件属性、KQL 语法、受支持的运算符和搜索技巧,请参阅以下文章:For more information about searchable email properties, KQL syntax, supported operators, and tips on searching, see the following articles:

对 person 集合使用 $searchUsing $search on person collections

可以使用 Microsoft Graph People API 检索与用户相关度最高的人员。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. People API 支持 $search 查询参数。The People API supports the $search query parameter. $search 请求最多可返回 250 个结果。A $search request returns up to 250 results.

人员搜索就是按 person 资源的 displayNameemailAddress 属性进行搜索。Searches on people occur on both the displayName and emailAddress properties of the person resource.

以下请求在已登录用户的人员集合中的每个人员的 displayNameemailAddress 属性中,为名为“Irene McGowen”的人员执行搜索。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. 由于一个名为“Irene McGowan”的人员与登录用户相关,因此返回了“Irene McGowan”的信息。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"

以下示例显示了相应的响应。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"
           }
       }
   ]
}

若要了解有关 People API 的详细信息,请参阅获取相关人员的信息To learn more about the People API, see Get information about relevant people.

在目录对象集合上使用 $searchUsing $search on directory object collections

可以使用$search 查询参数根据搜索条件限制结果,比如查找由空格、大小写和字符类型(数字和特殊字符)分隔的字符串中的单词。You can use the $search query parameter to restrict results based on a search criterion such as looking for words in strings delimited by spaces, casing, and character types (numbers and special characters). 标记的搜索支持仅适用于 displayName 和说明字段。The tokenized search support works only on the displayName and description fields. 任何字段都可以放入 $search中,而不是 displayName 的字段,说明 默认 $filter startswith 行为。Any field can be put in $search, fields other than displayName and description defaults to $filter startswith behavior. 例如:For example:

https://graph.microsoft.com/beta/groups/?$search="displayName:OneVideo"

这将查找显示名称看起来像 "OneVideo" 的所有组。This looks for all groups with display names that look like "OneVideo". 也可与$search配合使用$filter$search can be used together with $filter as well. 例如:For example:

https://graph.microsoft.com/beta/groups/?$filter=mailEnabled eq true&$search="displayName:OneVideo"

这将查找显示名称类似于“OneVideo”的所有启用邮件的组。This looks for all mail-enabled groups with display names that look like "OneVideo". 结果是根据逻辑结合("AND")和$filter整个查询$search来限制。The results are restricted based on a logical conjunction (an "AND") of the $filter and the entire query in the $search. 搜索文本基于大小写进行标记,但是匹配以不区分大小写的方式执行。The search text is tokenized based on casing, but matches are performed in a case-insensitive manner. 例如,“OneVideo”将被分割成两个输入令牌“one”和“video”,但是匹配不区分大小写的属性。For example, "OneVideo" would be split into two input tokens "one" and "video", but matches properties in insensitive to case.

搜索的语法遵循以下规则:The syntax of search follows these rules:

  • 通用格式: $search = "clause1" [AND |或] "[clauseX]"。Generic format: $search="clause1" [AND | OR] "[clauseX]".
  • 支持任何子句。Any number of clauses is supported. 支持适用于优先级的括号。Parentheses for precedence is also supported.
  • 每个子句的语法The syntax for each clause is :.
  • 必须在子句中指定属性名称。The property name must be specified in clause. 可以在中使用的任何属性$filter也可以在内使用 $searchAny property that can be used in $filter can also be used inside $search. 根据属性的不同,如果属性不支持搜索,那么搜索行为要么是“search”,要么是“start with”。Depending on the property, the search behavior is either "search" or "startswith" if search is not supported on the property.
  • 必须将完整子句部分置于双引号内。The whole clause part must be put inside double quotes.
  • 必须将逻辑运算符 "AND" 和 "OR" 置于双引号之外。Logical operator 'AND' 'OR' must be put outside double quotes. 它们必须处于大写形式。They must be in upper case.
  • 考虑到整个子句部分需要放在双引号内,如果包含双引号和反斜杠,则需要使用反斜杠对其进行转义。Given that the whole clause part needs to be put inside double quotes, if contains double quote and backslash, it needs to be escaped by backslash. 无需转义其他字符。No other characters need to be escaped.

下表显示了一些示例。The table below shows some examples.

对象类Object class 说明Description 示例Example
用户User 通讯簿显示用户的名称。Address book display name of the user. https://graph.microsoft.com/beta/users?$search="displayName:Guthr"
用户User 通讯簿显示用户的名称或邮件。Address book display name or mail of the user. https://graph.microsoft.com/beta/users?$search="displayName:Guthr" OR "mail:Guthr"
GroupGroup 通讯簿显群组的名称或说明。Address book display name or description of the group. https://graph.microsoft.com/beta/groups?$search="description:One" AND ("displayName:Video" OR "displayName:Drive")
GroupGroup 通讯簿在启用邮件组上显示名称。Address book display name on a mail enabled group. https://graph.microsoft.com/beta/groups?$filter=mailEnabled eq true&$search="displayName:OneVideo"

你提供的字符串输入 $search以及上面指出的可搜索属性都按空格、不同的大小写和字符类型(数字和特殊字符)划分为多个部分。Both the string inputs you provide in $search, as well as the searchable properties indicated above, are split up into parts by spaces, different casing, and character types (numbers and special characters).

select 参数select parameter

使用 $select 查询参数返回一组不同于单个资源的默认集或资源集合的属性。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. 使用 $select,可以指定默认属性的子集或超集。With $select, you can specify a subset or a superset of the default properties.

例如,检索登录用户的邮件时,可以指定仅返回 fromsubject 属性: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

在 Graph 浏览器中试调用Try in Graph Explorer

重要说明: 一般来说,建议使用 $select 将查询返回的属性限制为应用所需的属性。Important: In general, we recommend that you use $select to limit the properties returned by a query to those needed by your app. 这对于可能返回大型结果集的查询尤为有用。This is especially true of queries that might potentially return a large result set. 限制每行返回的属性将减少网络负载并帮助提升应用的性能。Limiting the properties returned in each row will reduce network load and help improve your app's performance.

v1.0 中,从 directoryObject 派生的一些 Azure AD 资源(如 usergroup)在读取时返回受限的默认属性子集。对于这些资源,必须使用 $select 将属性返回到默认集之外。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 参数skip parameter

使用 $skip 查询参数设置要在集合开头跳过的项数。例如,以下请求返回按照创建日期排序的用户的事件,从集合中的第 21 个事件开始: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

在 Graph 浏览器中试调用Try in Graph Explorer

注意: 一些 Microsoft Graph API 使用 $skip 实现分页,如 Outlook 邮件和日历(messageeventcalendar)。Note: Some Microsoft Graph APIs, like Outlook Mail and Calendars (message, event, and calendar), use $skip to implement paging. 当查询结果跨多个页面时,这些 API 会返回 @odata:nextLink 属性,具有包含 $skip 参数的 URL。When results of a query span multiple pages, these APIs will return an @odata:nextLink property with a URL that contains a $skip parameter. 可以使用此 URL 返回下一页结果。You can use this URL to return the next page of results. 若要了解详细信息,请参阅分页To learn more, see Paging.

skipToken 参数skipToken parameter

由于服务器端分页或由于使用 $top 参数来限制响应的页面大小,致使一些请求返回多页数据。许多 Microsoft Graph API 使用 skipToken 查询参数来引用结果的后续页面。$skiptoken 参数包含引用下一页结果的不透明令牌,并在响应的 @odata.nextLink 属性中提供的 URL 中返回。若要了解详细信息,请参阅分页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 参数top parameter

使用 $top 查询参数指定结果集的页面大小。Use the $top query parameter to specify the page size of the result set.

如果结果集中还剩余多个项目,则响应正文将包含 @odata.nextLink 参数。If more items remain in the result set, the response body will contain an @odata.nextLink parameter. 此参数包含可用于获取下一页结果的 URL。This parameter contains a URL that you can use to get the next page of results. 若要了解详细信息,请参阅分页To learn more, see Paging.

$top 接受的最小值为 1,接受的最大值为 999。$top accepts a minimum value of 1 and a maximum value of 999 (inclusive).

例如,以下请求返回用户邮箱中的前 5 封邮件: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

在 Graph 浏览器中试调用Try in Graph Explorer

查询参数的错误处理Error handling for query parameters

如果不支持指定的查询参数,某些请求将返回错误消息。例如,不能对 user/photo 关系使用 $expandSome 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"
        }
    }
}

但是,值得注意的是请求中指定的查询参数可能会自行失败。However, it is important to note that query parameters specified in a request might fail silently. 不支持的查询参数以及不支持的查询参数组合的情况就是如此。This can be true for unsupported query parameters as well as for unsupported combinations of query parameters. 在这些情况下,应检查请求返回的数据,以确定指定的查询参数是否具有所需的效果。In these cases, you should examine the data returned by the request to determine whether the query parameters you specified had the desired effect.

另请参阅See also