使用 Microsoft Graph 获取 OneNote 内容和结构Get OneNote content and structure with Microsoft Graph

适用于:OneDrive 上的消费者笔记本 | Office 365 上的企业级笔记本Applies to: Consumer notebooks on OneDrive | Enterprise notebooks on Office 365

若要获取 OneNote 内容和结构,请向目标终结点发送 GET 请求。To get OneNote content and structure, you send a GET request to the target endpoint. 例如:For example:

GET ../onenote/pages/{id}

如果请求成功,Microsoft Graph 将返回一个 200 HTTP 状态代码以及请求的实体或内容。If the request is successful, Microsoft Graph returns a 200 HTTP status code and the entities or content that you requested. OneNote 实体作为符合 OData 版本 4.0 规范的 JSON 对象返回。OneNote entities are returned as JSON objects that conform to the OData version 4.0 specification.

通过使用查询字符串选项,可以筛选查询并提高性能。By using query string options, you can filter your queries and improve performance.

构建请求 URIConstruct the request URI

若要构建请求 URI,请从服务根 URL 开始:To construct the request URI, start with the service root URL:

https://graph.microsoft.com/v1.0/me/onenote


然后追加要检索的资源的终结点。Then append the endpoint of the resource you want to retrieve. 资源路径会显示在下一个节中。)(Resource paths are shown in the next section.)

完整的请求 URI 类似于以下示例之一:Your full request URI will look like one of these examples:

  • 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 的详细信息。Note: Learn more about the service root URL.

GET 请求的资源路径Resource paths for GET requests

使用以下资源路径获取页面、节、节组、笔记本和图像或文件资源。Use the following resource paths to get pages, sections, section groups, notebooks, and image or file resources.

页面集合Page collection

获取所有笔记本的页面(元数据)。Get pages (metadata) across all notebooks.

../pages[?filter,orderby,select,expand,top,skip,search,count]


从特定节获取页面(元数据)。Get pages (metadata) from a specific section.

../sections/{section-id}/pages[?filter,orderby,select,expand,top,skip,search,count,pagelevel]


`search` 查询字符串选项仅适用于消费者笔记本。The `search` query string option is available for consumer notebooks only.

页面的默认排序顺序是 lastModifiedTime descThe default sort order for pages is lastModifiedTime desc.

默认查询将展开父节并选择节的 idnameself 属性。The default query expands the parent section and selects the section's id, name, and self properties.

默认情况下,为 GET 页面请求返回仅前 20 个实体。By default, only the top 20 entries are returned for GET pages requests. 未指定 top 查询字符串选项的请求将在响应中返回 @odata.nextLink 链接,该链接可用于获取接下来的 20 个条目。Requests that don't specify a top query string option return an @odata.nextLink link in the response that you can use to get the next 20 entries.

对于节中的页面集合,使用 pagelevel 返回页面的缩进级别及其在节中的顺序。For the pages collection in a section, use pagelevel to return the indentation level of pages and their order within the section.

示例Example

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

页面实体Page entity

获取特定页面的元数据。Get the metadata for a specific page.

../pages/{page-id}[?select,expand,pagelevel]


页面可以展开 parentNotebookparentSection 属性。Pages can expand the parentNotebook and parentSection properties.

默认查询将展开父节并选择节的 idnameself 属性。The default query expands the parent section and selects the section's id, name, and self properties.

使用 pagelevel 返回页面的缩进级别及其在父节中的顺序。Use pagelevel to return the indentation level of the page and its order within its parent section.

示例Example

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

页面预览Page preview

获取页面的文字和图像预览内容。Get text and image preview content for a page.

../pages/{page-id}/preview


JSON 响应包含预览内容,可用于帮助用户标识页面中的内容。The JSON response contains the preview content, which you can use to help users identify what's in the page.

{
  "@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 属性包含来自页面的文本片段。The previewText property contains a text snippet from the page. Microsoft Graph 返回完整短语,最多 300 个字符。Microsoft Graph returns complete phrases, up to a maximum of 300 characters.

如果页面包含可用于生成预览 UI 的图像,则 previewImageUrl 对象中的 href 属性包含指向公共图像资源的链接。If the page has an image that can be used to build a preview UI, the href property in the previewImageUrl object contains a link to a public, pre-authenticated image resource. 可以在 HTML 中使用此链接。You can use this link in HTML. 否则,href 返回 null。Otherwise, href returns null.

示例Example

<img src="https://www.onenote.com/api/v1.0/resources/{id}/content?publicAuth=true&mimeType=image/png" />

页面 HTML 内容Page HTML content

获取页面的 HTML 内容。Get the HTML content of a page.

../pages/{page-id}/content[?includeIDs]

了解有关返回的 HTML 内容 的详细信息)(learn more about returned HTML content)


