OneNote API HTML タグ サポート
Microsoft OneNote API が Presentation コンテンツ内で受け入れることができるのは、限定された HTML タグです。使用できるタグは OneNote ページで利用可能な機能に対応しており、その内容についてこのトピックで説明します。
**適用対象:**OneNote service
OneNote のページ構造を定義する HTML には次のような要件があります。
HTML は UTF-8 でエンコードされている必要があります。
信頼性を高めるため、HTML は整形式であるべきです。内容のあるすべてのタグには終了タグが必要です (例: <p>All paragraphs need closing tags</p>)。内容が空のすべてのタグには末尾のスラッシュが必要です (例: <br/> および <img src="..."/>)。
すべての属性値は、上記の img タグのように、二重引用符または単一引用符で囲む必要があります。
HTTP POST の本文または "Presentation" という名前の MIME パートに入れて、アプリから OneNote API に HTML を提供するときには、次のような一般的な制限に注意してください。
Javascript コード、インクルードされたファイル、および CSS は削除されます。
HTML フォームは全体が削除されます。
OneNote ページの構造と内容になる HTML に加えて、<img data-render-src="..."> タグを使用してページ レンダリング機能に HTML を渡すこともできます。ページ レンダリング機能を使用すると、サポートされる HTML タグのセットは標準に準拠したブラウザーに近いものになり、生成された Web ページは OneNote ページにビットマップ形式の画像として挿入されます。このトピックでは、ページの POST 内で API によって認識されるタグのほか、画像のマークアップ、埋め込まれたファイル データ、レンダリングされる HTML ブロックについて説明します。
サポートされている HTML タグと制限事項
HTML タグ |
制限事項とコメント |
|---|---|
構造タグ |
|
<html> |
コンテンツを囲むために適切ですが、必須ではありません。 |
<head> |
|
<title> |
このタグの内容はページのタイトルとして使用されます (存在する場合)。このタグはオプションです。 |
<meta> |
通常、このタグは API によって無視されますが、name 属性が "created" の場合を除きます。「<meta> タグの詳細」セクションを参照してください。 |
<body> |
|
<div>, <span> |
これらのタグにあるスタイル設定は無視されます。 |
コンテンツ タグ |
|
<a> |
現時点で、このタグの内容にはテキストのみ指定できます。画像をリンクすることはできません。 |
<p>, <br/> |
<p> タグに関する重要な情報については、「<p> タグの詳細」セクションを参照してください。 |
<h1>...<h6> |
対応する OneNote の段落スタイルにマップされます。 |
<ul>, <ol>, <li> |
記号付きリストと番号付きリストが、入れ子になったリストを含めてサポートされます。type 属性は無視されます。 |
<img> |
このタグに関する重要な情報については、「<img> タグの詳細」セクションを参照してください。 |
<object> |
ファイル オブジェクトの埋め込みの場合のみ使用できます (「<object> タグの詳細」セクションを参照)。それ以外の場合は無視されます。 |
<table>, <tr>, <td> |
入れ子になった表を使用できます。これらは OneNote の表にマップされます。値を 1 つ指定する border 属性 (border="2") がサポートされます。<table> と <td> は width をピクセル数 (width="100px" など) または対ページ比 (width="60%"など) として受け入れます。 |
<b>, <em>, <strong>, <i>, <u>, <strike>, <del>, <sup>, <sub>, <cite>, <font> |
OneNote で使用可能な文字スタイルにマップされます。<font> タグは、face 属性および color 属性のみを受け入れます。 |
<meta> タグの詳細
次のコードは、単純な POST で meta タグを使用する方法を示しています。
Content-Type:multipart/form-data; boundary=BlockPartBoundary
--BlockPartBoundary
Content-Disposition:form-data;name="Presentation"
Content-Type:application/xhtml+xml
<?xml version="1.0">
<html>
<head>
<title>Example showing how to set the creation data-time</title>
<meta name="created" content="2013-06-11T06:30:00-08:00"/>
</head>
<body>
<p>The head tag sets the created data and time of the capture.</p>
</body>
</html>
--BlockPartBoundary--
OneNote API では特定の種類の meta タグを認識して、新しい OneNote ページの作成日時を設定します。name="created" 属性を含める必要があり、content 属性に ISO 8601 標準のタイムスタンプを指定する必要があります。タイムスタンプには、必要に応じて UTC タイムゾーン オフセットを含めます。この meta タグを指定しない場合、ページの作成日時はブランクになります。オプションとして、OneNote API では、日時なしのタイムゾーン オフセットのみの指定を受け入れることができ、そのタイムゾーンでのページ作成日時がページの作成日時に設定されます。次のコードは、この使用方法を示します。
<meta name="created" content="-08:00" />
<p> タグの詳細
最新の CSS が実装されているブラウザーでは、<p> タグに様々な style 属性を指定できます。これらのいくつかは、新しい OneNote ページを作成するために OneNote API に POST する場合に <p> タグでサポートされます。
background-color:#HEXCODE はテキストを強調表示します。16 進数の #RRGGBB 形式と名前付きの色 (red など) が受け入れられます。
color:#HEXCODE は、テキストの色を指定します。16 進数の #RRGGBB 形式と名前付きの色 (red など) が受け入れられます。
font-family:fontName1, fontName2,… は、使用するフォントを示します。フォント名がデバイスで利用できなければならず、OneNote はリストの最初の名前のみを使用します。
font-size:XXpx は、フォントの文字サイズをピクセル単位で指定します。Point-size (12pt など) やその他のフォント サイズを指定する方法は、認識されません。
次のコードは、サポートされるスタイル属性を使用した段落タグを示しています。
<p style="color:#00FFFF; font-family:Garamond; font-size:28px; background-color:#000000">
This paragraph shows yellow, 28-pixel Garamond text on a black background</p>
<img> タグの詳細
img タグは、キャプチャの中に画像を組み込むために使用します。画像を組み込む方法は 3 つあります。標準的な HTML ページと同様にインターネット上の画像を参照する方法、キャプチャ POST 内に直接画像データを組み込む方法、OneNote API によって Web ページのサムネイルを埋め込む方法です。
画像の属性
OneNote API では、次に挙げる属性を img タグでサポートしています。
src="http://..." は、画像ソースを指定する HTML の標準的な方法で、インターネット上で公開されている画像の場合に OneNote ページに組み込まれます。
src="name:BlockName" は、OneNote ページ内でこの画像に使用するバイナリ画像データを含む POST 内の MIME パート名を指定します。
data-render-src="http://…" は、OneNote API によって認識される属性です。URL を指定すると、Web ブラウザーに表示されるのと同じ Web ページのビットマップ形式の画像がページ レンダリング サービスによって新しい OneNote ページに挿入されます。
data-render-src="name:BlockName" は、OneNote API によって認識される属性です。属性値が name:... という形式になっている場合、POST 内の MIME パート名とそこに含まれている画像としてレンダリングする HTML を示します。生成されたビットマップ画像が新しい OneNote ページに挿入されます。この部分が PDF ファイル (content-type:application/pdf) の場合、各ページはページの別の画像としてレンダリングされます。
alt は、スクリーン リーダーによって使用され、画像をレンダリングできない場合にも使用される代替テキストです。
height は、画像が OneNote ページに挿入されるときの高さ (ピクセル) です。単位は常にピクセルです。画像がマルチページの PDF ファイルからのものである場合、高さはすべてのページを合わせた合計の高さを指定します。各画像のサイズを指定するには、PDF ファイルのページに必要な高さにページ数を掛けます。
height は、画像が OneNote ページに挿入されるときの幅 (ピクセル) です。
style は、幅と高さの最大値を設定するために使用できます: style=”max-width:150px; max-height:200px”
画像を使用する場合の制限
OneNote API による取り込みデータの中に画像を埋め込む場合は、以下の制限事項に注意してください。これらの制限を解除または拡張する方向で作業を進めていますが、現時点ではこれらの制限があります。
**合計の POST サイズは 70 MB までという制限があります。**これには、ファイルとその他のデータが含まれます。この制限を上回るデータを取り込むと、アプリや取り込みデータが不安定になりますので、ご注意ください。
**MIME パートのサイズ制限は 25 MB です。**これより大きいデータ ブロックは、API によって拒否されます。これはイメージ パートとファイル データ パートの両方に当てはまり、サイズにはパート ヘッダーも含まれます。
**画像の制限は、ページあたり 150 個です。**src="internetURL" 属性を使用する場合、この制限数を超える <img> タグは API によって無視されます。
**MIME パートの数は POST あたり 6 個までに制限されています。**この数には、Presentation HTML パートも含まれます。
**data-render-src を使用する <img/> および <object/> タグの最大数は、5… または 1 です。**つまり、使用できるイメージは 5 個までですが、<img data-render-src="name:blockName"> タグを使用して表示できる PDF ドキュメントは 1 つだけです。この数を超えるレンダリング イメージおよび埋め込みファイルは無視されます。
**ファイルの種類のアイコンは事前に定義されています。**OneNote API は、幅広い種類の一般的なファイルを認識し、事前に定義されたアイコンを使用してそのファイルを埋め込みます。API がファイルの種類を認識できない場合は、汎用のファイル アイコンが使用されます。
URL による画像の参照
キャプチャ HTML に標準の <img src="..."/> タグが含まれている場合、src 属性には画像の通常の URL を指定します。OneNote API はその画像のコピーをインターネットから取得し、ページに直接挿入します。img タグに height 属性または width 属性 (単位は常にピクセル) が含まれる場合、それらの値は新しい OneNote ページ上での画像のサイズを決めるために使用されます。次のコードで例を示します。
<img src="http://officeimg.vo.msecnd.net/en-us/files/018/949/ZA103278226.png"
height="180" width="345"/>
URL によって画像を参照する場合は、公衆インターネット上で OneNote が画像を利用可能であることを確認してください。API が取得できない画像の URL を指定すると、その画像はキャプチャされたページに表示されません。
POST 内に画像を組み込む
別の方法として、最大 150 個までの画像のデータを OneNote API POST 内に直接配置して送信することもできます。この方法は、モバイル デバイスのカメラから画像を取得する場合や、スキャナーやカメラのようなハードウェア デバイス上で実行されるアプリの場合に一般的に利用されます。インターネット上で利用可能な画像であっても、データを POST 内に埋め込むと、OneNote ページを作成するために必要なラウンド トリップの合計数が削減されるため、キャプチャしたページを OneNote ユーザーが使用できるようになるまでの時間を短縮できることがあります。
画像を POST 内に埋め込むには、src 属性に "name:BlockName" という値を指定します。name プレフィックスを指定すると、属性値の残りの部分が POST 内の MIME パートの名前であることを OneNote API に指示できます (詳細については、「Pages REST API」を参照してください)。
次の例は、埋め込んだ画像を示しています。(わかりやすくするため、HTTP ヘッダーと、画像に無関係のコードを取り除いてあります)。
Content-Type:multipart/form-data; boundary=NewPart12345
--NewPart12345
Content-Disposition:form-data; name="Presentation"
Content-Type:text/html
<!DOCTYPE html>
<html>
<body>
<img src="name:imageDataPart1" width="50" height="50"/>
</body>
</html>
--NewPart12345
Content-Disposition:form-data; name="imageDataPart1"
Content-Type:image/jpeg
...binary image data...
--NewPart12345--
重要な点ですが、バイナリー画像データに Base64 やその他のエンコードは不要です。そのため、アプリの側でも OneNote API の側でも通信時に時間を節約できます。さらに、OneNote API は、POST に組み込まれた画像データ ブロックの最初の 150 個だけを使用することに注意してください。
Web ページを画像としてキャプチャする
OneNote API では、キャプチャしたページ内の画像として Web ページのスクリーン ショットを組み込むことができます。Web ページとしては、URL で参照できる公開されたインターネット Web ページを使用することも、MIME パートに HTML として提供することもできます。これは、ユーザーがセールス品を購入しようと調査している時や、特定の時点でページがどのように表示されているかを記録したい時など、実際に表示されている Web ページをキャプチャする場合に便利です。
この方法で Web ページをキャプチャする場合は、キャプチャした OneNote ページ内に画像を表示する大きさを height および width 属性を使用して OneNote に指示します。これは、実際のページと必ずしも同じにする必要はありません。Web ページの画像を元のサイズで OneNote に表示する場合は、img タグに height および width 属性を含めないでください。
OneNote にページを画像としてレンダリングするように指示するには、img タグに data-render-src 属性を含めます。ブラウザーが img タグを表示する時点で、data-render-src 属性は意味を持たず、その代わりにブラウザーは通常の src 属性を使用します。img タグが OneNote API にポストされた時点で、data-render-src 属性の指定内容を使用して情報のスクリーン ショットをどのように作成するかを決定します。
data-render-src 属性を使用する方法は 2 つあります。次のように値を指定します。
data-render-src="https://www.onenote.com" を指定した場合、API では Web ページの JPEG プレビューを生成し、キャプチャしたページにそれを挿入します。
data-render-src="name:imageDataPartName" を指定した場合、API では imageDataPartName 値に指定された POST データ パートから HTML を取得し、その HTML の JPEG プレビューを生成し、その JPEG 画像をページに挿入します。
次の例は、Web ページのレンダリングされた画像を組み込む両方の方法を示しています。
Content-Type:multipart/form-data; boundary= NewPart12345
--NewPart12345
Content-Disposition:form-data; name="Presentation"
Content-Type:text/html
<!DOCTYPE html>
<html>
<body>
<p>This first image embeds a screen-shot of the onenote.com web site.</p>
<img data-render-src="https://www.onenote.com" width="500"/>
<p>This second image embeds a bit of HTML in the next multi-part
block as a screen-shot</p>
<img data-render-src="name:htmlPart" width="500"/>
</body>
</html>
-- NewPart12345
Content-Disposition:form-data; name="htmlPart"
Content-Type:text/HTML
<html>
<body>
<h1>This will be rendered in an image<h1>
<p style="font-weight:bold">and so will this text. Don't try to embed another
data-render-src type image inside the HTML part; it won't
work. Instead, use URL-based real images like this:</p>
<img src="http://officeimg.vo.msecnd.net/en-us/files/018/949/ZA103278226.png"
height="180" width="345"/>
</body>
</html>
-- NewPart12345--
.
レンダリングするために別個の MIME パートに組み込む HTML では、このトピックで列挙したタグには限定されません。レンダリング エンジンは標準 Web ブラウザーに近いものですが、ブラウザーのプラグインとアクティブ コンテンツに関連していくつかの制限事項があります。キャプチャしたページに、レイアウトが複雑なページをそのまま表示する必要がある場合は、その複雑な HTML を画像として組み込むほうが適切な場合があります。
Web ページのレンダリングでは data-render-src 属性が認識されないため、HTML パート内部にその属性を含めることはできません。
ヒント
ページのレンダリングにはユーザーとしてログインする機能がないため、data-render-src に URL を指定して送信するだけでは、ログインを必要とするページがユーザーの期待どおりには表示されない恐れがあります。たとえば、ユーザーが購入履歴またはアカウント状況を閲覧している時にページをキャプチャしようとした場合、アプリの側で現在の URL に data-render-src 属性を指定した img を使用するとき、通常はサムネイルはサイトのログインページになるか、もっと悪い場合には "アクセスが拒否されました" のページになります。このようなケースでは、ページの HTML を取得し、それを POST 内の名前を指定したパートに入れて送信するほうが適切です。ただし、特にログインしたユーザーしか取得できない画像が HTML に含まれている場合など、この方法にはリスクが伴うことに注意してください。
<object> タグの詳細
object タグを使用すると、ファイルを OneNote ページ上に直接埋め込み、ファイルの種類を表すアイコンとして表示することができます。img タグとは違って、ファイルの実際の内容が表示されることはありません。object タグから参照するデータは、POST 要求の MIME パートに提供する必要があり、URL 参照にすることはできません。
オブジェクトの属性
object タグは、異なるブラウザー プラグインによってさまざまに異なる方法で利用され、標準の定義が公開されています。OneNote API ではこの柔軟性を活用し、object タグの次のような属性をサポートしています。
data-attachment="DisplayedFileName.extension" は、OneNote ページ上に表示されるファイルのファイル名と拡張子を指定します。この値は、ユーザーがファイルを OneNote ページからアクティブ化することによってファイルを保存するときにも使用されます。
data="name:PartName" は、OneNote ページに埋め込むファイルのデータを含む POST 内の MIME パート名を指定します。埋め込むファイルを追加するには、必ずマルチパートの POST 要求に直接データを入れて送信する必要があります。
type="standardMIMEtype" は、埋め込むファイルの種類を OneNote API に知らせます。指定する MIME タイプは必ずファイルのデータと同じタイプにしてください。そうしない場合、その POST 要求に対して OneNote API がエラーを返す可能性があります。
OneNote ページに表示される埋め込まれたファイルのアイコンは、次の優先順位で決定されます。
data-attachment 属性で指定された ファイル名拡張子。もしそれを認識できない場合は…
type 属性 を確認して MIME タイプが認識されます。もしそれを認識できない場合は…
ファイル データの MIME パートの content-type ヘッダー が確認されます。もしそれを認識できない場合は…
既定の "ドキュメント" アイコンが使用されます。
OneNote API による取り込みデータの中にファイルを埋め込む場合は、以下の制限事項に注意してください。これらの制限を解除または拡張する方向で作業を進めていますが、現時点ではこれらの制限があります。
**合計の POST サイズは 70 MB までという制限があります。**これには、ファイルとその他のデータが含まれます。この制限を上回るデータを取り込むと、アプリや取り込みデータが不安定になりますので、ご注意ください。
**MIME パートのサイズ制限は 25 MB です。**これより大きいデータ ブロックは、API によって拒否されます。これはイメージ パートとファイル データ パートの両方に当てはまり、サイズにはパート ヘッダーも含まれます。
**MIME パートの数は POST あたり 6 個までに制限されています。**この数には、Presentation HTML パートも含まれます。
data-render-src を使用した <img/> タグおよび <object/> タグの最大数は 5 です。レンダリングされる追加の画像と埋め込みファイルは無視されます。
**ファイルの種類のアイコンは事前に定義されています。**OneNote API は、幅広い種類の一般的なファイルを認識し、事前に定義されたアイコンを使用してそのファイルを埋め込みます。API がファイルの種類を認識できない場合は、汎用のファイル アイコンが使用されます。
次のコードは、REST を使用してファイルを埋め込む方法を示しています。
Content-Type:multipart/form-data; boundary=MyAppPartBoundary
Authorization:bearer tokenString
--MyAppPartBoundary
Content-Disposition:form-data; name="Presentation"
Content-type:text/html
<!DOCTYPE html>
<html>
<head>
<title>A simple page with an embedded file</title>
</head>
<body>
<p>This is a simple Presentation block.</p>
<p>This next object tag specifies the file data in this POST request.</p>
<object data-attachment="Logo.jpg" data="name:MyAppFilePartName"
type="image/jpeg" />
</body>
</html>
--MyAppPartBoundary
Content-Disposition:form-data; name="MyAppFilePartName"
Content-type:image/jpeg
... embedded file binary data ...
--MyAppPartBoundary--
HTML ブロックの例
次に示す HTML ブロックは、OneNote API によってサポートされるタグの多くを示しています。(body タグの style 属性は単に指定しているだけあり、ブラウザーで表示して見苦しいことはありません。)
<html>
<head>
<title>HTML sample block</title>
<meta name="created" content="2013-06-11T06:30:00-08:00"/>
</head>
<body style="font-family:Arial;">
<h1>HTML sample block</h1>
<h2>The basics</h2>
<p>For the most part, try to keep the HTML simple, and be
sure to properly close all tags.</p>
<p>Character encoding must be in UTF-8; the API doesn't
accept other encodings</p>
<h2>Overall structure</h2>
<p>The normal <html>, <head> and <body> tags are
expected, but the API is usually okay if they aren't included.</p>
<p>Inside the <head> tag, we recognize only the <title> and
One form of the <meta> tags.</p>
<p>All includes, CSS, script, etc. inside the <head> and <body>
blocks are ignored.</p>
<p>As you can tell from the <body> tag's style attribute, in this
HTML, the API ignores CSS styles</p>
<h2>Block formatting</h2>
<p>Paragraph (<p>) and line-break (<br/>) tags are handled
properly. They get the "Normal" OneNote styling</p>
<p>The <div> and <span> tags are recognized but generally
don't have any significant effect, since CSS styling is ignored. A
<div> tag acts like a <p> tag.</p>
<p>The header tags <h1> through <h6> are recognized, and
map to the OneNote Heading 1 through Heading 6 styles.</p>
<h2>Simple character formatting</h2>
<p>This paragraph shows how the API handles <b>HTML4+ bold
<b></b> tags</p>
<p>...and <strong>HTML4+ strong <strong></strong> tags</p>
<p>...and <i>HTML4+ italics <i></i> and <cite> tags</p>
<p>...and <em>HTML4+ emphasis <em></em> tags</p>
<p>...and <u>HTML underline <u></u> tags</p>
<p>...and <strike>HTML strikeout <strike> and <del></strike> tags</p>
<p>...and Super<sup>script</sup> (<sup>) and Sub<sub>script</sub> (<sub>) tags</p>
<p style="background-color:#FFBBBB; color:#EEEEFF; font-family:Garamond; font-size:30px">...and styled text</p>
<p>...and <a href=".">HTML anchor <a></a> tags.</p>
<h2>Images</h2>
<p>The <img> tag is supported. The src attribute can be either
a URL to an Internet image, or can be a reference to an image provided
in the data sent to the OneNote API in the request. For
example, here's a referenced image: </p>
<img
src="http://officeimg.vo.msecnd.net/en-us/files/018/949/ZA103278226.png"
alt="Everyone loves OneNote!"/>
<p>The OneNote API supports JPEG, GIF, TIFF and PNG images</p>
<p>This next tag inserts a screenshot thumbnail image of the OneNote.com web
page into the captured page, displayed as 500 pixels wide.</p>
<img data-render-src="https://www.onenote.com" width="500"/>
<h2>Tables</h2>
<p>Tables are understood, but not table headers. Table headers are treated
like normal rows. You can nest tables, but their content-layout ability
is limited. </p>
<p>Tables have to be "regular", in that the API assumes all
rows have same number of columns. Similarly, all columns have the same
number of rows. More specifically, the API ignores colspan and rowspan
attributes.</p>
<p>Table border and other styling is ignored, but instead get the default
OneNote table styling, so a simple table like the below will have no
visible borders on the notebook page, until the user adds them.</p>
<table border="0px">
<tr>
<td width="20%">First row First column</td>
<td width="40%">First row Second column</td>
</tr>
<tr>
<td style="background-color:#EEEEFF">Second row First column in blue</td>
<td style="background-color:#EEFFEE">Second row Second column in green</td>
</tr>
</table>
<p>Lists of both types (<ol> and <ul>) are supported, and can
be nested. The "type=" attribute is ignored.</p>
<ul>
<li>First unordered list item</li>
<li>Second unordered list item<br>which contains another list
<ol>
<li>First (nested) ordered list item</li>
<li>Second (nested) ordered list item</li>
</ol>
</li>
</ul>
<h2>Not (yet) supported</h2>
<p>Nested tables are supported, but table header rows (<th>)
are treated like normal table rows (<tr>)</p>
<p>CSS styles are ignored at this time.</p>
<p>Scripts are ignored.</p>
<p>Other tags (for example, <article>, <header>,
<footer>, <section> and <aside>) are largely
ignored, but their otherwise-valid contents are included.</p>
</body>
</html>
関連項目
概念
OneNote API を使用して簡単なキャプチャを作成する
OneNote API で HTML を使用した構造を作成する
OneNote API を使用して写真およびイメージをキャプチャする
OneNote API を使用して Web ページ スナップショットをキャプチャする
OneNote API を使用して埋め込みファイルをキャプチャする
OneNote API を使用した PDF ファイルの取り込みと埋め込み