OneNote コンテンツと構造を取得する

  • [アーティクル]

適用対象 OneDrive のコンシューマー ノートブック | Microsoft 365 のエンタープライズ ノートブック

Microsoft Graph OneNote API を使用して OneNote のコンテンツと構造を取得するには、GET リクエストをターゲット エンドポイントに送信します。 次に例を示します。

GET ../onenote/pages/{id}

要求が成功した場合、Microsoft Graph は HTTP 状態コードと、要求したエンティティまたはコンテンツを返 200 OK します。 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 要求のリソース パス

次のリソース パスを使用して、ページ、セクション、セクション グループ、ノートブック、画像、またはファイル リソースを取得します。

ページ コレクション

すべてのノートブックのページ (メタデータ) を取得する。

../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 のエントリのみが返されます。 上位クエリ文字列オプションを指定しない要求を行った場合、次の 20 エントリを取得するために使用できる @odata.nextLink リンクが応答で返されます。

セクションのページ コレクションの場合、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 プロパティには、パブリックの image resource のリンクが含まれます。 このリンクは 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]

セクション グループは、セクション、sectionGroups、parentNotebook、および parentSectionGroup プロパティを展開できます。

セクション グループの既定の並べ替え順序は name asc です。

既定のクエリは、親ノートブックおよび親セクション グループを展開し、id、name、および self プロパティを選択します。

SectionGroup エンティティ

特定のセクション グループを取得します。

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

セクション グループは、セクション、sectionGroups、parentNotebook、および parentSectionGroup プロパティを展開できます。

既定のクエリは、親ノートブックおよび親セクション グループを展開し、id、name、および self プロパティを選択します。

ノートブック コレクション

ユーザーによって所有されるすべてのノートブックを取得する。

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

ノートブックは、セクションおよび sectionGroups プロパティを展開できます。

ノートブックの既定の並べ替え順序は name asc です。

ノートブック エンティティ

特定のノートブックを取得します。

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

ノートブックは、セクションおよび sectionGroups プロパティを展開できます。

画像またはその他のファイル リソース

特定のリソースのバイナリ データを取得する。

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

ファイルのリソース URI は、ページの出力 HTML にあります。

たとえば、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

学校のノートブックにあるすべてのセクションの名前と 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 日以降に作成された最新の 5 つのページを取得します。 既定ではこの API は 20 エントリを返します。最大では 100 エントリを返します。 ページの既定の並べ替え順序は lastModifiedTime desc です。

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

上部 & スキップ & フィルター

結果セット内の次の 5 ページを取得します。

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

さらに、次の 5 ページを取得します。

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

注:

上位とフィルターの両方が同じ要求に適用される場合、結果には両方の条件に一致するエンティティのみが含まれます。

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 ページのタイトルと セルフ リンクを取得します。 既定ではこの 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

注:

既定のエントリ数を取得する pages に対する GET 要求 (つまり、top 式を指定しない要求) は、応答で次の 20 エントリを取得するために使用できる @odata.nextLink リンクを戻します。

サポートされている 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 の各プロパティを選択します。

1 つのエンティティまたはコレクションに使用できます。
コンマを使用して複数のプロパティを区切ります。
プロパティ名では、大文字と小文字を区別します。
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

返すプロパティ。 1 つのエンティティまたはコレクションに使用できます。 コンマを使用して複数のプロパティを区切ります。 プロパティ名では、大文字と小文字を区別します。
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 は、フィルター式で次の 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

論理演算子 例
and createdTime le 2014-01-30 and createdTime gt 2014-01-23
or createdByAppId eq '{app-id}' or createdByAppId eq '{app-id}'
not not contains(tolower(title),'school')

String 関数 例
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 プロトコルを使用します。
承認ヘッダー

Bearer {token}。{token} は、登録済みアプリの有効な OAuth 2.0 アクセス トークンです。

これがないか、無効の場合、要求は失敗し、401 ステータス コードが表示されます。 「認証とアクセス許可」を参照してください。
Accept ヘッダー

OneNote エンティティとエンティティ セットの場合、application/json

ページ コンテンツの場合、text/html

応答データ 説明
成功コード 200 HTTP ステータス コード。
応答本文 JSON 形式のエンティティまたはエンティティ セット、ページ HTML、またはファイル リソースのバイナリ データの OData 表現。
エラー 要求が失敗すると、API は応答本文の @api.diagnostics オブジェクトにエラーを返します。
X-CorrelationId ヘッダー 要求を一意に識別する GUID。 Microsoft サポートと問題のトラブルシューティングを行うときに、この値を Date ヘッダーの値とともに使用できます。

Microsoft Graph のノート サービスのルート URL の構築

Microsoft Graph ノートのルート URL は、Microsoft Graph ノートへのすべての呼び出しで次の形式を使用します。

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

URL の version セグメントは、使用する Microsoft Graph のバージョンを示しています。 安定した運用コードには v1.0 を使用します。 開発中の機能を試すには beta を使用します。 ベータ版の機能は変更される可能性があるため、運用コードでは使用しないでください。

現在のユーザーがアクセスできる OneNote コンテンツには me を使用します (所有と共有)。 指定されたユーザー (URL 内) が現在のユーザーと共有している OneNote コンテンツには users/{id} を使用します。 ユーザー ID を取得するには Microsoft Graph を使用します。

GET 要求のアクセス許可

OneNote のコンテンツまたは構造を取得するには、適切なアクセス許可を要求する必要があります。

次のスコープは、Microsoft Graph に対する GET 要求を許可します。 アプリの動作に必要な最低限のアクセス許可を選択してください。

次から選択します。

  • Notes.read
  • Notes.ReadWrite
  • Notes.ReadWrite.All

アクセス許可の範囲とその動作方法の詳細については、「Microsoft Graph のアクセス許可のリファレンス」を参照してください。

関連コンテンツ