培训
学习路径
了解 ASP.NET Core 开发的 Microsoft Graph 方案 - Training
该学习路径包含实践练习,展示了如何在使用 Microsoft Graph API 的 ASP.NET Core 应用中执行常见任务,例如显示用户的电子邮件、访问日历事件,以及下载和上传文件。
适用于:OneDrive 上的消费者笔记本 | Microsoft 365 上的企业级笔记本
若要使用 Microsoft Graph OneNote API 获取 OneNote 内容和结构,请向目标终结点发送 GET 请求。 例如:
GET ../onenote/pages/{id}
如果请求成功,Microsoft Graph 会返回 200 OK
HTTP 状态代码以及请求的实体或内容。 OneNote 实体作为符合 OData 版本 4.0 规范的 JSON 对象返回。
通过使用查询字符串选项,可以筛选查询并提高性能。
备注
如果正在构建支持以下方案之一的解决方案,则会达到 OneNote API 限制:
有关备份和还原操作,请参阅 发现文件和检测大规模更改的最佳做法。
若要构建请求 URI,请从服务根 URL 开始:
https://graph.microsoft.com/v1.0/me/onenote
然后追加要检索的资源的终结点。 (资源路径会显示在下一个节中。)
完整的请求 URI 类似于以下示例之一:
https://graph.microsoft.com/v1.0/me/onenote/notebooks/{id}/sections
https://graph.microsoft.com/v1.0/me/onenote/notes/pages
https://graph.microsoft.com/v1.0/me/onenote/pages?select=title,self
备注
了解有关服务根 URL 的详细信息。
使用以下资源路径获取页面、节、节组、笔记本和图像或文件资源。
获取所有笔记本的页面(元数据)。
../pages[?filter,orderby,select,expand,top,skip,count]
从特定节获取页面(元数据)。
../sections/{section-id}/pages[?filter,orderby,select,expand,top,skip,count,pagelevel]
页面的默认排序顺序是 lastModifiedTime desc
。
默认查询将展开父节并选择节的 id
、name
和 self
属性。
默认情况下,为 GET 页面请求返回仅前 20 个实体。 未指定 top 查询字符串选项的请求将在响应中返回 @odata.nextLink
链接,该链接可用于获取接下来的 20 个条目。
对于节中的页面集合,使用 pagelevel 返回页面的缩进级别及其在节中的顺序。
GET ../sections/{section-id}/pages?pagelevel=true
获取特定页面的元数据。
../pages/{page-id}[?select,expand,pagelevel]
页面可以展开 parentNotebook 和 parentSection 属性。
默认查询将展开父节并选择节的 id
、name
和 self
属性。
使用 pagelevel 返回页面的缩进级别及其在父节中的顺序。
GET ../pages/{page-id}?pagelevel=true
获取页面的文字和图像预览内容。
../pages/{page-id}/preview
JSON 响应包含预览内容,可用于帮助用户标识页面中的内容。
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.PagePreview",
"previewText":"text-snippet",
"links":{
"previewImageUrl":{
"href":"https://www.onenote.com/api/v1.0/resources/{id}/content?publicAuth=true&mimeType=image/png"
}
}
}
previewText 属性包含来自页面的文本片段。 Microsoft Graph 返回完整短语,最多 300 个字符。
如果页面包含可用于生成预览 UI 的图像,则 previewImageUrl 对象中的 href 属性包含指向公共图像资源的链接。 可以在 HTML 中使用此链接。 否则,href 返回 null。
<img src="https://www.onenote.com/api/v1.0/resources/{id}/content?publicAuth=true&mimeType=image/png" />
获取页面的 HTML 内容。
../pages/{page-id}/content[?includeIDs]
(了解有关返回的 HTML 内容的详细信息)
使用 includeIDs=true 查询字符串选项获取生成的 ID,用于更新页面。
获取用户拥有的所有笔记本的所有节,包括嵌套节组中的节。
../sections[?filter,orderby,select,top,skip,expand,count]
获取直接位于特定节组下的所有节。
../sectionGroups/{sectiongroup-id}/sections[?filter,orderby,select,top,skip,expand,count]
获取直接位于特定笔记本下的所有节。
../notebooks/{notebook-id}/sections[?filter,orderby,select,top,skip,expand,count]
节可以展开 parentNotebook 和 parentSectionGroup 属性。
节的默认排序顺序是 name asc
。
默认查询将展开父笔记本和父节组,并选择它们的 id
、name
和 self
属性。
获取特定节。
../sections/{section-id}[?select,expand]
节可以展开 parentNotebook 和 parentSectionGroup 属性。
默认查询将展开父笔记本和父节组,并选择它们的 id
、name
和 self
属性。
获取用户拥有的所有笔记本的所有节组,包括嵌套节组。
../sectionGroups[?filter,orderby,select,top,skip,expand,count]
获取直接位于特定笔记本下的所有节组。
../notebooks/{notebook-id}/sectionGroups[?filter,orderby,select,top,skip,expand,count]
节组可以展开 sections、sectionGroups、parentNotebook 和 parentSectionGroup 属性。
节组的默认排序顺序是 name asc
。
默认查询将展开父笔记本和父节组,并选择它们的 id
、name
和 self
属性。
获取特定节组。
../sectionGroups/{sectiongroup-id}[?select,expand]
节组可以展开 sections、sectionGroups、parentNotebook 和 parentSectionGroup 属性。
默认查询将展开父笔记本和父节组,并选择它们的 id
、name
和 self
属性。
获取用户拥有的所有笔记本。
../notebooks[?filter,orderby,select,top,skip,expand,count]
笔记本可以展开 sections 和 sectionGroups 属性。
笔记本的默认排序顺序是 name asc
。
获取特定笔记本。
../notebooks/{notebook-id}[?select,expand]
笔记本可以展开 sections 和 sectionGroups 属性。
获取特定资源的二进制数据。
../resources/{resource-id}/$value
可以在页面的输出 HTML 中找到文件的资源 URI。
例如,img 标记包含 data-fullres-src 属性中原始图像的终结点和 src 属性中经优化图像的终结点。
<img
src="https://www.onenote.com/api/v1.0/me/notes/resources/{image-id}/$value"
data-src-type="image/png"
data-fullres-src="https://www.onenote.com/api/v1.0/resources/{image-id}/$value"
data-fullres-src-type="image/png" ... />
object 标记包含 data 属性中文件资源的终结点。
<object
data="https://www.onenote.com/api/v1.0/me/notes/resources/{file-id}/$value"
data-attachment="fileName.pdf"
type="application/pdf" ... />
备注
不支持获取资源的集合。
在获取文件资源时,无需在请求中包含 Accept 内容类型。
有关 GET 请求的详细信息,请参阅 Microsoft Graph API REST 引用中的以下资源:
可以查询 OneNote 实体以获取所需的信息。 以下示例演示了一些方法,可以在对 Microsoft Graph 的 GET 请求中使用支持的查询字符串选项。
请注意:
所有的 GET 请求都以服务根 URL 开头。
示例:https://www.onenote.com/api/v1.0/me/notes
和 https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/
URL 查询字符串中的空格必须使用 %20 编码。
示例:filter=title%20eq%20'biology'
属性名和 OData 字符串比较均区分大小写。 建议使用 OData tolower 函数进行字符串比较。
示例:filter=tolower(name) eq 'spring'
获取由特定应用创建的所有页面。
[GET] ../pages?filter=createdByAppId eq 'WLID-000000004C12821A'
获取所有页面的标题、OneNote 客户端链接和 contentUrl 链接。
[GET] ../pages?select=title,links,contentUrl
获取所有笔记本,并展开它的节和节组。
[GET] ../notebooks?expand=sections,sectionGroups
获取某个特定的节组,并展开它的节和节组。
[GET] ../sectionGroups/{sectiongroup-id}?expand=sections,sectionGroups
获取一个页面并展开其父节和父笔记本。
[GET] ../pages/{page-id}?expand=parentSection,parentNotebook
获取所有笔记本,展开其节和节组,并在每个节组中展开所有节。
[GET] ../notebooks?expand=sections,sectionGroups(expand=sections)
备注
展开子实体的父项或展开父实体的子项来创建循环引用,这并不受支持。
获取特定节组的名称和 self 链接,并获取其所有节的名称和 self 链接。
[GET] ../sectionGroups/{sectiongroup-id}?expand=sections(select=name,self)&select=name,self
获取所有节的名称和 self 链接,并获取每个节的父笔记本的名称和创建时间。
[GET] ../sections?expand=parentNotebook(select=name,createdTime)&select=name,self
[GET] ../pages?select=id,title&expand=parentSection(select=name),parentNotebook(select=name)
获取所有笔记本、节和节组。
[GET] ../notebooks?expand=sections,sectionGroups(expand=sections,sectionGroups(levels=max;expand=sections))
获取 2014 年 10 月创建的所有节。
[GET] ../sections?filter=createdTime ge 2014-10-01 and createdTime le 2014-10-31
获取某个特定应用自 2015 年 1 月 1 日以来所创建的页面。
[GET] ../pages?filter=createdByAppId eq 'WLID-0000000048118631' and createdTime ge 2015-01-01
获取特定笔记本中的所有页面。 默认情况下,API 返回 20 个条目。
[GET] ../pages?filter=parentNotebook/id eq '{notebook-id}'&expand=parentNotebook
获取 School 笔记本的所有节的名称和 pagesUrl 链接。 OData 字符串比较区分大小写,因此,作为最佳做法将使用 tolower 函数。
[GET] ../notebooks?filter=tolower(name) eq 'school'&expand=sections(select=name,pagesUrl)
获取在节名中包含术语 spring 的所有节的名称和 pagesUrl 链接。 按照最后修改日期对节进行排序。
[GET] ../sections?filter=contains(tolower(name),'spring')&select=name,pagesUrl&orderby=lastModifiedTime desc
获取先按照 createdByAppId 属性排序再按照最近创建时间排序的前 20 个页面。 默认情况下,API 返回 20 个条目。
[GET] ../pages?orderby=createdByAppId,createdTime desc
获取自 2015 年 1 月 1 日以来创建的五个最新页面。 默认情况下,此 API 返回 20 个条目,最多返回 100 个条目。 页面的默认排序顺序是 lastModifiedTime desc
。
[GET] ../pages?filter=createdTime ge 2015-01-01&top=5
在结果集中获取接下来的五页。
[GET] ../pages?filter=createdTime ge 2015-01-01&top=5&skip=5
以及接下来的五个页面。
[GET] ../pages?filter=createdTime ge 2015-01-01&top=5&skip=10
备注
如果 同时将 top 和 filter 应用于同一请求,则结果仅包括与这两个条件匹配的实体。
获取用户笔记本中所有节的名称、创建时间和 self 链接。
[GET] ../sections?select=name,createdTime,self
获取特定页面的标题、创建时间和 OneNote 客户端链接。
[GET] ../pages/{page-id}?select=title,createdTime,links
获取用户的默认笔记本中所有节的名称和 pagesUrl 链接。
[GET] ../notebooks?select=name&expand=sections(select=name,pagesUrl)&filter=isDefault eq true
获取按标题字母顺序排序的前 50 个页面的标题和 self 链接。 默认情况下,此 API 返回 20 个条目,最多返回 100 个条目。 页面的默认排序顺序是 lastModifiedTime desc
。
[GET] ../pages?top=50&select=title,self&orderby=title
获取第 51 至 100 页。 默认情况下,此 API 返回 20 个条目,最多返回 100 个条目。
[GET] ../pages?skip=50&top=50&select=title,self&orderby=title
备注
对检索默认条目数的页面的 GET 请求 (即,它们不指定 顶级 表达式) 响应中返回 @odata.nextLink 链接,可用于获取接下来的 20 个条目。
向 Microsoft Graph 发送 GET 请求时,可以使用 OData 查询字符串选项来自定义查询并仅获取所需的信息。 它们可以通过减少对该服务的调用数量以及响应有效负载的大小来提高性能。
备注
为了增强可读性,本文中的示例不使用 URL 查询字符串中空格所需的 %20 百分比编码:filter=isDefault%20eq%20true
查询选项 | 示例和说明 |
---|---|
count |
集合中的实体计数。 在响应的 @odata.count 属性中返回此值。 |
expand |
要在响应中返回内联的导航属性。
expand 表达式支持以下属性: 默认情况下,页面的 GET 请求同时展开 parentSection 并选择该节的 id、name 和 self 属性。 节和节组的默认 GET 请求扩展 parentNotebook 和 parentSectionGroup,并选择父项的id、name 和 self 属性。 可用于单个实体或集合。 |
filter |
是否在结果集中包含条目的布尔表达式。 支持以下 OData 运算符和函数:
属性名和 OData 字符串比较均区分大小写。 建议使用 OData tolower 函数进行字符串比较。 |
orderby |
作为排序依据的属性,具有可选的 asc(默认)或 desc 的排序顺序。 您可以按请求集合中实体的任意属性进行排序。 笔记本、节组和节的默认排序顺序为 用逗号隔开多个属性,并按想要应用属性的顺序列出它们。 属性名区分大小写。 |
select |
要返回的属性。 可用于单个实体或集合。 使用逗号分隔多个属性。 属性名区分大小写。 |
skip |
结果集中要跳过的条目数量。 通常用于对结果分页。 |
top |
结果集中要返回的条目数量,最多可达 100 个条目。 默认值为 20。 |
Microsoft Graph 还提供 pagelevel
查询字符串选项,可使用该选项获取父节内页面的级别和顺序。 仅适用于特定节中页面的查询或特定页面中的查询。
GET ../sections/{section-id}/pages?pagelevel=true
GET ../pages/{page-id}?pagelevel=true
Microsoft Graph 支持 filter 表达式中的以下 OData 运算符和函数。 使用 OData 表达式时,请记住:
必须将 URL 查询字符串中的空格替换为 %20
编码。
示例:filter=isDefault%20eq%20true
属性名和 OData 字符串比较均区分大小写。 建议使用 OData tolower 函数进行字符串比较。
示例:filter=tolower(name) eq 'spring'
比较运算符 | 示例 |
---|---|
eq (等于) |
createdByAppId eq '{app-id}' |
ne (不等于) |
userRole ne 'Owner' |
gt (大于) |
createdTime gt 2014-02-23 |
ge (大于或等于) |
lastModifiedTime ge 2014-05-05T07:00:00Z |
lt (小于) |
createdTime lt 2014-02-23 |
le (小于或等于) |
lastModifiedTime le 2014-02-23 |
逻辑运算符 | 示例 |
---|---|
和 | createdTime le 2014-01-30 and createdTime gt 2014-01-23 |
或 | createdByAppId eq '{app-id}' or createdByAppId eq '{app-id}' |
not | not contains(tolower(title),'school') |
字符串函数 | 示例 |
---|---|
contains | contains(tolower(title),'spring') |
endswith | endswith(tolower(title),'spring') |
startswith | startswith(tolower(title),'spring') |
length | length(title) eq 19 |
indexof | indexof(tolower(title),'spring') eq 1 |
substring | substring(tolower(title),1) eq 'spring' |
tolower | tolower(title) eq 'spring' |
toupper | toupper(title) eq 'SPRING' |
trim | trim(tolower(title)) eq 'spring' |
concat | concat(title,'- by MyRecipesApp') eq 'Carrot Cake Recipe - by MyRecipesApp' |
filter、select、expand 和 orderby 查询表达式可以包含 OneNote 实体的属性。
../sections?filter=createdTime ge 2015-01-01&select=name,pagesUrl&orderby=lastModifiedTime desc
查询表达式中的属性名称区分大小写。
有关属性列表和属性类型,请参阅 Microsoft Graph API REST 引用中的以下资源:
expand 查询字符串选项可与以下导航属性一起使用:
请求数据 | 说明 |
---|---|
协议 | 所有请求均使用 SSL/TLS HTTPS 协议。 |
授权标头 |
如果缺少或无效,则请求失败,并显示 401 状态代码。 请参阅身份验证和权限。 |
接受标头 |
|
响应数据 | 说明 |
---|---|
成功代码 | 200 HTTP 状态代码。 |
响应正文 | JSON 格式、页面 HTML 或文件资源二进制数据中的实体或实体集的 OData 表示形式。 |
错误 | 如果请求失败,API 将在响应正文的 @api.diagnostics 对象中返回错误。 |
X-CorrelationId 标头 | 唯一标识该请求的 GUID。 在与 Microsoft 支持部门协作来解决问题时,可以使用此值和日期标头值。 |
Microsoft Graph 笔记根 URL 为 Microsoft Graph 笔记的所有调用使用以下格式:
https://graph.microsoft.com/{version}/me/onenote/
URL 中的 version
段表示想要使用的 Microsoft Graph 的版本。
v1.0
用于稳定的生产代码。
beta
用于试用正在开发的功能。 Beta 版中的特性和功能可能会有所更改,因此,不应将其用于生产代码。
为当前用户可以访问的 OneNote 内容(拥有和共享)使用 me
。 为指定用户已与当前用户共享的 OneNote 内容(此 URL 中)使用 users/{id}
。 使用 Microsoft Graph 获取用户 ID。
若要获取 OneNote 内容或结构,需要请求相应的权限。
以下范围允许对 Microsoft Graph 执行 GET 请求。 选择应用运行所需的最低级别的权限。
从以下项中进行选择:
有关权限范围及其工作方式的详细信息,请参阅 Microsoft Graph 权限引用。
培训
学习路径
了解 ASP.NET Core 开发的 Microsoft Graph 方案 - Training
该学习路径包含实践练习,展示了如何在使用 Microsoft Graph API 的 ASP.NET Core 应用中执行常见任务,例如显示用户的电子邮件、访问日历事件,以及下载和上传文件。