使用 includeIDs=true 查询字符串选项获取生成的 ID,用于更新页面Use the includeIDs=true query string option to get generated IDs used to update the page.

节集合Section collection

获取用户拥有的所有笔记本的所有节,包括嵌套节组中的节。Get all sections from all notebooks that are owned by the user, including sections in nested section groups.

../sections[?filter,orderby,select,top,skip,expand,count]


获取直接位于特定节组下的所有节。Get all sections that are directly under a specific section group.

../sectionGroups/{sectiongroup-id}/sections[?filter,orderby,select,top,skip,expand,count]


获取直接位于特定笔记本下的所有节。Get all sections that are directly under a specific notebook.

../notebooks/{notebook-id}/sections[?filter,orderby,select,top,skip,expand,count]


节可以展开 parentNotebookparentSectionGroup 属性。Sections can expand the parentNotebook and parentSectionGroup properties.

节的默认排序顺序是 name ascThe default sort order for sections is name asc.

默认查询将展开父笔记本和父节组,并选择它们的 idnameself 属性。The default query expands the parent notebook and parent section group and selects their id, name, and self properties.

节实体Section entity

获取特定节。Get a specific section.

../sections/{section-id}[?select,expand]


节可以展开 parentNotebookparentSectionGroup 属性。Sections can expand the parentNotebook and parentSectionGroup properties.

默认查询将展开父笔记本和父节组,并选择它们的 idnameself 属性。The default query expands the parent notebook and parent section group and selects their id, name, and self properties.

SectionGroup 集合SectionGroup collection

获取用户拥有的所有笔记本的所有节组,包括嵌套节组。Get all section groups from all notebooks that are owned by the user, including nested section groups.

../sectionGroups[?filter,orderby,select,top,skip,expand,count]


获取直接位于特定笔记本下的所有节组。Get all section groups that are directly under a specific notebook.

../notebooks/{notebook-id}/sectionGroups[?filter,orderby,select,top,skip,expand,count]


节组可以展开 sectionssectionGroupsparentNotebookparentSectionGroup 属性。Section groups can expand the sections, sectionGroups, parentNotebook, and parentSectionGroup properties.

节组的默认排序顺序是 name ascThe default sort order for section groups is name asc.

默认查询将展开父笔记本和父节组,并选择它们的 idnameself 属性。The default query expands the parent notebook and parent section group and selects their id, name, and self properties.

SectionGroup 实体SectionGroup entity

获取特定节组。Get a specific section group.

../sectionGroups/{sectiongroup-id}[?select,expand]


节组可以展开 sectionssectionGroupsparentNotebookparentSectionGroup 属性。Section groups can expand the sections, sectionGroups, parentNotebook, and parentSectionGroup properties.

默认查询将展开父笔记本和父节组,并选择它们的 idnameself 属性。The default query expands the parent notebook and parent section group and selects their id, name, and self properties.

笔记本集合Notebook collection

获取用户拥有的所有笔记本。Get all the notebooks that are owned by the user.

../notebooks[?filter,orderby,select,top,skip,expand,count]


笔记本可以展开 sectionssectionGroups 属性。Notebooks can expand the sections and sectionGroups properties.

笔记本的默认排序顺序是 name ascThe default sort order for notebooks is name asc.

笔记本实体Notebook entity

获取特定笔记本。Get a specific notebook.

../notebooks/{notebook-id}[?select,expand]


笔记本可以展开 sectionssectionGroups 属性。Notebooks can expand the sections and sectionGroups properties.

图像或其他文件资源Image or other file resource

获取特定资源的二进制数据。Get the binary data of a specific resource.

../resources/{resource-id}/$value


可以在页面的输出 HTML 中找到文件的资源 URI。You can find the file's resource URI in the page's output HTML.

