使用查询参数自定义响应

Microsoft Graph 支持查询参数,可用于指定和控制响应中返回的数据量。 对确切查询参数的支持因 API 操作而异,并且根据 API,v1.0beta 终结点可能有所不同。

提示

beta 终结点上 $ ,前缀是可选的。 例如,可使用 filter 来代替 $filter。 在 v1.0 终结点上 $ ,前缀仅对于一部分 API 是可选的。 为简单起见,始终包括 $ 所有版本

查询参数可以是 OData 系统查询选项,也可以是其他查询参数。

OData 系统查询选项

Microsoft Graph API 操作可以支持以下一个或多个 OData 系统查询选项。 这些查询选项与 OData V4 查询语言 兼容,并且仅在 GET 操作中受支持。

单击示例可以在 Graph 浏览器中试调用它们。

名称 说明 示例
$count 检索匹配资源的总数。 /me/messages?$top=2&$count=true
$expand 检索相关资源。 /groups?$expand=members
$filter 筛选结果(行)。 /users?$filter=startswith(givenName,'J')
$format 返回指定媒体格式的结果。 /users?$format=json
$orderby 对结果进行排序。 /users?$orderby=displayName desc
$search 返回基于搜索条件的结果。 /me/messages?$search=pizza
$select 筛选属性(列)。 /users?$select=givenName,surname
$skip 结果集中的索引。 此外,某些 API 也用于实现分页,并且可以与 $top 一起使用来手动对结果进行分页。 /me/messages?$skip=11
$top 设置结果的页面大小。 /users?$top=2

若要了解 API 及其属性支持的 OData 系统查询选项,请参阅资源页中的“属性”表,以及 API 的 LIST 和 GET 操作的“可选查询参数”部分。

其他查询参数

名称 说明 示例
$skipToken 从跨多页的结果集中检索下一页结果。 (某些 API 改用 $skip 。) /users?$skiptoken=X%274453707402000100000017...

其他 OData URL 功能

下列 OData 4.0 功能是 URL 区段,不是查询参数。

名称 说明 示例
$count 检索集合的整数总计。 GET /users/$count
GET /groups/{id}/members/$count

获取用户计数
$ref 更新实体成员身份至集合。 POST /groups/{id}/members/$ref

将成员添加到组
$value 检索或更新项的二进制值。 GET /me/photo/$value

获取用户、组或团队的照片
$batch 将多个 HTTP 请求合并到批处理请求中。 POST /$batch

JSON 批处理

对查询参数进行编码

查询参数的值应按照 RFC 3986 进行百分比编码。 例如,查询字符串中的所有保留字符都必须采用百分比编码。 许多 HTTP 客户端、浏览器和工具 ((如 Graph 资源管理器 )) 为你处理此编码。 如果查询失败,一个可能的原因是无法正确编码查询参数值。 在某些情况下,需要对值进行双重编码。

注意

v1.0 终结点上的表达式中的$search编码和 (&) 符号存在一个已知问题。 有关此问题和建议的解决方法的详细信息,请参阅 已知问题:目录对象的$search编码和和 (&) 字符失败

例如,未编码的 URL 如下所示:

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

正确百分比编码的 URL 如下所示:

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

双重编码的 URL 如下所示:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith%28givenName%2C%20%27J%27%29

转义单引号

对于使用单引号的请求,如果任何参数值还包含单引号,则必须进行双引号转义;否则,请求由于语法无效而失败。 在示例中,字符串值 let''s meet for lunch? 进行了单引号转义。

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

count 参数

使用 $count 查询参数检索集合中的项总数或与表达式匹配的项总数。 可以通过以下方式使用 $count

  1. 作为查询字符串参数,其语法 $count=true 包括集合中项总数的计数以及从 Microsoft Graph 返回的数据值页。 例如,users?$count=true
  2. 作为 URL 段,仅检索集合的整数总计。 例如,users/$count
  3. 在具有等式运算符的 $filter 表达式中,检索筛选属性为空集合的数据集合。 请参阅 使用 $filter 查询参数筛选对象的集合

注意

  1. 在派生自 directoryObject 的资源上,仅在高级查询中支持 $count。 请参阅 目录对象的高级查询功能
  2. Azure AD B2C 租户不支持使用$count

例如,以下请求返回当前用户的联系人集合,以及 @odata.count 属性中的联系人集合中的项目数。

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

对于目录对象(即派生自 directoryObject 的资源), $count 查询参数仅在 高级查询中受支持。

expand 参数

许多 Microsoft Graph 资源都会公开资源的已声明属性以及该资源与其他资源的关系。 这些关系也称为引用属性或导航属性,它们可以引用单个资源或资源集合。 例如,用户的邮件文件夹、管理者和直接下属都将作为关系公开。

可以使用 $expand 查询字符串参数以包含结果中单个关系(导航属性)引用的扩展资源或集合。 对于某些 API,一个请求中只能扩展一个关系。

以下示例在驱动器中获取根驱动器信息以及顶级子项:

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

对于某些资源集合,还可以通过添加 $select 参数来指定要在扩展的资源中返回的属性。 以下示例执行与上一示例相同的查询,但使用 语句 $select 将为展开的子项返回的属性限制为 id名称 属性。

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

