OneNote ページの作成Create OneNote pages

適用対象: OneDrive のコンシューマー ノートブック | Office 365 のエンタープライズ ノートブックApplies to: Consumer notebooks on OneDrive | Enterprise notebooks on Office 365

OneNote ページを作成する場合は、POST 要求を pages エンドポイントに送信します。次に例を示します。To create a OneNote page, you send a POST request to a pages endpoint. For example:

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


メッセージ本文でページを定義する HTML を送信します。Send the HTML that defines the page in the message body. 要求が成功すると、Microsoft Graph は 201 HTTP 状態コードを返します。If the request is successful, Microsoft Graph returns a 201 HTTP status code.

注: セクション、セクション グループ、ノートブックを作成するために送信できる POST 要求の詳細については、対話型 REST リファレンスNote: To learn about the POST requests you can send to create sections, section groups, and notebooks, see our interactive REST reference.

要求 URI の構築Construct the request URI

POST 要求 URI を構築するには、サービス ルート URL から開始します。To construct the POST request URI, start with the service root URL:

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


次に、pages エンドポイントを追加します。Then append the pages endpoint:

  • 任意のセクション (セクション名で指定) にページを作成するCreate a page in any section (specified by section name)

    .../pages?sectionName=DefaultSection

  • 任意のセクション (ID で指定) にページを作成するCreate a page in any section (specified by ID)

    .../sections/{section-id}/pages

ユーザーの個人用ノートブックにページを作成する場合は、Microsoft Graph が提供する、既定のノートブックにページを作成するためのエンドポイントを使用することもできます。If you're creating pages in the user's personal notebook, Microsoft Graph also provides endpoints you can use to create pages in the default notebook:

  • 既定のノートブックの既定のセクションにページを作成するCreate a page in the default section of the default notebook

    ../pages

完全な要求 URI は、次に示す例のいずれかのようになります。Your full request URI will look like one of these examples:

  • https://graph.microsoft.com/v1.0/me/onenote/sections/{id}/pages
  • https://graph.microsoft.com/v1.0/me/onenote/pages?sectionName=Homework

サービス ルート URL の詳細についてはリンク先を参照してください。Learn more about the service root URL.

sectionName URL パラメーターの使用Using the sectionName URL parameter

次に示すルールは、sectionName パラメーターを使用して、既定のノートブックの指名したセクションにページを作成するときに適用されます。The following rules apply when using the sectionName parameter to create a page in a named section in the default notebook:

  • 最上位のセクションのみを参照できます (セクション グループ内のセクションは参照できません)。Only top-level sections can be referenced (not sections within section groups).

  • 指定した名前のセクションが既定のノートブックに存在しない場合、そのセクションは API によって作成されます。If a section with the specified name doesn't exist in the default notebook, the API creates it. セクション名に使用できない文字は、「? * \ / : < > | & # " % ~」です。These characters are not allowed for section names: ? * \ / : < > | & # " % ~

  • セクション名の照合では、大文字と小文字が区別されませんが、セクションが作成されるときには大文字と小文字が維持されます。そのため、"My New Section" はこのとおりに表示されますが、これ以降の POST では "my new section" も一致します。Section names are case-insensitive for matching, but case is preserved when sections are created. So "My New Section" will display like that, but "my new section" would also match on subsequent posts.

  • セクション名は、URL エンコードされている必要があります。たとえば、スペースは %20 とエンコードされなければなりません。Section names must be URL-encoded. For example, spaces must be encoded as %20.

  • sectionName パラメーターは、../notes/pages のルートでのみ有効になります (../notes/sections/{id}/pages では無効です)。The sectionName parameter is valid only with the ../notes/pages route (not ../notes/sections/{id}/pages).

セクションは存在しない場合に作成されるため、この呼び出しはアプリで作成するすべてのページに使用しても問題ありません。Because sections are created if they don't exist, it's safe to use this call with every page your app creates. セクションの名前はユーザーが変更する可能性もありますが、API は指定されたセクション名で新しいセクションを作成します。Users might rename sections, but the API will create a new section with the section name that you supply.

注: API から返された、名前を変更したセクション内のページへのリンクは、引き続き元のページに到達します。Note: The links returned by the API for pages in a renamed section will still reach those older pages.

メッセージ本文の構築Construct the message body

ページのコンテンツを定義する HTML は、入力 HTML と呼ばれます。入力 HTML は、標準の HTML および CSS のサブセットと、追加のカスタム属性をサポートしています。(data-iddata-render-src のようなカスタム属性は入力および出力 HTML で記述されます)。The HTML that defines page content is called input HTML. Input HTML supports a subset of standard HTML and CSS, with the addition of custom attributes. (Custom attributes, like data-id and data-render-src, are described in Input and output HTML.)