例如,img 标记包含 data-fullres-src 属性中原始图像的终结点和 src 属性中经优化图像的终结点。For example, an img tag includes endpoints for the original image in the data-fullres-src attribute and the optimized image in the src attribute.

示例Example

<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 属性中文件资源的终结点。And an object tag includes the endpoint for the file resource in the data attribute.

示例Example

<object
    data="https://www.onenote.com/api/v1.0/me/notes/resources/{file-id}/$value"
    data-attachment="fileName.pdf" 
    type="application/pdf" ... />

注意: 不支持获取资源的集合。Note: Getting a collection of resources is not supported.

在获取文件资源时,无需在请求中包含 Accept 内容类型。When you get a file resource, you don't need to include an Accept content type in the request.

有关 GET 请求的详细信息,请参阅 Microsoft Graph API REST 引用中的以下资源:For more information about GET requests, see the following resources in the Microsoft Graph API REST reference:

示例 GET 请求Example GET requests

可以查询 OneNote 实体和搜索页面内容以仅获取所需的信息。You can query for OneNote entities and search page content to get just the information you need. 以下示例演示了一些方法,可以在对 Microsoft Graph 的 GET 请求中使用支持的查询字符串选项The following examples show some ways you can use supported query string options in GET requests to Microsoft Graph.

请注意:Remember:

  • 所有的 GET 请求都以服务根 URL 开头。All GET requests start with the service root URL.

    示例https://www.onenote.com/api/v1.0/me/noteshttps://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/Examples: https://www.onenote.com/api/v1.0/me/notes and https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/

  • URL 查询字符串中的空格必须使用 %20 编码。Spaces in the URL query string must use %20 encoding.

    示例filter=title%20eq%20'biology'Example: filter=title%20eq%20'biology'

  • 属性名和 OData 字符串比较均区分大小写。Property names and OData string comparisons are case-sensitive. 建议使用 OData tolower 函数进行字符串比较。We recommend using the OData tolower function for string comparisons.

    示例filter=tolower(name) eq 'spring'Example: filter=tolower(name) eq 'spring'

search & filtersearch & filter

获取包含由特定应用创建的术语 recipe 的所有页面(search 仅适用于消费者笔记本)。Get all pages that contain the term recipe that were created by a specific app (search is available for consumer notebooks only).

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

search & selectsearch & select

获取包含术语 golgi app 的所有页面的标题、OneNote 客户端链接和 contentUrl 链接(search 仅适用于消费者笔记本)。Get the title, OneNote client links, and contentUrl link for all pages that contain the term golgi app (search is available for consumer notebooks only).

[GET] ../pages?search=golgi app&select=title,links,contentUrl

expandexpand

获取所有笔记本,并展开它的节和节组。Get all notebooks and expand their sections and section groups.

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

获取某个特定的节组,并展开它的节和节组。Get a specific section group and expand its sections and section groups.

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

获取一个页面并展开其父节和父笔记本。Get a page and expand its parent section and parent notebook.

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

expand(多个级别)expand (multiple levels)

获取所有笔记本,展开其节和节组,并在每个节组中展开所有节。Get all notebooks and expand their sections and section groups, and expand all sections in each section group.

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

注意: 展开子实体的父项或展开父实体的子项来创建循环引用,这并不受支持。Note: Expanding parents of child entities or expanding children of parent entities creates a circular reference and is not supported.

expand & select(多个级别)expand & select (multiple levels)

获取特定节组的名称和 self 链接,并获取其所有节的名称和 self 链接。Get the name and self link for a specific section group, and get the name and self links for all its sections.

[GET] ../sectionGroups/{sectiongroup-id}?expand=sections(select=name,self)&select=name,self

获取所有节的名称和 self 链接,并获取每个节的父笔记本的名称和创建时间。Get the name and self link for all sections, and get the name and created time of each section's parent notebook.

[GET] ../sections?expand=parentNotebook(select=name,createdTime)&select=name,self

获取所有页面的标题和 ID,并获取父节和父笔记本的名称。Get the title and ID for all pages, and get the name of the parent section and parent notebook.
[GET] ../pages?select=id,title&expand=parentSection(select=name),parentNotebook(select=name)

expand & levels(多个级别)expand & levels (multiple levels)

获取所有笔记本、节和节组。Get all notebooks, sections, and section groups.

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

filterfilter

获取 2014 年 10 月创建的所有节。Get all sections that were created in October 2014.

