通过

使用查询参数自定义Microsoft Graph 响应

查询参数通过精确控制返回的数据，帮助你优化Microsoft图形 API响应。 可以使用查询参数来以下作，而不是检索所有可用属性和数据：

  • 筛选结果以仅获取所需的记录
  • 选择特定属性以减小响应大小并提高性能
  • 对数据进行排序和分页，以提供更好的用户体验
  • 展开相关资源以在单个请求中获取连接数据

本文介绍如何有效地使用 OData 系统查询选项 和其他Microsoft Graph 查询参数。 你将了解语法、查看实际示例，并发现构建可增强应用程序性能的高效查询的最佳做法。

对特定查询参数的支持因 API作而异，并且 v1.0 和 beta 终结点可能有所不同。

提示

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

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 ：

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

注意

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

例如，以下请求在 @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 查询参数。 例如，可以展开用户的 directReports、 manager 和 memberOf 关系，但不能扩展其 事件、 消息或 照片 关系。 并非所有资源或关系都支持在扩展项上使用 $select。

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

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

筛选器

$filter使用查询参数仅获取集合的子集。 有关使用 $filter的指导，请参阅 使用 $filter 查询参数筛选对象的集合。

格式

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

例如，以下请求以 JSON 格式返回组织中的用户：

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

注意

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

排序方式

使用 $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 结果的排序顺序，必须以特定的方式指定属性。

下面的示例展示了如何按 subject 和 importance 属性筛选查询，再按 subject、importance 和 receivedDateTime 属性进行降序排序。

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 查询参数匹配搜索条件。

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",

例如，在获取已登录用户的消息时，可以指定仅返回 from 和 subject 属性：

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

重要

建议使用 $select 将查询返回的属性限制为应用所需的属性。 对于可能返回大型结果集的查询尤其如此。 限制每行中返回的属性可减少网络负载并提高应用的性能。

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

跳过

$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使用查询参数指定要包含在结果中的项数。

如果结果集中保留更多项，则响应正文包含 @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"
        }
    }
}

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

相关内容