トレーニング
OneNote ページの作成
適用対象: OneDrive のコンシューマー ノートブック | Microsoft 365 のエンタープライズ ノートブック
OneNote ページを作成する場合は、POST 要求を pages エンドポイントに送信します。 たとえば次のようにします。
POST ../notes/sections/{id}/pages
メッセージ本文でページを定義する HTML を送信します。 要求が成功すると、Microsoft Graph は 201 HTTP 状態コードを返します。
注意
セクション、セクション グループ、ノートブックを作成するために送信できる POST 要求について調べるために、対話型 REST リファレンスをご覧ください。
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 パラメーターを使用して、既定のノートブックの指名したセクションにページを作成するときに適用されます。
最上位のセクションのみを参照できます (セクション グループ内のセクションは参照できません)。
指定した名前のセクションが既定のノートブックに存在しない場合、そのセクションは 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>
バイナリ データを送信する場合は、マルチパート要求を使用する必要があります。
注意
プログラミングを簡単にして、アプリでの一貫性を保つために、すべてのページの作成にマルチパート要求を使用できます。 マルチパート メッセージを作成するライブラリの使用をお勧めします。 これにより、無効な形式のペイロードを作成してしまう危険性が少なくなります。
入力 HTML を送信するときには、次に示す一般的な要件と制限事項に注意してください。
入力 HTML は、UTF-8 でエンコードされた整形式の XHTML である必要があります。 すべてのコンテナーの開始タグは、終了タグと一致する必要があります。 すべての属性値は、二重引用符または一重引用符で囲む必要があります。
JavaScript コード (ファイルを含む) および CSS は削除されます。
HTML フォームは全体が削除されます。
Microsoft Graph は HTML 要素のサブセットをサポートします。
Microsoft Graph は一般的な HTML 属性のサブセットとカスタム属性のセットをサポートします (ページの更新に使用される data-id 属性など)。 サポートされる属性については、「入出力 HTML
すべての要素、属性、およびプロパティがサポートされるわけではありません (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 要求のサイズ制限を参照してください。
要求データ | 説明 |
---|---|
プロトコル | すべての要求は SSL/TLS HTTPS プロトコルを使用します。 |
承認ヘッダー |
これがないか、無効の場合、要求は失敗し、401 ステータス コードが表示されます。 「認証とアクセス許可」を参照してください。 |
Content-Type ヘッダー | HTML コンテンツの マルチパート要求はバイナリ データを送信するときに必須であり、コンテンツ タイプとして |
Accept ヘッダー | application/json |
応答データ | 説明 |
---|---|
成功コード | 201 HTTP ステータス コード。 |
応答本文 | JSON 形式での新しいページの OData 表現。 |
エラー | 要求が失敗すると、API は応答本文の @api.diagnostics オブジェクトでエラーを返します。 |
Location ヘッダー | 新しいページのリソース URL。 |
X-CorrelationId ヘッダー | 要求を一意に識別する GUID。 Microsoft サポートと問題のトラブルシューティングを行うときに、この値を Date ヘッダーの値とともに使用できます。 |
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 API を使用してセクションに追加できるページの数には制限があります。 セクションがこの制限に達した状態で、そのセクションに新しいページを作成しようとすると、HTTP ステータス コード 507
とともに「セクションごとに許可されている最大ページ数を超えました」というメッセージが表示されます。 このエラー コードの詳細については、「OneNote のエラー コード」を参照してください。
次のいずれかの回避策を使用できます。
- 新しいセクションを作成し、そこに新しいページを追加します。
- ページ制限に達した既存のセクションの使用されていないページを削除します。
OneNote ページを作成するには、適切なアクセス許可を要求する必要があります。 アプリの動作に必要な最低限のアクセス許可を選択してください。
次から選択します。
- Notes.Create
- Notes.ReadWrite
- Notes.ReadWrite.All
アクセス許可の範囲とその動作方法の詳細については、「Microsoft Graph のアクセス許可のリファレンス」を参照してください。