入力 HTML は、POST 要求のメッセージ本文で送信します。入力 HTML は、application/xhtml+xml または text/html コンテンツ タイプを使用して、メッセージ本文に直接含めて送信することも、マルチパート要求の "Presentation" 部分に含めて送信することもできます。Send the input HTML in the message body of the POST request. You can send the input HTML directly in the message body using the application/xhtml+xml or text/html content type, or you can send it in the "Presentation" part of a multipart request.

次に示す例では、入力 HTML をメッセージ本文に直接含めて送信しています。The following example sends the input HTML directly in the message body.

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>

バイナリ データを送信する場合は、マルチパート要求を使用する必要があります。If you're sending binary data, you must use a multipart request.

注: プログラミングを簡単にして、アプリでの一貫性を保つために、すべてのページの作成にマルチパート要求を使用できます。Note: To simplify programming and consistency in your app, you can use multipart requests to create all pages. マルチパート メッセージを作成するライブラリの使用をお勧めします。It's a good idea to use a library to construct multipart messages. これにより、無効な形式のペイロードを作成してしまう危険性が少なくなります。This reduces the risk of creating malformed payloads.

POST pages 要求の入力 HTML に対する要件と制限事項Requirements and limitations for input HTML in POST pages requests

入力 HTML を送信するときには、次に示す一般的な要件と制限事項に注意してください。When sending input HTML, be aware of these general requirements and limitations:

  • 入力 HTML は、UTF-8 でエンコードされた整形式の XHTML である必要があります。Input HTML should be UTF-8 encoded and well-formed XHTML. すべてのコンテナーの開始タグは、終了タグと一致する必要があります。All container start tags require matching closing tags. すべての属性値は、二重引用符または一重引用符で囲む必要があります。All attribute values must be surrounded by double- or single-quote marks.

  • JavaScript コード (ファイルを含む) および CSS は削除されます。JavaScript code, included files, and CSS are removed.

  • HTML フォームは全体が削除されます。HTML forms are removed in their entirety.

  • Microsoft Graph は HTML 要素のサブセットをサポートします。Microsoft Graph supports a subset of HTML elements.

  • Microsoft Graph は一般的な HTML 属性のサブセットとカスタム属性のセットをサポートします (ページの更新に使用される data-id 属性など)。Microsoft Graph supports a subset of common HTML attributes and a set of custom attributes, such as the data-id attribute used for updating pages. サポートされる属性については、「入出力 HTMLFor supported attributes, see Input and output HTML.

OneNote ページでサポートされる HTML と CSSSupported HTML and CSS for OneNote pages

すべての要素、属性、およびプロパティがサポートされるわけではありません (HTML4、XHTML、CSS、HTML5 などについて)。Not all elements, attributes, and properties are supported (in HTML4, XHTML, CSS, HTML5, etc.). Microsoft Graph は、ユーザーの OneNote の使用方法に適した、限定的な HTML のセットを受け入れます。Instead, Microsoft Graph accepts a limited set of HTML that better fits how people use OneNote. 詳細については、「ページでサポートされる HTML タグ」を参照してください。For more information, see HTML tag support for pages. この参照先に示されていないタグは、無視されることがあります。If a tag's not listed there, it'll probably be ignored.

次に、Microsoft Graph でサポートされる基本的な要素の種類の一覧を示します。The following list shows the basic element types that Microsoft Graph supports:

  • <head><body><head> and <body>

  • <title><meta> (ページのタイトルと作成日を設定する)<title> and <meta> that set the page title and creation date

  • <h1> から <h6> (セクションの見出し用)<h1> through <h6> for section headings

  • <p> (段落用)<p> for paragraphs

  • <ul><ol>、および <li> (リストおよびリスト アイテム用)<ul>, <ol>, and <li> for lists and list items

  • <table><tr>、および <td> (入れ子になったテーブルを含む)<table>, <tr> and <td>, including nested tables

  • <pre> (書式設定済みのテキスト用であり、空白と改行が維持される)<pre> for preformatted text (preserves white space and line breaks)

  • <b><i> (太字および斜体文字スタイル用)<b> and <i> for bold and italic character styles

Microsoft Graph は、ページの作成時に入力 HTML の意味内容と基本的構造を維持しますが、サポートされている HTML および CSS のセットを使用するように入力 HTML を変換します。Microsoft Graph preserves the semantic content and basic structure of the input HTML when it creates pages, but it converts the input HTML to use the supported set of HTML and CSS. OneNote に存在しない機能は変換されないため、ソース HTML では認識されない可能性があります。Features that don't exist in OneNote have nothing to be translated to, so they might not be recognized in the source HTML.

要求の例Example request

