トレーニング
モジュール
Power Apps キャンバス アプリでカスタムの更新を実行する - Training
Power Apps キャンバス アプリの中には、フォームが解決策にならないものもあります。 このモジュールでは、データがフォーム内にない場合にカスタムの更新を実行する方法に焦点を当てます。
このブラウザーはサポートされなくなりました。
Microsoft Edge にアップグレードすると、最新の機能、セキュリティ更新プログラム、およびテクニカル サポートを利用できます。
適用対象 OneDrive のコンシューマー ノートブック | Microsoft 365 のエンタープライズ ノートブック
OneNote ページのコンテンツを更新する場合は、ページの content エンドポイントに PATCH 要求を送信します。
PATCH ../notes/pages/{id}/content
メッセージの本文で JSON 変更オブジェクトを送信します。 要求が成功すると、Microsoft Graph は 204 HTTP 状態コードを返します。
要求 URI を構築するには、サービス ルート URL から開始します。
https://graph.microsoft.com/v1.0/me/onenote
次に、ページの content エンドポイントを追加します。
ページ HTML と、すべての定義済み data-id の値を取得する../pages/{id}/content
ページ HTML、すべての定義済み data-id の値、およびすべての生成された id の値を取得する../pages/{page-id}/content?includeIDs=true
data-id と id の値は、更新する要素の target 識別子として使用されます。
完全な要求 URI は、次のようになります。https://graph.microsoft.com/v1.0/me/onenote/pages/{id}/content
サービス ルート URL の詳細についてはリンク先をご覧ください。
OneNote ページの HTML には、div 要素、img 要素、ol 要素などの構造に編成されたテキスト、画像などのコンテンツが含まれています。 OneNote ページのコンテンツを更新する場合は、ページ上で HTML 要素を追加および置換します。
変更内容は JSON 変更オブジェクトの配列としてメッセージ本文に入れて送信します。 ターゲット要素、新しい HTML コンテンツ、コンテンツに対する操作が各オブジェクトにより指定されます。
2 つの変更を定義する配列を次に示します。 最初の変更では画像が兄弟として段落の上に挿入され、2 番目の変更ではアイテムが最後の子としてリストに追加されます。
注意
OneNote ページでイメージを更新する場合、www リンクは使用できません。 サービスはランダム なリソースのダウンロードを試みません。 代わりに、イメージは、image-data-url またはマルチパート要求の部分名によって、要求の一部である必要があります。
[
{
'target':'#para-id',
'action':'insert',
'position':'before',
'content':'<img src="image-data-url-or-part-name" alt="Image above the target paragraph" />'
},
{
'target':'#list-id',
'action':'append',
'content':'<li>Item at the end of the list</li>'
}
]
その他の例を参照してください。
PATCH 要求の JSON オブジェクトの定義には、target 属性、action 属性、position 属性、および content 属性を使用します。
更新する要素。 値として次の ID のいずれかを指定する必要があります。
Identifier | 説明 |
---|---|
#{data-id} | この ID は、ページを作成するときや更新するときに、入力 HTML の要素で任意で定義されます。 値の先頭に # を付けます。 例: |
ID | これは、Microsoft Graph から得られる生成済み ID であり、ほとんどの置換操作で必要になります。 プレフィックス # を追加しないでください。 例: 入力 HTML に定義されている id 値とこれらを混同しないでください。 入力 HTML で送信される id 値は、すべて破棄されます。 |
body | ページ上で最初の div をターゲットにするキーワード。 プレフィックス # を追加してはいけません。 |
title | ページ タイトルをターゲットにするキーワード。 プレフィックス # を追加してはいけません。 |
ターゲット要素で実行するアクション。 「サポートされる要素とアクション」を参照してください。
アクション | 説明 |
---|---|
append | 指定されたコンテンツを最初または最後の子としてターゲットに追加します。追加される位置 (最初または最後) は、position 属性によって決まります。 body、div、ol、ul 要素にのみ適用されます。 |
insert | 指定されたコンテンツを兄弟としてターゲットの前または後に追加します。追加される位置 (前または後) は、position 属性によって決まります。 |
prepend | 指定されたコンテンツを最初の子としてターゲットに追加します。 append + before のショートカット。 body、div、ol、ul 要素にのみ適用されます。 |
replace | 指定したコンテンツでターゲットを置換します。 ほとんどの replace アクションは、ターゲットの生成された ID を使用する必要があります (ただし、div 内の img 要素と object 要素を除きます。これらは、data-id の使用もサポートしています)。 |
指定されたコンテンツを追加する場所。ターゲット要素を基準とします。 省略した場合、既定値は after になります。
位置 | 説明 |
---|---|
after (既定値) | append の場合: ターゲット要素の最後の子。 insert の場合: ターゲット要素の後続の兄弟。 |
before | append の場合: ターゲット要素の最初の子。 insert の場合: ターゲット要素の先行の兄弟。 |
ページに追加する整形式 HTML の文字列と画像またはファイル バイナリ データ。 コンテンツにバイナリ データが含まれている場合、コンテンツ タイプとして multipart/form-data
を利用し、"Commands" パートを含む要求を送信する必要があります (例参照)。
Microsoft Graph は、更新可能なページで要素に対して id 値を生成します。 生成された ID を取得するには、GET 要求で includeIDs=true
クエリ文字列を使用します。
GET ../notes/pages/{page-id}/content?includeIDs=true
注意
API は、ページ作成要求およびページ更新要求の入力 HTML で定義された id の値をすべて破棄します。
次の例は、ページの出力 HTML の段落と画像に対して生成された ID を示します。
<p id="p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}">Some text on the page</p>
<img id="img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}" ... />
生成された id 値はページ更新後に変更されることがあるため、これらの値を使用する PATCH 要求を作成する前に、現行値を取得する必要があります。
ターゲット要素は、data-id または id 値を使用して次のように指定できます。
次の例では、ターゲットに id 値を使用します。 生成された ID と共に # プレフィックスを使用しないでください。
[
{
'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
'action':'insert',
'position':'before',
'content':'<p>This paragraph goes above the target paragraph.</p>'
}
]
ページ上の要素の多くは更新可能ですが、要素の種類ごとに特定のアクションがサポートされています。 サポートされるターゲット要素と、各要素でサポートされる更新アクションを次の表に示します。
要素 | 置換 | 子の追加 | 兄弟の挿入 |
---|---|---|---|
body (ページの最初の div をターゲットとする) |
いいえ | はい | いいえ |
div (絶対配置) |
いいえ | はい | いいえ |
div (div 内) |
はい (id のみ) |
はい | はい |
img、object (div 内) |
はい | いいえ | はい |
ol、ul |
はい (id のみ) |
はい | はい |
table |
はい (id のみ) |
いいえ | はい |
p、li、h1-h6 |
はい (id のみ) |
いいえ | はい |
title | はい | いいえ | いいえ |
次の要素では更新アクションはサポートされていません。
更新要求には、JSON 変更オブジェクトとして表現される変更が 1 つ以上含まれています。 これらのオブジェクトでは、ページ上のさまざまなターゲットや、ターゲットに対するさまざまなアクションとコンテンツを定義できます。
次の例に、PATCH 要求で使用される JSON オブジェクトと完全な PATCH 要求を示します。
append アクションでは、body、div (div 内)、ol、ul 要素に子が追加されます。 position 属性により、ターゲットの前または後に子を追加することが決定されます。 既定の位置は後です。
次の例では、2 つの子ノードが div1 要素に追加されます。 画像が最初の子として追加され、段落が 2 番目の子として追加されます。
[
{
'target':'#div1',
'action':'append',
'position':'before',
'content':'<img data-id="first-child" src="image-url-or-part-name" />'
},
{
'target':'#div1',
'action':'append',
'content':'<p data-id="last-child">New paragraph appended to the div</p>'
}
]
body は、任意のページ上の最初の div 内に子要素を追加するためのショートカットとして使用できます。
次の例では、ページの最初の div に 2 つの段落を最初の子と最後の子として追加しています。 body ターゲットと共に # を使用しないでください。 この例では、prepend アクションを append + before として使用しています。
[
{
'target':'body',
'action':'prepend',
'content':'<p data-id="first-child">New paragraph as first child in the first div</p>'
},
{
'target':'body',
'action':'append',
'content':'<p data-id="last-child">New paragraph as last child in the first div</p>'
}
]
次の例では、リスト項目がターゲット リストに最後の子として追加されます。 この項目では既定以外のリスト スタイルが使用されるため、list-style-type プロパティが定義されます。
[
{
'target':'#circle-ul',
'action':'append',
'content':'<li style="list-style-type:circle">Item at the end of the list</li>'
}
]
insert アクションでは、兄弟がターゲット要素に追加されます。 position 属性により、ターゲットの前または後に兄弟を挿入することが決定されます。 既定の位置は後です。 「insert をサポートする要素」を参照してください。
次の例では、ページに 2 つの兄弟ノードが挿入されます。 para1 要素の上に画像が追加され、para2 要素の下に段落が追加されます。
[
{
'target':'#para1',
'action':'insert',
'position':'before',
'content':'<img src="image-data-url-or-part-name" alt="Image inserted above the target" />'
},
{
'target':'#para2',
'action':'insert',
'content':'<p data-id="next-sibling">Paragraph inserted below the target</p>'
}
]
data-id と生成された id のいずれかをターゲット値として使用し、div 内にある img 要素および object 要素を置換できます。 ページ タイトルを置換する場合は、title キーワードを使用します。 replace をサポートするその他すべての要素については、生成された ID を使用する必要があります。
次の例では、画像の data-id をターゲットとして使用して、div 内の画像が置換されます。
[
{
'target':'#img1',
'action':'replace',
'content':'<div data-id="new-div"><p>This div replaces the image</p></div>'
}
]
次の例は、生成された ID を使用して表を更新する方法を示します。 tr 要素と td 要素の置換はサポートされていませんが、表全体を置換することができます。
[
{
'target':'table:{de3e0977-94e4-4bb0-8fee-0379eaf47486}{11}',
'action':'replace',
'content':'<table data-id="football">
<tr><td><p><b>Brazil</b></p></td><td><p>Germany</p></td></tr>
<tr><td><p>France</p></td><td><p><b>Italy</b></p></td></tr>
<tr><td><p>Netherlands</p></td><td><p><b>Spain</b></p></td></tr>
<tr><td><p>Argentina</p></td><td><p><b>Germany</b></p></td></tr></table>'
}
]
次の例は、ページのタイトルを変更する方法を示します。 タイトルを変更するには、ターゲット値として title キーワードを使用します。 title ターゲットでは # は使用しないでください。
[
{
'target':'title',
'action':'replace',
'content':'New title'
}
]
次に示す例では、replace アクションを使用して、To Do チェック ボックス アイテムを完了状態に変更します。
[
{
'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
'action':'replace',
'content':'<p data-tag="to-do:completed" data-id="task1">First task</p>'
}
]
data-tag 属性の使用法の詳細については、「ノート シールを使用する」を参照してください。
次の例に、完全な PATCH 要求を示します。
次の例では、PATCH 要求でコンテンツ タイプとして application/json が使用されています。 コンテンツにバイナリ データが含まれていない場合は、この形式を使用できます。
PATCH https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages/{page-id}/content
Content-Type: application/json
Authorization: Bearer {token}
[
{
'target':'#para-id',
'action':'insert',
'position':'before',
'content':'<img src="image-data-url" alt="New image from a URL" />'
},
{
'target':'#list-id',
'action':'append',
'content':'<li>Item at the bottom of the list</li>'
}
]
次の例は、バイナリ データを含んでいるマルチパート PATCH 要求を示しています。 マルチパート要求には、application/json コンテンツ タイプを指定し、JSON 変更オブジェクトの配列を含める "Commands" 部分が必要になります。 その他のデータ部分に、バイナリ データを含めることができます。 部分の名前は、通常、ミリ秒単位での現在の時刻、またはランダムな GUID が付加された文字列になります。
PATCH https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages/{page-id}/content
Content-Type: multipart/form-data; boundary=PartBoundary123
Authorization: Bearer {token}
--PartBoundary123
Content-Disposition: form-data; name="Commands"
Content-Type: application/json
[
{
'target':'img:{2998967e-69b3-413f-a221-c1a3b5cbe0fc}{42}',
'action':'replace',
'content':'<img src="name:image-part-name" alt="New binary image" />'
},
{
'target':'#list-id',
'action':'append',
'content':'<li>Item at the bottom of the list</li>'
}
]
--PartBoundary123
Content-Disposition: form-data; name="image-part-name"
Content-Type: image/png
... binary image data ...
--PartBoundary123--
要求データ | 説明 |
---|---|
プロトコル | すべての要求は SSL/TLS HTTPS プロトコルを使用します。 |
承認ヘッダー |
これがないか、無効の場合、要求は失敗し、401 ステータス コードが表示されます。 「認証とアクセス許可」を参照してください。 |
Content-Type ヘッダー | JSON 変更オブジェクトの配列の マルチパート要求はバイナリ データを送信するときに必須であり、コンテンツ タイプとして |
応答データ | 説明 |
---|---|
成功コード | 204 HTTP ステータス コード。 PATCH 要求に対して JSON データは返されません。 |
エラー | Microsoft Graph から返されることのある OneNote エラーに関する詳細については、「Microsoft Graph の OneNote API のエラー コード」をご覧ください。 |
OneNote サービスのルート URL は、OneNote API へのすべての呼び出しで次の形式を使用します。
https://graph.microsoft.com/{version}/me/onenote/
URL の version
セグメントは、使用する Microsoft Graph のバージョンを示しています。 安定した運用コードには v1.0
を使用します。 開発中の機能を試すには beta
を使用します。 ベータ版の機能は変更される可能性があるため、運用コードでは使用しないでください。
現在のユーザーがアクセスできる OneNote コンテンツには me
を使用します (所有と共有)。 指定されたユーザー (URL 内) が現在のユーザーと共有している OneNote コンテンツには users/{id}
を使用します。
ユーザー API を使用します。
注意
に対して GET 要求を行うことで、ユーザー ID を https://graph.microsoft.com/v1.0/users
取得できます。
OneNote ページを更新するには、適切なアクセス許可を要求する必要があります。 アプリの動作に必要な最低限のアクセス許可を選択してください。
アクセス許可のスコープと動作のしくみの詳細については、「OneNote のアクセス許可のスコープ」を参照してください。
トレーニング
モジュール
Power Apps キャンバス アプリでカスタムの更新を実行する - Training
Power Apps キャンバス アプリの中には、フォームが解決策にならないものもあります。 このモジュールでは、データがフォーム内にない場合にカスタムの更新を実行する方法に焦点を当てます。