[GET] ../sections?filter=createdTime ge 2014-10-01 and createdTime le 2014-10-31

获取某个特定应用自 2015 年 1 月 1 日以来所创建的页面。Get the pages that were created by a specific app since January 1, 2015.

[GET] ../pages?filter=createdByAppId eq 'WLID-0000000048118631' and createdTime ge 2015-01-01

filter & expandfilter & expand

获取特定笔记本中的所有页面。Get all pages in a specific notebook. 默认情况下,API 返回 20 个条目。The API returns 20 entries by default.

[GET] ../pages?filter=parentNotebook/id eq '{notebook-id}'&expand=parentNotebook

获取 School 笔记本的所有节的名称和 pagesUrl 链接。Get the name and pagesUrl link for all sections from the School notebook. OData 字符串比较区分大小写,因此,作为最佳做法将使用 tolower 函数。OData string comparisons are case-sensitive, so use the tolower function as a best practice.

[GET] ../notebooks?filter=tolower(name) eq 'school'&expand=sections(select=name,pagesUrl)

filter & select & orderbyfilter & select & orderby

获取在节名中包含术语 spring 的所有节的名称和 pagesUrl 链接。Get the name and pagesUrl link for all sections that contain the term spring in the section name. 按照最后修改日期对节进行排序。Order sections by last modified date.

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

orderbyorderby

获取先按照 createdByAppId 属性排序再按照最近创建时间排序的前 20 个页面。Get the first 20 pages ordered by createdByAppId property and then by most recent created time. 默认情况下,API 返回 20 个条目。The API returns 20 entries by default.

[GET] ../pages?orderby=createdByAppId,createdTime desc

search & filter & topsearch & filter & top

获取自 2015 年 1 月 1 日以来创建的包含短语 cell division 的 5 个最新页面。Get the five newest pages created since January 1, 2015 that contain the phrase cell division. 默认情况下,此 API 返回 20 个条目,最多返回 100 个条目。The API returns 20 entries by default with a maximum of 100. 页面的默认排序顺序为 lastModifiedTime descsearch 仅适用于消费者笔记本)。The default sort order for pages is lastModifiedTime desc (search is available for consumer notebooks only).

[GET] ../pages?search="cell division"&filter=createdTime ge 2015-01-01&top=5

search & filter & top & skipsearch & filter & top & skip

获取结果集中接下来的五个页面(search 仅适用于消费者笔记本)。Get the next five pages in the result set (search is available for consumer notebooks only).

[GET] ../pages?search=biology&filter=createdTime ge 2015-01-01&top=5&skip=5

以及接下来的五页(search 仅适用于消费者笔记本)。And the next five (search is available for consumer notebooks only).

[GET] ../pages?search=biology&filter=createdTime ge 2015-01-01&top=5&skip=10

注意: 如果 searchfilter 都应用于同一请求,则结果只包含与这两个条件都匹配的实体。Note: If both search and filter are applied to the same request, the results include only those entities that match both criteria.

selectselect

获取用户笔记本中所有节的名称、创建时间和 self 链接。Get the name, created time, and self link for all sections in the user's notebooks.

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

获取特定页面的标题、创建时间和 OneNote 客户端链接。Get the title, created time, and OneNote client links for a specific page.

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

select & expand & filter(多个级别)select & expand & filter (multiple levels)

获取用户的默认笔记本中所有节的名称和 pagesUrl 链接。Get the name and pagesUrl link for all sections in the user's default notebook.

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

top & select & orderbytop & select & orderby

获取按标题字母顺序排序的前 50 个页面的标题和 self 链接。Get the title and self link for the first 50 pages, ordered alphabetically by title. 默认情况下,此 API 返回 20 个条目,最多返回 100 个条目。The API returns 20 entries by default with a maximum of 100. 页面的默认排序顺序是 lastModifiedTime descThe default sort order for pages is lastModifiedTime desc.

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

skip & top & select & orderbyskip & top & select & orderby

获取第 51 至 100 页。默认情况下,此 API 返回 20 个条目,最多返回 100 个条目。Get pages 51 to 100. The API returns 20 entries by default with a maximum of 100.

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

