获取 OneNote 内容和结构

项目
11/07/2024

适用于：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 限制：

备份/还原 OneNote 部分
备份/还原 OneNote 笔记本

有关备份和还原操作，请参阅发现文件和检测大规模更改的最佳做法。

构建请求 URI

若要构建请求 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 的详细信息。

GET 请求的资源路径

使用以下资源路径获取页面、节、节组、笔记本和图像或文件资源。

页面集合
页面实体
页面预览
页面 HTML 内容
节集合
节实体
SectionGroup 集合
SectionGroup 实体
笔记本集合
笔记本实体
图像或其他文件资源

页面集合

获取所有笔记本的页面（元数据）。

../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 内容

获取页面的 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 属性。

SectionGroup 集合

获取用户拥有的所有笔记本的所有节组，包括嵌套节组。

../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 属性。

SectionGroup 实体

获取特定节组。

../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 引用中的以下资源：

示例 GET 请求

可以查询 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'

filter

获取由特定应用创建的所有页面。

[GET] ../pages?filter=createdByAppId eq 'WLID-000000004C12821A'

select

获取所有页面的标题、OneNote 客户端链接和 contentUrl 链接。

[GET] ../pages?select=title,links,contentUrl

expand

获取所有笔记本，并展开它的节和节组。

[GET] ../notebooks?expand=sections,sectionGroups

获取某个特定的节组，并展开它的节和节组。

[GET] ../sectionGroups/{sectiongroup-id}?expand=sections,sectionGroups

获取一个页面并展开其父节和父笔记本。

[GET] ../pages/{page-id}?expand=parentSection,parentNotebook

expand（多个级别）

获取所有笔记本，展开其节和节组，并在每个节组中展开所有节。

[GET] ../notebooks?expand=sections,sectionGroups(expand=sections)

注意

展开子实体的父项或展开父实体的子项来创建循环引用，这并不受支持。

expand & select（多个级别）

获取特定节组的名称和 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

获取所有页面的标题和 ID，并获取父节和父笔记本的名称。

[GET] ../pages?select=id,title&expand=parentSection(select=name),parentNotebook(select=name)

expand & levels（多个级别）

获取所有笔记本、节和节组。

[GET] ../notebooks?expand=sections,sectionGroups(expand=sections,sectionGroups(levels=max;expand=sections))

filter

获取 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

filter & expand

获取特定笔记本中的所有页面。默认情况下，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)

filter & select & orderby

获取在节名中包含术语 spring 的所有节的名称和 pagesUrl 链接。按照最后修改日期对节进行排序。

[GET] ../sections?filter=contains(tolower(name),'spring')&select=name,pagesUrl&orderby=lastModifiedTime desc

orderby

获取先按照 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 应用于同一请求，则结果仅包括与这两个条件匹配的实体。

select

获取用户笔记本中所有节的名称、创建时间和 self 链接。

[GET] ../sections?select=name,createdTime,self

获取特定页面的标题、创建时间和 OneNote 客户端链接。

[GET] ../pages/{page-id}?select=title,createdTime,links

select & expand & filter（多个级别）

获取用户的默认笔记本中所有节的名称和 pagesUrl 链接。

[GET] ../notebooks?select=name&expand=sections(select=name,pagesUrl)&filter=isDefault eq true

top & select & orderby

获取按标题字母顺序排序的前 50 个页面的标题和 self 链接。默认情况下，此 API 返回 20 个条目，最多返回 100 个条目。页面的默认排序顺序是 lastModifiedTime desc。

[GET] ../pages?top=50&select=title,self&orderby=title

skip & top & select & orderby

获取第 51 至 100 页。默认情况下，此 API 返回 20 个条目，最多返回 100 个条目。

[GET] ../pages?skip=50&top=50&select=title,self&orderby=title

注意

对检索默认条目数的页面的 GET 请求 (即，它们不指定顶级表达式) 响应中返回 @odata.nextLink 链接，可用于获取接下来的 20 个条目。

受支持的 OData 查询字符串选项

向 Microsoft Graph 发送 GET 请求时，可以使用 OData 查询字符串选项来自定义查询并仅获取所需的信息。它们可以通过减少对该服务的调用数量以及响应有效负载的大小来提高性能。

注意

为了增强可读性，本文中的示例不使用 URL 查询字符串中空格所需的 %20 百分比编码：filter=isDefault%20eq%20true

