创建 OneNote 页
适用于:OneDrive 上的消费者笔记本 | Microsoft 365 上的企业级笔记本
若要创建 OneNote 页面,请向 pages 终结点发送一个 POST 请求。 例如:
POST ../notes/sections/{id}/pages
发送在邮件正文中定义页面的 HTML。 如果请求成功,Microsoft Graph 将返回 201 HTTP 状态代码。
备注
若要了解有关可以发送以创建节、节组和笔记本的 POST 请求,请参阅我们的交互式 REST 参考。
若要构建 POST 请求 URI,请从服务根 URL 开始:
https://graph.microsoft.com/v1.0/me/onenote
然后追加页面终结点:
在任何节中创建页面(由节名称指定)
.../pages?sectionName=DefaultSection
在任何节中创建页面(由 ID 指定)
.../sections/{section-id}/pages
如果要在用户的个人笔记本中创建页面,Microsoft Graph 还提供了可用于在默认笔记本中创建页面的终结点:
在默认笔记本的默认节中创建页面
../pages
完整的请求 URI 类似于以下示例之一:
https://graph.microsoft.com/v1.0/me/onenote/sections/{id}/pages
https://graph.microsoft.com/v1.0/me/onenote/pages?sectionName=Homework
了解有关服务根 URL 的详细信息。
使用 sectionName 参数在默认笔记本的命名节中创建页面时,适用以下规则:
仅顶级节可以引用(不是节组中的节)。
如果默认笔记本中不存在带指定名称的节,API 将自动创建该节。 这些字符不允许出现在节名称中:
? * \ / : < > | & # " % ~
出于匹配原因,节名称不区分大小写,但创建节时要保留大小写。 因此,“My New Section”将以此方式显示,但“my new section”也会在后面的文章中匹配。
节名称必须为 URL 编码。 例如,空格必须编码为 %20。
SectionName 参数仅对
../notes/pages
路由(不是../notes/sections/{id}/pages
)有效。
由于如果不存在节便会进行创建,因此在应用创建的每一个页面上使用此调用都是安全的。 用户可以重命名节,但 API 将创建一个使用你所提供的 sectionName 的新分区。
备注
API 针对重命名节中的页面返回的链接仍然会到达那些旧页面。
定义页面内容的 HTML 被称为输入 HTML。 输入 HTML 支持标准 HTML 和 CSS 子集,并增添了自定义属性。 (data-id 和 data-render-src 等自定义属性在输入和输出 HTML 中进行了说明。)
在 POST 请求的邮件正文中发送输入 HTML。 可以使用 或 text/html
内容类型直接在邮件正文application/xhtml+xml
中发送输入 HTML,也可以在多部分请求的“演示文稿”部分发送它。
以下示例直接在邮件正文中发送输入 HTML。
POST https://graph.microsoft.com/v1.0/me/onenote/pages
Authorization: Bearer {token}
Content-Type: application/xhtml+xml
<!DOCTYPE html>
<html>
<head>
<title>A page with a block of HTML</title>
<meta name="created" content="2015-07-22T09:00:00-08:00" />
</head>
<body>
<p>This page contains some <i>formatted</i> <b>text</b> and an image.</p>
<img src="https://..." alt="an image on the page" width="500" />
</body>
</html>
如果要发送二进制数据,则必须使用多部分请求。
备注
为简化编程和应用的一致性,可以使用多部分请求来创建所有页面。 最好使用库来构造多部分邮件。 这样可减少创建格式不正确的有效负载的风险。
发送输入 HTML 时,请注意这些常规要求和限制:
输入 HTML 应为 UTF-8 编码且格式标准的 XHTML。 所有容器开始标记都要求匹配结束标记。 所有属性值必须使用双引号或单引号引住。
JavaScript 代码、包含的文件和 CSS 会被删除。
HTML 表单将全部删除。
Microsoft Graph 支持 HTML 元素的子集。
Microsoft Graph 支持常见 HTML 属性的子集和一组自定义属性,如用于更新页面的 data-id 属性。 有关受支持的属性,请参阅输入和输出 HTML。
并非所有元素、特性和属性都受支持(在 HTML4、XHTML、CSS、HTML5 等中)。 相反,Microsoft Graph 接受一组有限的 HTML,以更好地适应用户使用 OneNote 的方式。 有关详细信息,请参阅 HTML 标记对页面的支持。 如果其中未列出标记,则可能被忽略。
以下列表显示 Microsoft Graph 支持的基本元素类型:
-
<head>
和<body>
-
<title>
和<meta>
,用于设置页面标题和创建日期 -
<h1>
至<h6>
,用于节标题 -
<p>
用于段落 -
<ul>
、<ol>
和<li>
,用于列表和列表项 -
<table>
、<tr>
和<td>
,包括嵌套表 -
<pre>
用于预设格式的文本(会保留空格和换行符) -
<b>
和<i>
,用于粗体和斜体字符样式
Microsoft Graph 在创建页面时会保留输入 HTML 的语义内容和基本结构,但会转换输入 HTML 以使用一组受支持的 HTML 和 CSS。 OneNote 中不存在的功能没有任何内容可以转换,因此,它们可能无法在源 HTML 中识别。
这个多部分请求示例创建了一个包含图像和嵌入式文件的页面。 必需的演示部分包含定义页面的输入 HTML。 ImageBlock1 部分包含二进制图像数据,fileBlock1 包含二进制文件数据。 数据部分也可包含 HTML,其中 Microsoft Graph 在 OneNote 页面上将 HTML 呈现为一个图像。
POST https://graph.microsoft.com/v1.0/me/onenote/pages
Authorization: Bearer {token}
Content-Type: multipart/form-data; boundary=MyPartBoundary198374
--MyPartBoundary198374
Content-Disposition:form-data; name="Presentation"
Content-Type:text/html
<!DOCTYPE html>
<html>
<head>
<title>A page with rendered images and an attached file</title>
<meta name="created" content="2015-07-22T09:00:00-08:00" />
</head>
<body>
<p>Here's an image from an <i>online source</i>:</p>
<img src="https://..." alt="an image on the page" width="500" />
<p>Here's an image uploaded as <b>binary data</b>:</p>
<img src="name:imageBlock1" alt="an image on the page" width="300" />
<p>Here's a file attachment:</p>
<object data-attachment="FileName.pdf" data="name:fileBlock1" type="application/pdf" />
</body>
</html>
--MyPartBoundary198374
Content-Disposition:form-data; name="imageBlock1"
Content-Type:image/jpeg
... binary image data ...
--MyPartBoundary198374
Content-Disposition:form-data; name="fileBlock1"
Content-Type:application/pdf
... binary file data ...
--MyPartBoundary198374--
有关介绍如何创建包含图像和其他文件的页面的更多示例,请参阅添加图像和文件、我们的教程及示例。 此外,了解如何针对名片捕获、线上食谱和产品列表创建绝对定位元素、使用笔记标记和提取数据。
Microsoft Graph 对某些格式非常严格,如多部分邮件正文中的 CRLF 换行符。 为降低创造格式不正确的有效负载的风险,应使用库来构造多部分消息。
如果收到格式不正确有效负载的 400 状态,请检查换行符和空格的格式,并检查编码问题。 例如,请尝试使用 charset=utf-8
(示例:Content-Type: text/html; charset=utf-8
)。
请参阅输入 HTML 的要求和限制,以及 POST 请求的大小限制。
请求数据 | 说明 |
---|---|
协议 | 所有请求均使用 SSL/TLS HTTPS 协议。 |
授权标头 |
如果缺少或无效,则请求失败,并显示 401 状态代码。 请参阅身份验证和权限。 |
Content-Type 标头 | HTML 内容的 发送二进制数据时,多部分请求是必需的,并使用 |
接受标头 | application/json |
响应数据 | 说明 |
---|---|
成功代码 | 201 HTTP 状态代码。 |
响应正文 | 采用 JSON 格式的新页的 OData 表示形式。 |
错误 | 如果请求失败,API 将在响应正文的 @api.diagnostics 对象中返回错误。 |
位置标头 | 新页的资源 URL。 |
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 API 添加到分区的页面数量有一些限制。 当某个分区达到此限制并尝试在该分区中创建新页面时,你将看到 HTTP 状态代码为 507
的响应,并显示消息“已超出每个分区允许的最大页面数”。 有关此错误代码的详细信息,请参阅 OneNote 错误代码。
可以使用下列解决办法之一:
- 创建新分区并从中添加新页面。
- 删除已达到页面限制的现有分区的未使用页面。
若要创建 OneNote 页面,需要请求相应的权限。 选择应用运行所需的最低级别的权限。
从以下项中进行选择:
- Notes.Create
- Notes.ReadWrite
- Notes.ReadWrite.All
有关权限范围及其工作方式的详细信息,请参阅 Microsoft Graph 权限引用。