使用 Microsoft Graph 中的 OneNote API 的最佳做法
本文提供了有关使用 Microsoft Graph 中的 OneNote API 的建议。 这些建议基于 Microsoft Q&A 常见问题的解答。
查询资源(例如,笔记本中的分区)时,会发出类似于以下内容的请求。
GET ~/notebooks/{id}/sections
此请求检索节的所有属性。 然而,你可能并不需要所有属性。 可以使用 $select
查询参数只返回所需属性,如下面的示例中所示。
GET ~/notebooks/{id}/sections?$select=id,displayName
同样的方法适用于其他 OneNote API。
假定你要在分层视图中检索用户的所有笔记本、分区和分区组。 可以通过执行以下操作来实现:
调用
GET ~/notebooks
以获取笔记本的列表。对于每个检索的笔记本,调用
GET ~/notebooks/{notebookId}/sections
以检索分区的列表。对于每个检索的笔记本,调用
GET ~/notebooks/{notebookId}/sectionGroups
以检索分区组的列表。(可选)以递归方式遍历分区组。
此方法 (服务) 进行一些额外的顺序往返:但是,更好的方法是使用 $expand
查询参数。
GET ~/notebooks?$expand=sections,sectionGroups($expand=sections)
此方法在一次网络往返中产生相同的结果,性能更佳。
Microsoft Graph 公开用于检索所有页面的终结点;但是,我们不建议使用此终结点来获取用户有权访问的所有页面。 如果用户的分区太多,并且尝试获取所有页面,则调用将产生 HTTP 状态代码 400
和以下消息:“超出此请求的最大节数。 若要获取包含大量分区的帐户的页面,我们建议一次获取一个分区的页面。”有关此错误代码的详细信息,请参阅 OneNote 错误代码。
若要获取用户有权访问的所有页面,最佳做法是单独调用以获取每个部分的页面。
例如,不使用此调用(此 API 已分页,因此无法一次获取所有页面):
GET ~/pages
最好多次使用以下调用 (,尤其是在不需要) 的所有部分时:
GET ~/sections/{id}/pages
获取页面元数据时,请覆盖默认的 lastModifiedDateTime
排序。 无需按 对页面进行 lastModifiedDateTime
排序时,获取页面会更快。 为此,可以按任何其他属性进行排序;例如:
GET ~/sections/{id}/pages?$select=id,title,createdDateTime&$orderby=createdDateTime