Microsoft Graph - 查询参数

上一篇我们介绍了Microsoft Graph的查询语法。本篇我们开始介绍Microsoft Graph中的请求可用的查询参数。由于篇幅有限，所有的查询参数可以访问此页面查看。

Filter

Filter是我们使用的较普遍的一个查询参数。即从总的结果集中通过一些条件筛选出结果的子集。

语法

<baseGraphQuery>?$filter=<conditions>

示例

获取显示名以大写字母A开头的用户：

https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,’A’)

Select

Select允许获取默认属性集合的子集或超集。这对当我们获取了相当多数量的默认属性的记录集时特别有帮助。通过限制返回属性的数量(只保留我们的应用需要的那些)以降低内存和网络带宽占用。

语法

<baseGraphQuery>?$select=<property1>,<property2>,…,<propertyN>

示例

获取登录用户的OneDrive网站中文件的名称、大小和网络URL：

https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name,size,webUrl

OrderBy

OrderBy会对返回的结果以指定的属性进行排序。某些API支持多属性排序。

语法

<baseGraphQuery>?$orderby=<property1>,<property2>,…,<propertyN>

示例

获取当前登录用户的联系人并以生日排序(默认升序)：

https://graph.microsoft.com/v1.0/me/contacts?$orderby=birthday

另外，我们可以通过在属性名后面添加“ asc”或“ desc”来指定升序或者降序。

示例

获取当前登录用户的联系人并以生日降序排列：

https://graph.microsoft.com/v1.0/me/contacts?$orderby=birthday

Format

指定Microsoft Graph的端点可以提供以不同格式返回结果的能力。这可能包括可下载的CSV文件、JSON或其他流行的格式。支持格式化查询参数的端点默认会有一个格式，但是允许我们指定其他支持的格式。

语法

<baseGraphQuery>?$format=<formatValue>

示例

获取Office 365组活动的报告的JSON格式：

https://graph.microsoft.com/beta/reports/getOffice365GroupsActivityGroupCounts(period=’D7′)?$format=application/json

获取Office 365组活动的报告的CSV格式：

https://graph.microsoft.com/beta/reports/getOffice365GroupsActivityGroupCounts(period=’D7′)?$format=text/csv

注意：本示例需要以Office 365全局管理员或Azure AD管理员的身份登录Graph资源管理器进行测试。

Count

当我们的应用需要知道结果集的数量时，Count是一个很有用的查询参数。结果的数量将会以属性的形式返回。

语法

<baseGraphQuery>?$count=<boolean>

示例

获取当前登录用户联系人的数量：

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

Top

Microsoft Graph查询的结果集有时可能会多于一个响应可以返回的数量。这时我们可以指定Top参数来设置返回结果的最大值。

语法

<baseGraphQuery>?$top=<int>

示例

获取当前登录用户OneNote的前两个notebook：

https://graph.microsoft.com/v1.0/me/onenote/notebooks?$top=2

Skip

Skip是另一个从Microsoft Graph获取分页结果时常使用的查询参数。@odata.nextlink往往会包含一个Skip或SkipToken查询参数。Skip是用来跳过查询结果集的前N个结果的。

语法

<baseGraphQuery>?$skip=<int>

示例

获取当前登录用户从第11封邮件起的邮件列表：

https://graph.microsoft.com/v1.0/me/messages?$skip=10

Search

Search跟Filter类似，用来从调用返回的结果集中获取子集。在自由文本搜索表达式的成本上，Search在message和person资源上有优势。

语法

<baseGraphQuery>?$search=<searchCriteria>

示例

获取当前登录用户邮件主体中包含Contoso这个词的邮件列表：

https://graph.microsoft.com/v1.0/me/messages?$search=”body:Contoso”

Expand

很多时候Microsoft Graph上的实体相互之间是有关联的。使用Expand查询参数可以返回复杂数据类型或关联实体的更多信息。

语法

<baseGraphQuery>?$expand=<property>

示例

获取当前用户的经理的扩展信息：

https://graph.microsoft.com/beta/me?$expand=manager

注意：本示例使用了beta版的端点，User实体只在beta版API中支持Expand查询参数。