通过

使用查询参数自定义响应

  • 项目

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

提示

在 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 查询参数。 例如，可以展开一个用户的 directReports、 manager和 memberOf 关系，但不能展开其 events、 messages或 photos 关系。 并非所有资源或关系都支持在扩展项上使用 $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 参数支持多种格式 (，例如 atom、 xml和 json) 但结果可能不会以所有格式返回。

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

下面的示例展示了如何按 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 查询参数限制与搜索条件匹配的请求结果。 它的语法和行为因 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",

例如，检索登录用户的邮件时，可以指定仅返回 from 和 subject 属性：

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

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

相关内容