OneNote ページの作成

[アーティクル]
03/16/2023

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

OneNote ページを作成する場合は、POST 要求を pages エンドポイントに送信します。たとえば次のようにします。

POST ../notes/sections/{id}/pages

メッセージ本文でページを定義する HTML を送信します。要求が成功すると、Microsoft Graph は 201 HTTP 状態コードを返します。

注:

セクション、セクショングループ、ノートブックを作成するために送信できる POST 要求について調べるために、対話型 REST リファレンスをご覧ください。

要求 URI の構築

POST 要求 URI を構築するには、サービスルート URL から開始します。

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

次に、pages エンドポイントを追加します。

任意のセクション (セクション名で指定) にページを作成する

.../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 URL パラメーターを使用する

次に示すルールは、sectionName パラメーターを使用して、既定のノートブックの指名したセクションにページを作成するときに適用されます。

最上位のセクションのみを参照できます (セクショングループ内のセクションは参照できません)。
指定した名前のセクションが既定のノートブックに存在しない場合、そのセクションは API によって作成されます。セクション名に使用できない文字は、「? * \ / : < > | & # " % ~」です。
セクション名の照合では、大文字と小文字が区別されませんが、セクションが作成されるときには大文字と小文字が維持されます。そのため、"My New Section" はこのとおりに表示されますが、これ以降の POST では "my new section" も一致します。
セクション名は URL エンコードを適用する必要があります。たとえば、スペースは %20 としてエンコードする必要があります。
sectionName パラメーターは、../notes/pages のルートでのみ有効になります (../notes/sections/{id}/pages では無効です)。

セクションは存在しない場合に作成されるため、この呼び出しはアプリで作成するすべてのページに使用しても問題ありません。セクションの名前はユーザーが変更する可能性もありますが、API は指定されたセクション名で新しいセクションを作成します。

注:

API から返された、名前を変更したセクション内のページへのリンクは、引き続き元のページに到達します。

メッセージ本文の構築

ページコンテンツを定義する HTML は 、入力 HTML と呼ばれます。入力 HTML では、カスタム属性を追加して、標準の HTML と CSS のサブセットがサポートされています。 (data-id や data-render-src などのカスタム属性については、「入力と出力 HTML」で説明されています)。

入力 HTML は、POST 要求のメッセージ本文で送信します。または 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>

バイナリデータを送信する場合は、マルチパート要求を使用する必要があります。

注:

プログラミングを簡単にして、アプリでの一貫性を保つために、すべてのページの作成にマルチパート要求を使用できます。マルチパートメッセージを作成するライブラリの使用をお勧めします。これにより、無効な形式のペイロードを作成してしまう危険性が少なくなります。

POST pages 要求の入力 HTML に対する要件と制限事項

入力 HTML を送信するときには、次に示す一般的な要件と制限事項に注意してください。

入力 HTML は、UTF-8 でエンコードされた整形式の XHTML である必要があります。すべてのコンテナーの開始タグは、終了タグと一致する必要があります。すべての属性値は、二重引用符または一重引用符で囲む必要があります。
JavaScript コード (ファイルを含む) および CSS は削除されます。
HTML フォームは全体が削除されます。
Microsoft Graph は HTML 要素のサブセットをサポートします。
Microsoft Graph は一般的な HTML 属性のサブセットとカスタム属性のセットをサポートします (ページの更新に使用される data-id 属性など)。サポートされる属性については、「入出力 HTML

OneNote ページでサポートされる HTML と CSS

すべての要素、属性、およびプロパティがサポートされるわけではありません (HTML4、XHTML、CSS、HTML5 などについて)。 Microsoft Graph は、ユーザーの OneNote の使用方法に適した、限定的な HTML のセットを受け入れます。詳細については、「ページでサポートされる HTML タグ」を参照してください。この参照先に示されていないタグは、無視されることがあります。

次に、Microsoft Graph でサポートされる基本的な要素の種類の一覧を示します。