查询选项	示例和说明
count	`count=true` 集合中的实体计数。在响应的 @odata.count 属性中返回此值。
expand	`expand=sections,sectionGroups` 要在响应中返回内联的导航属性。 expand 表达式支持以下属性： - 页面：parentNotebook、parentSection - 节：parentNotebook、parentSectionGroup - 节组：sections、sectionGroups、parentNotebook、parentSectionGroup - 笔记本：sections、sectionGroups 默认情况下，页面的 GET 请求同时展开 parentSection 并选择该节的 id、name 和 self 属性。节和节组的默认 GET 请求扩展 parentNotebook 和 parentSectionGroup，并选择父项的id、name 和 self 属性。可用于单个实体或集合。使用逗号分隔多个属性。属性名区分大小写。
filter	`filter=isDefault eq true` 是否在结果集中包含条目的布尔表达式。支持以下 OData 运算符和函数： - 比较运算符：eq、ne、gt、ge、lt、le - 逻辑运算符：and、or、not - 字符串函数：contains、endswith、startswith、length、indexof、substring、tolower、toupper、trim、concat 属性名和 OData 字符串比较均区分大小写。建议使用 OData tolower 函数进行字符串比较。示例：`filter=tolower(name) eq 'spring'`
orderby	`orderby=title,createdTime desc` 作为排序依据的属性，具有可选的 asc（默认）或 desc 的排序顺序。您可以按请求集合中实体的任意属性进行排序。笔记本、节组和节的默认排序顺序为 `name asc`，页面的默认排序顺序为 `lastModifiedTime desc`（最后修改的页面排第一）。用逗号隔开多个属性，并按想要应用属性的顺序列出它们。属性名区分大小写。
select	`select=id,title` 要返回的属性。可用于单个实体或集合。使用逗号分隔多个属性。属性名区分大小写。
skip	`skip=10` 结果集中要跳过的条目数量。通常用于对结果分页。
top	`top=50` 结果集中要返回的条目数量，最多可达 100 个条目。默认值为 20。

Microsoft Graph 还提供 pagelevel 查询字符串选项，可使用该选项获取父节内页面的级别和顺序。仅适用于特定节中页面的查询或特定页面中的查询。

示例

GET ../sections/{section-id}/pages?pagelevel=true
GET ../pages/{page-id}?pagelevel=true

受支持的 OData 运算符和函数

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'`

OneNote 实体属性

filter、select、expand 和 orderby 查询表达式可以包含 OneNote 实体的属性。

示例

../sections?filter=createdTime ge 2015-01-01&select=name,pagesUrl&orderby=lastModifiedTime desc

查询表达式中的属性名称区分大小写。

有关属性列表和属性类型，请参阅 Microsoft Graph API REST 引用中的以下资源：

expand 查询字符串选项可与以下导航属性一起使用：

页面：parentNotebook、parentSection
节：parentNotebook、parentSectionGroup
节组：sections、sectionGroups、parentNotebook、parentSectionGroup
笔记本：sections、sectionGroups

GET 请求的请求和响应信息

请求数据说明

协议所有请求均使用 SSL/TLS HTTPS 协议。

授权标头

请求数据	说明
协议	所有请求均使用 SSL/TLS HTTPS 协议。
授权标头	`Bearer {token}`，其中 `{token}` 是已注册应用的一个有效 OAuth 2.0 访问令牌。如果缺少或无效，则请求失败，并显示 401 状态代码。请参阅身份验证和权限。
接受标头	`application/json` 适用于 OneNote 实体和实体集 `text/html` 适用于页面内容

Bearer {token}，其中 {token} 是已注册应用的一个有效 OAuth 2.0 访问令牌。

如果缺少或无效，则请求失败，并显示 401 状态代码。请参阅身份验证和权限。

接受标头

application/json 适用于 OneNote 实体和实体集

text/html 适用于页面内容

响应数据	说明
成功代码	200 HTTP 状态代码。
响应正文	JSON 格式、页面 HTML 或文件资源二进制数据中的实体或实体集的 OData 表示形式。
错误	如果请求失败，API 将在响应正文的 @api.diagnostics 对象中返回错误。
X-CorrelationId 标头	唯一标识该请求的 GUID。在与 Microsoft 支持部门协作来解决问题时，可以使用此值和日期标头值。

构建 Microsoft Graph 笔记服务根 URL

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。

GET 请求的权限

若要获取 OneNote 内容或结构，需要请求相应的权限。

以下范围允许对 Microsoft Graph 执行 GET 请求。选择应用运行所需的最低级别的权限。

从以下项中进行选择：

Notes.read
Notes.ReadWrite
Notes.ReadWrite.All

有关权限范围及其工作方式的详细信息，请参阅 Microsoft Graph 权限引用。

通过

获取 OneNote 内容和结构

构建请求 URI

GET 请求的资源路径

页面集合

示例

页面实体

示例

页面预览

示例

页面 HTML 内容

节集合

节实体

SectionGroup 集合

SectionGroup 实体

笔记本集合

笔记本实体

图像或其他文件资源

示例

示例

示例 GET 请求

filter

select

expand

expand（多个级别）

expand & select（多个级别）

expand & levels（多个级别）

filter

filter & expand

filter & select & orderby

orderby

筛选器 & 顶部

筛选 & 顶部 & 跳过

select

select & expand & filter（多个级别）

top & select & orderby

skip & top & select & orderby

受支持的 OData 查询字符串选项

示例

受支持的 OData 运算符和函数

OneNote 实体属性

示例

GET 请求的请求和响应信息

构建 Microsoft Graph 笔记服务根 URL

GET 请求的权限

相关内容

反馈

其他资源