注意: 检索条目默认数量(即,它们不指定 top 表达式)的页面的 GET 请求在响应中将返回一个 @odata.nextLink 链接,你可使用此链接获取接下来的 20 个条目。Note: GET requests for pages that retrieve the default number of entries (that is, they don't specify a top expression) return an @odata.nextLink link in the response that you can use to get the next 20 entries.

受支持的 OData 查询字符串选项Supported OData query string options

向 Microsoft Graph 发送 GET 请求时,可以使用 OData 查询字符串选项来自定义查询并仅获取所需的信息。When sending GET requests to Microsoft Graph, you can use OData query string options to customize your query and get just the information you need. 它们可以通过减少对该服务的调用数量以及响应有效负载的大小来提高性能。They can also improve performance by reducing the number of calls to the service and the size of the response payload.

注意: 为了增强可读性,本文中的示例不使用 URL 查询字符串中空格所需的 %20 百分比编码:filter=isDefault%20eq%20trueNote: For readability, the examples in this article don't use the %20 percent-encoding required for spaces in the URL query string: filter=isDefault%20eq%20true

查询选项Query option 示例和说明Example and description
countcount

count=true

集合中的实体计数。在响应的 **@odata.count** 属性中返回此值。The count of entities in the collection. The value is returned in the **@odata.count** property in the response.

expandexpand

expand=sections,sectionGroups

要在响应中返回内联的导航属性。The navigation properties to return inline in the response. expand 表达式支持以下属性:The following properties are supported for expand expressions:
- 页面:parentNotebookparentSection- Pages: parentNotebook, parentSection
- 节:parentNotebookparentSectionGroup- Sections: parentNotebook, parentSectionGroup
- 节组:sectionssectionGroupsparentNotebookparentSectionGroup- Section groups: sections, sectionGroups, parentNotebook, parentSectionGroup
- 笔记本:sectionssectionGroups- Notebooks: sections, sectionGroups

默认情况下,页面的 GET 请求同时展开 parentSection 并选择该节的 idnameself 属性。节和节组的默认 GET 请求扩展 parentNotebookparentSectionGroup,并选择父项的idnameself 属性。By default, GET requests for pages expands parentSection and select the section's id, name, and self properties. Default GET requests for sections and section groups expand both parentNotebook and parentSectionGroup, and select the parents' id, name, and self properties.

可用于单个实体或集合。Can be used for a single entity or a collection.
使用逗号分隔多个属性。Separate multiple properties with commas.
属性名区分大小写。Property names are case-sensitive.

filterfilter

filter=isDefault eq true

是否在结果集中包含条目的布尔表达式。A Boolean expression for whether to include an entry in the result set. 支持以下 OData 运算符和函数:Supports the following OData operators and functions:
- 比较运算符:eqnegtgeltle- Comparison operators: eq, ne, gt, ge, lt, le
- 逻辑运算符:andornot- Logical operators: and, or, not
- 字符串函数:containsendswithstartswithlengthindexofsubstringtolowertouppertrimconcat- String functions: contains, endswith, startswith, length, indexof, substring, tolower, toupper, trim, concat

属性名和 OData 字符串比较均区分大小写。Property names and OData string comparisons are case-sensitive. 建议使用 OData tolower 函数进行字符串比较。We recommend using the OData tolower function for string comparisons.

示例filter=tolower(name) eq 'spring'Example: filter=tolower(name) eq 'spring'

orderbyorderby

orderby=title,createdTime desc

作为排序依据的属性,具有可选的 asc(默认)或 desc 的排序顺序。您可以按请求集合中实体的任意属性进行排序。The properties to sort by, with an optional asc (default) or desc sort order. You can sort by any property of the entity in the requested collection.

笔记本、节组和节的默认排序顺序为 name asc,页面的默认排序顺序为 lastModifiedTime desc(最后修改的页面排第一)。The default sort order for notebooks, section groups, and sections is name asc, and for pages is lastModifiedTime desc (last modified page first).

用逗号隔开多个属性,并按想要应用属性的顺序列出它们。Separate multiple properties with commas, and list them in the order that you want them applied. 属性名区分大小写。Property names are case-sensitive.

searchsearch

search=cell div

仅适用于消费者笔记本。Available for consumer notebooks only.

要在页面标题、页面正文、图像替换文字、图像 OCR 文本中搜索的术语或短语。默认情况下,搜索查询返回按相关性排序的结果。The term or phrase to search for in the page title, page body, image alt text, and image OCR text. By default, search queries return results sorted by relevance.

OneNote 使用必应全文搜索来支持短语搜索、词干分解、拼写宽容、相关性和排名、断字、多语言以及其他全文搜索功能。OneNote uses Bing full-text search to support phrase search, stemming, spelling forgiveness, relevance and ranking, word breaking, multiple languages, and other full-text search features. 搜索字符串不区分大小写。Search strings are case-insensitive.

仅适用于用户拥有的笔记本中的页面。Applies only to pages in notebooks owned by the user. 已编入索引的内容具有私密性,只有所有者才能访问。Indexed content is private and can only be accessed by the owner. 受密码保护的页面未编入索引。Password-protected pages are not indexed. 仅适用于 pages 终结点。Applies only to the pages endpoint.

selectselect

select=id,title

要返回的属性The properties to return. 可用于单个实体或集合。Can be used for a single entity or for a collection. 使用逗号分隔多个属性。Separate multiple properties with commas. 属性名区分大小写。Property names are case-sensitive.

skipskip

skip=10

结果集中要跳过的条目数量。The number of entries to skip in the result set. 通常用于对结果分页。Typically used for paging results.

toptop

top=50

结果集中要返回的条目数量,最多可达 100 个条目。The number of entries to return in the result set, up to a maximum of 100. 默认值为 20。The default value is 20.

Microsoft Graph 还提供 pagelevel 查询字符串选项,可使用该选项获取父节内页面的级别和顺序。Microsoft Graph also provides the pagelevel query string option you can use to get the level and order of pages within the parent section. 仅适用于特定节中页面的查询或特定页面中的查询。Applies only to queries for pages in a specific section or queries for a specific page.

示例Examples

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

受支持的 OData 运算符和函数Supported OData operators and functions

Microsoft Graph 支持 filter 表达式中的以下 OData 运算符和函数。Microsoft Graph supports the following OData operators and functions in filter expressions. 使用 OData 表达式时,请记住:When using OData expressions, remember:

  • 必须将 URL 查询字符串中的空格替换为 %20 编码。Spaces in the URL query string must be replaced with the %20 encoding.

    示例: filter=isDefault%20eq%20trueExample: filter=isDefault%20eq%20true

  • 属性名和 OData 字符串比较均区分大小写。Property names and OData string comparisons are case-sensitive. 建议使用 OData tolower 函数进行字符串比较。We recommend using the OData tolower function for string comparisons.

    示例: filter=tolower(name) eq 'spring'Example: filter=tolower(name) eq 'spring'

比较运算符Comparison operator 示例Example
eqeq
(等于)(equal to)
createdByAppId eq '{app-id}'
nene
(不等于)(not equal to)
userRole ne 'Owner'
gtgt
(大于)(greater than)
createdTime gt 2014-02-23
gege
(大于或等于)(greater than or equal to)
lastModifiedTime ge 2014-05-05T07:00:00Z
ltlt
(小于)(less than)
createdTime lt 2014-02-23
lele
(小于或等于)(less than or equal to)
lastModifiedTime le 2014-02-23

逻辑运算符Logical operator 示例Example
and createdTime le 2014-01-30 and createdTime gt 2014-01-23
or createdByAppId eq '{app-id}' or createdByAppId eq '{app-id}'
notnot not contains(tolower(title),'school')

| 字符串函数String function | 示例Example | |------|------| | containscontains | `contains(tolower(title),'spring')` | | endswithendswith | `endswith(tolower(title),'spring')` | | startswithstartswith | `startswith(tolower(title),'spring')` | | lengthlength | `length(title) eq 19` | | indexofindexof | `indexof(tolower(title),'spring') eq 1` | | substringsubstring | `substring(tolower(title),1) eq 'spring'` | | tolowertolower | `tolower(title) eq 'spring'` | | touppertoupper | `toupper(title) eq 'SPRING'` | | trimtrim | `trim(tolower(title)) eq 'spring'` | | concatconcat | `concat(title,'- by MyRecipesApp') eq 'Carrot Cake Recipe - by MyRecipesApp'` |

OneNote 实体属性OneNote entity properties

filterselectexpandorderby 查询表达式可以包含 OneNote 实体的属性。The filter, select, expand, and orderby query expressions can include properties of OneNote entities.

示例Example

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

查询表达式中的属性名称区分大小写。Property names are case-sensitive in query expressions.

有关属性列表和属性类型,请参阅 Microsoft Graph API REST 引用中的以下资源:For the list of properties and property types, see the following resources in the Microsoft Graph API REST reference:

expand 查询字符串选项可与以下导航属性一起使用:The expand query string option can be used with the following navigation properties:

  • 页面:parentNotebookparentSectionPages: parentNotebook, parentSection
  • 节:parentNotebookparentSectionGroupSections: parentNotebook, parentSectionGroup
  • 节组:sectionssectionGroupsparentNotebookparentSectionGroupSection groups: sections, sectionGroups, parentNotebook, parentSectionGroup
  • 笔记本:sectionssectionGroupsNotebooks: sections, sectionGroups

GET 请求的请求和响应信息Request and response information for GET requests

请求数据Request data 说明Description
协议Protocol 所有请求均使用 SSL/TLS HTTPS 协议。All requests use the SSL/TLS HTTPS protocol.
授权标头Authorization header

Bearer {token},其中 {token} 是已注册应用的一个有效 OAuth 2.0 访问令牌。Bearer {token}, where {token} is a valid OAuth 2.0 access token for your registered app.

如果缺少或无效,则请求失败,并显示 401 状态代码。If missing or invalid, the request fails with a 401 status code. 请参阅身份验证和权限See Authentication and permissions.

接受标头Accept header

application/json 适用于 OneNote 实体和实体集application/json for OneNote entities and entity sets

text/html 适用于页面内容text/html for page content


响应数据Response data 说明Description
成功代码Success code 200 HTTP 状态代码。A 200 HTTP status code.
响应正文Response body JSON 格式、页面 HTML 或文件资源二进制数据中的实体或实体集的 OData 表示形式。An OData representation of the entity or entity set in JSON format, the page HTML, or file resource binary data.
错误Errors 如果请求失败,API 将在响应正文的 **@api.diagnostics** 对象中返回错误If the request fails, the API returns errors in the **@api.diagnostics** object in the response body.
X-CorrelationId 标头X-CorrelationId header 唯一标识该请求的 GUID。A GUID that uniquely identifies the request. 在与 Microsoft 支持部门协作来解决问题时,可以使用此值和日期标头值。You can use this value along with the value of the Date header when working with Microsoft support to troubleshoot issues.

构建 Microsoft Graph 笔记服务根 URLConstructing the Microsoft Graph notes service root URL

Microsoft Graph 笔记根 URL 为 Microsoft Graph 笔记的所有调用使用以下格式:The Microsoft Graph notes root URL uses the following format for all calls to Microsoft Graph notes:

https://graph.microsoft.com/{version}/me/onenote/

URL 中的 version 段表示想要使用的 Microsoft Graph 的版本。The version segment in the URL represents the version of Microsoft Graph that you want to use. v1.0 用于稳定的生产代码。Use v1.0 for stable production code. beta 用于试用正在开发的功能。Use beta to try out a feature that's in development. Beta 版中的特性和功能可能会有所更改,因此,不应将其用于生产代码。Features and functionality in beta may change, so you shouldn't use it in your production code.

为当前用户可以访问的 OneNote 内容(拥有和共享)使用 meUse me for OneNote content that the current user can access (owned and shared). 为指定用户已与当前用户共享的 OneNote 内容(此 URL 中)使用 users/{id}Use users/{id} for OneNote content that the specified user (in the URL) has shared with the current user. 使用 Microsoft Graph 获取用户 ID。Use Microsoft Graph to get user IDs.

GET 请求的权限Permissions for GET requests

若要获取 OneNote 内容或结构,需要请求相应的权限。To get OneNote content or structure, you'll need to request appropriate permissions.

以下范围允许对 Microsoft Graph 执行 GET 请求。The following scopes allow GET requests to Microsoft Graph. 选择应用运行所需的最低级别的权限。Choose the lowest level of permissions that your app needs to do its work.

从以下项中进行选择:Choose from:

  • Notes.readNotes.read
  • Notes.ReadWriteNotes.ReadWrite
  • Notes.ReadWrite.AllNotes.ReadWrite.All

有关权限范围及其工作方式的详细信息,请参阅 Microsoft Graph 权限引用For more information about permission scopes and how they work, see Microsoft Graph permissions reference.

另请参阅See also