使用英语阅读

通过


使用 Microsoft Graph 中的 OneNote API 的最佳做法

本文提供了有关使用 Microsoft Graph 中的 OneNote API 的建议。 这些建议基于 Microsoft Q&A 常见问题的解答。

使用 $select 选择所需的最小属性集

查询资源(例如,笔记本中的分区)时,会发出类似于以下内容的请求。

GET ~/notebooks/{id}/sections

此请求检索节的所有属性。 然而,你可能并不需要所有属性。 可以使用 $select 查询参数只返回所需属性,如下面的示例中所示。

GET ~/notebooks/{id}/sections?$select=id,displayName

同样的方法适用于其他 OneNote API。

使用 $expand 而不是进行多个 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