<head> と <body>
<title> と <meta> (ページのタイトルと作成日を設定する)
<h1> から <h6> (セクションの見出し用)
<p> (段落用)
<ul>、<ol>、および <li> (リストおよびリストアイテム用)
<table>、<tr>、および <td> (入れ子になったテーブルを含む)
<pre> (書式設定済みのテキスト用であり、空白と改行が維持される)
<b> と <i> (太字および斜体文字スタイル用)

Microsoft Graph は、ページの作成時に入力 HTML の意味内容と基本的構造を維持しますが、サポートされている HTML および CSS のセットを使用するように入力 HTML を変換します。 OneNote に存在しない機能は変換されないため、ソース HTML では認識されない可能性があります。

要求の例

ここに示すマルチパート要求の例では、イメージと埋め込みファイルが含まれたページを作成します。必須の Presentation パーツには、ページを定義する入力 HTML が含まれています。 imageBlock1 パーツにはバイナリイメージデータが含まれ、fileBlock1 にはバイナリファイルデータが含まれています。データパーツには、Microsoft Graph が OneNote ページに画像として HTML をレンダリングする場合の 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 要求のサイズ制限を参照してください。

POST pages 要求の要求情報と応答情報

要求データ	説明
プロトコル	すべての要求は SSL/TLS HTTPS プロトコルを使用します。
承認ヘッダー	`Bearer {token}`。`{token}` は、登録済みアプリの有効な OAuth 2.0 アクセストークンです。これがないか、無効の場合、要求は失敗し、401 ステータスコードが表示されます。「認証とアクセス許可」を参照してください。
Content-Type ヘッダー	HTML コンテンツの `text/html` または `application/xhtml+xml`。メッセージ本文またはマルチパート要求の必須の "Presentation" パートで直接送信します。マルチパート要求はバイナリデータを送信するときに必須であり、コンテンツタイプとして `multipart/form-data; boundary=part-boundary` を使用します。`{part-boundary}` は、各データパートの開始と終了を伝える文字列です。
Accept ヘッダー	`application/json`

応答データ	説明
成功コード	201 HTTP ステータスコード。
応答本文	JSON 形式での新しいページの OData 表現。
エラー	要求が失敗すると、API は応答本文の @api.diagnostics オブジェクトでエラーを返します。
Location ヘッダー	新しいページのリソース URL。
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 を使用します。

OneNote のセクションサイズ制限

OneNote API を使用してセクションに追加できるページの数には制限があります。セクションがこの制限に達した状態で、そのセクションに新しいページを作成しようとすると、HTTP ステータスコード 507 とともに「セクションごとに許可されている最大ページ数を超えました」というメッセージが表示されます。このエラーコードの詳細については、「OneNote のエラーコード」を参照してください。

次のいずれかの回避策を使用できます。

新しいセクションを作成し、そこに新しいページを追加します。
ページ制限に達した既存のセクションの使用されていないページを削除します。

アクセス許可

OneNote ページを作成するには、適切なアクセス許可を要求する必要があります。アプリの動作に必要な最低限のアクセス許可を選択してください。

次から選択します。

Notes.Create
Notes.ReadWrite
Notes.ReadWrite.All

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

OneNote ページの作成

要求 URI の構築

sectionName URL パラメーターを使用する

メッセージ本文の構築

POST pages 要求の入力 HTML に対する要件と制限事項

OneNote ページでサポートされる HTML と CSS

要求の例

POST pages 要求の要求情報と応答情報

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

OneNote のセクションサイズ制限

アクセス許可

フィードバック

フィードバック

その他のリソース

OneNote ページの作成

要求 URI の構築

sectionName URL パラメーターを使用する

メッセージ本文の構築

POST pages 要求の入力 HTML に対する要件と制限事項

OneNote ページでサポートされる HTML と CSS

要求の例

POST pages 要求の要求情報と応答情報

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

OneNote のセクション サイズ制限

アクセス許可

関連コンテンツ

フィードバック

フィードバック

その他のリソース

OneNote のセクションサイズ制限