注意

  • 并不是所有关系和资源都支持 $expand 查询参数。 例如,可以展开一个用户的 directReportsmanagermemberOf 关系,但不能展开其 eventsmessagesphotos 关系。 并非所有资源或关系都支持在扩展项上使用 $select

  • 使用 Microsoft从 directoryObject 派生的 Entra 资源(如用户$expand)通常最多返回 20 个扩展关系的项目,并且没有@odata.nextLink。 有关详细信息,请参阅 查询参数限制

  • 高级查询当前不支持$expand

filter 参数

使用 $filter 查询参数,以仅检索集合的子集。 有关使用 $filter的指导,请参阅 使用 $filter 查询参数筛选对象的集合

format 参数

使用 $format 查询参数,指定 Microsoft Graph 返回的项的媒体格式。

例如,下面的请求以 json 格式返回组织中的用户:

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

注意

查询 $format 参数支持多种格式 (,例如 atomxmljson) 但结果可能不会以所有格式返回。

orderby 参数

使用 $orderby 查询参数指定从 Microsoft Graph 返回的项的排序顺序。 默认顺序为升序。

例如,以下请求按升序返回组织中按显示名称排序的用户:

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

某些 API 支持按复杂类型实体进行排序。 以下请求获取邮件,并按 from 属性的地址字段(属于复杂类型 emailAddress)对其进行排序:

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

若要按升序或降序对结果进行排序,请将 或 desc 追加asc到字段名称(用空格分隔);例如, ?$orderby=name desc (未编码) , ?$orderby=name%20desc (编码) URL。 如果未指定排序顺序,则会推断默认升序。

通过一些 API,可以对多个属性的结果进行排序。 例如,以下请求首先按发件人名称以降序(Z 到 A)排序用户收件箱中的邮件,然后按主题以升序(默认)排序邮件。

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

注意

指定 $filter时,服务会推断结果的排序顺序。 如果同时使用 $orderby$filter 获取消息,因为服务器始终会推断 $filter 结果的排序顺序,必须以特定的方式指定属性

下面的示例展示了如何按 subjectimportance 属性筛选查询,再按 subjectimportancereceivedDateTime 属性进行降序排序。

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

注意

目录对象支持组合 $orderby$filter 查询参数。 请参阅 目录对象中的高级查询功能

search 参数

使用 $search 查询参数限制与搜索条件匹配的请求结果。 它的语法和行为因 API 操作而异。 若要查看不同资源之间 $search 的语法,请参阅 使用$search查询参数匹配搜索条件

select 参数

$select使用查询参数可返回资源的一部分属性。 使用 $select,可以指定默认属性的子集或超集。

在不使用 来限制属性数据量的情况下 $select 发出 GET 请求时,Microsoft Graph 包含 一个 @microsoft.graph.tips 属性,该属性提供与 $select 以下消息类似的最佳做法建议:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

例如,检索登录用户的邮件时,可以指定仅返回 fromsubject 属性:

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

重要

一般来说,建议使用 $select 将查询返回的属性限制为应用所需的属性。 这对于可能返回大型结果集的查询尤为有用。 限制每行返回的属性将减少网络负载并帮助提升应用的性能。

v1.0 中,某些Microsoft从 directoryObject 派生的 Entra 资源(如 用户)在读取时返回有限的默认属性子集。 对于这些资源,必须使用 $select 返回默认集之外的属性。

skip 参数

$skip使用查询参数可设置集合开始时要跳过的项数。 例如,以下请求返回按创建日期排序的用户的事件,从集合中的第 21 个事件开始:

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

某些Microsoft Graph API, 如 Outlook 邮件和日历(邮件事件日历)使用 $skip 实现分页。 当查询结果跨越多个页面时,这些 API 返回 包含参数的 URL$skip 的 @odata.nextLink 属性。 可以使用此 URL 返回下一页结果。 若要了解详细信息,请参阅分页

用户应用程序目录对象不支持 $skip

skipToken 参数

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

注意

如果对目录对象的查询使用 OData Count(在查询字符串中添加 $count=true ),则 @odata.count 属性仅在第一页中显示。

默认情况下,针对目录对象的高级查询所需的 ConsistencyLevel 标头不包含在后续页面请求中。 必须在后续页面中显式设置它。

top 参数

$top使用查询参数指定要包含在结果中的项数。

如果结果集中保留更多项,则响应正文包含 @odata.nextLink 参数。 此参数包含可用于获取下一页结果的 URL。 若要了解详细信息,请参阅分页

最小值为 $top 1,最大值取决于相应的 API。

例如,以下列表 请求 返回用户邮箱中的前五条消息:

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

注意

默认情况下,针对目录对象的高级查询所需的 ConsistencyLevel 标头不包含在后续页面请求中。 必须在后续页面中显式设置它。

查询参数的错误处理

如果不支持指定的查询参数,某些请求将返回错误消息。 例如,不能对user/photo关系使用 $expand

https://graph.microsoft.com/v1.0/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"
        }
    }
}

但是,有时请求中指定的查询参数会以无提示方式失败。 例如,对于不支持的查询参数和不受支持的查询参数组合。 在这些情况下,应检查请求返回的数据,以确定指定的查询参数是否具有所需的效果。