ここに示すマルチパート要求の例では、イメージと埋め込みファイルが含まれたページを作成します。This example multipart request creates a page that contains images and an embedded file. 必須の Presentation パーツには、ページを定義する入力 HTML が含まれています。The required Presentation part contains the input HTML that defines the page. imageBlock1 パーツにはバイナリ イメージ データが含まれ、fileBlock1 にはバイナリ ファイル データが含まれています。The imageBlock1 part contains the binary image data, and fileBlock1 contains the binary file data. データ パーツには、Microsoft Graph が OneNote ページに画像として HTML をレンダリングする場合の HTML を含めることもできます。Data parts can also contain HTML, in which case Microsoft Graph renders the HTML as an image on the OneNote page.

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--

複数イメージやその他のファイルを含むページの作成方法を示す例については、「画像とファイルを追加する」、およびチュートリアルサンプルを参照してください。また、絶対配置要素の作成方法、ノート シールの使用方法と、名刺キャプチャ、オンラインのレシピ一覧およびオンラインの製品一覧のデータ抽出方法について調べてください。For more examples that show how to create pages that contain images and other files, see Add images and files, our tutorials, and our samples. Also, learn how to create absolute positioned elements, use note tags, and extract data for business card captures and online recipe and product listings.

Microsoft Graph は、マルチパート メッセージ本文の CRLF 改行など、一部の書式設定については厳密です。Microsoft Graph is strict about some formats, such as CRLF newlines in a multipart message body. 無効な形式のペイロードを作成してしまう危険性を少なくするために、マルチパート メッセージはライブラリを使用して作成してください。To reduce the risk of creating malformed payloads, you should use a library to construct multipart messages.

無効な形式のペイロードに関する 400 状態を受信した場合は、改行と空白の書式を確認し、エンコーディングの問題について調べます。If you do receive a 400 status for a malformed payload, check the formatting of newlines and whitespaces, and check for encoding issues. たとえば、charset=utf-8 を使用してみてください (例: Content-Type: text/html; charset=utf-8)。For example, try using charset=utf-8 (example: Content-Type: text/html; charset=utf-8).

入力 HTML に対する要件と制限事項 および POST 要求のサイズ制限を参照してください。See requirements and limitations for input HTML and size limits for POST requests.

POST pages 要求の要求情報と応答情報Request and response information for POST pages 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.

Content-Type ヘッダーContent-Type header

HTML コンテンツの text/html または application/xhtml+xml。メッセージ本文またはマルチパート要求の必須の "Presentation" パートで直接送信します。text/html or application/xhtml+xml for the HTML content, whether it's sent directly in the message body or in the required "Presentation" part of multipart requests.

マルチパート要求はバイナリ データを送信するときに必須であり、コンテンツ タイプとして multipart/form-data; boundary=part-boundary を使用します。{part-boundary} は、各データ パートの開始と終了を伝える文字列です。Multipart requests are required when sending binary data, and use the multipart/form-data; boundary=part-boundary content type, where {part-boundary} is a string that signals the start and end of each data part.

Accept ヘッダーAccept header application/json

応答データResponse data 説明Description
成功コードSuccess code 201 HTTP ステータス コード。A 201 HTTP status code.
応答本文Response body JSON 形式での新しいページの OData 表現。A OData representation of the new page in JSON format.
エラーErrors 要求が失敗すると、API は応答本文の **@api.diagnostics** オブジェクトでエラーを返します。If the request fails, the API returns errors in the **@api.diagnostics** object in the response body.
Location ヘッダーLocation header 新しいページのリソース URL。The resource URL for the new page.
X-CorrelationId ヘッダーX-CorrelationId header 要求を一意に識別する GUID。Microsoft サポートと問題のトラブルシューティングを行う際に、この値を Date ヘッダーの値とともに使用できます。A GUID that uniquely identifies the request. You can use this value along with the value of the Date header when working with Microsoft support to troubleshoot issues.

Microsoft Graph サービスのルート URL の構築Constructing the Microsoft Graph service root URL

Microsoft Graph サービスのルート URL は、Microsoft Graph へのすべての呼び出しで次の形式を使用します。The Microsoft Graph service root URL uses the following format for all calls to Microsoft Graph:

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. ベータ版の機能は変更される可能性があるため、運用コードでは使用しないでください。Features and functionality in beta may change, so you shouldn't use it in your production code.

現在のユーザーがアクセスできる OneNote コンテンツには me を使用します (所有と共有)。Use me for OneNote content that the current user can access (owned and shared). 指定されたユーザー (URL 内) が現在のユーザーと共有している OneNote コンテンツには users/{id} を使用します。Use users/{id} for OneNote content that the specified user (in the URL) has shared with the current user. ユーザー ID を取得するには Microsoft Graph を使用します。Use Microsoft Graph to get user IDs.

アクセス許可Permissions

OneNote ページを作成するには、適切なアクセス許可を要求する必要があります。アプリの動作に必要な最低限のアクセス許可を選択してください。To create OneNote pages, you'll need to request appropriate permissions. Choose the lowest level of permissions that your app needs to do its work.

次から選択します。Choose from:

  • Notes.CreateNotes.Create
  • 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