Teams チャネルのWikiが廃止されOneNoteの置き換わることで大きなメリットが一つ「PowerAutomateで扱うことができる！」ということに気づき、初めてOneNote(Business)コネクタを使ってみたのですがなかなか癖が強く苦戦中です。
今回はOneNoteノートブックのデータを取得する際にハマったポイントを備忘録的にまとめています。
※以降OneNoteコネクタとだけ記載していますがOneNote(Business)コネクタの話です。OneNote(Consumer)コネクタではありません。
はじめに - OneNoteノートブックの構造
ざっくりOneNoteノートブックは下図のような構造になっています。
OneNoteコネクタではノートブック・セクション・ページを取得するアクションが備わっています。（対応する取得アクションがないセクショングループ、サブページに関しては後述）
どのような動きをするか確認するために、最近使用したノートブックすべてのセクション・ページを取得するフローを作成し動作を検証してみました。
1.自分がアクセス可能なノートブックを列挙するアクションはない
Teamsコネクタであれば、「チームの一覧表示」アクションでアクセス可能なチームの情報がすべて取得できますが、OneNoteコネクタにはノートブックの情報を取得できるアクションは「最近使用したノートブックを取得する」アクションしかありません。
ですが、「ノートブックのセクションを取得」アクションのパラメーター"ノートブックキー"にはアクセス可能なノートブックが候補として表示されます。
また、Microsoft Graph API を使えばノートブックの一覧が取得できそうですが、今回は未確認です。
1-1.「ノートブックキー」の候補が１つも表示されないケースがある
私の環境でOneNoteコネクタの「ノートブックのセクションを取得」アクションでセクション情報を取得してみようかと試したところ、ノートブックキーの候補が１つも現れない事がありました。
OneNoteコネクタのリファレンスにある既知の問題と制限事項の1の状況です。
1.接続を使用しているときに、期待するノートブックのリストが表示されない場合は、接続を作成したアカウントを確認して、再試行してください。 コネクタの使用中にエラーが表示された場合は、エラー コードで詳細を確認できます。
とありますが、接続を作り直しても改善されませんでした。
learn.microsoft.com
色々試行錯誤した結論としては、OneDrive for Business にノートブックを作った事がないアカウントではSharePointサイト上のOneNoteノートブックも表示されない、という事でした。
※OneNoteコネクタのリファレンスページの冒頭に記載がありました。さらっと書いてありますが重要ポイントです。
普段からOneNoteを活用しているアカウントではこのような事は無いかもしれませんが、検証アカウントを使おうとした場合にハマるポイントかもしれません。
ちなみに、1度OD4bにOneNoteブックを作成した後は、OD4bからOneNoteノートブックを削除しても問題なく候補が表示されるようになりました。
2.ノートブックを動的に扱うにはノートブックキーの理解が必要
特定のノートブックを処理するフローであればUIでノートブックを指定すればOKですが、ノートブックを動的に指定して情報を取得したい場合、OneNoteコネクタの場合は「ノートブックキー」なるものが必要になります。
詳しくはこちらのサイトにありますが、ノートブックキーはこういった値です。
"ノートブックの名前|$|ノートブックのURL"
natechamberlain.com
OneDrive for Business(以降OD4bと記載)にあるノートブックの場合は
"マイノートブック|$|https://■■■■■-my.sharepoint.com/personal/sasami_■■■■_■■■■■_onmicrosoft_com/Documents/ノートブック/マイノートブック"
SharePointサイトの既定のノートブックの場合は
"テストチーム Notebook|$|https://■■■■■.sharepoint.com/sites/testteame/SiteAssets/テストチーム Notebook"
チャネルに任意で追加したノートブックの場合は
"testノートブック|$|https://■■■■■.sharepoint.com/sites/testteame/Shared Documents/OneNoteテスト/testノートブック"
といった形になります。
なお、ノートブック名の箇所はSharePoint/OD4b上の名前と一致させる必要があります。Teams チャネルのタブ名とは異なる場合がありますのでご注意ください。
3.セクションキーはURLであってidではない
OneNoteのセクションをパラメーターに指定するアクションで動的な値でセクションの情報を取得したい場合、「セクションキー」なるものが必要になります。
「ノートブックのセクションを取得」アクションの出力に含まれています。
「ノートブックのセクションを取得」アクションの出力にはidも含まれていますが、このidはセクションキーではありません。セクションキーにはpageUrlが対応します。
[
{
"id": "1-653e6450-f02a-450a-b936-6ee79ad340db",
"self": "https://www.onenote.com/api/v1.0/myOrganization/siteCollections/（省略）/sites/（省略）/notes/sections/1-653e6450-f02a-450a-b936-6ee79ad340db",
"createdTime": "2023-05-29T09:07:11Z",
"name": "Sasami (ささみ)テスト",
"createdBy": "Sasami (ささみ)",
"lastModifiedBy": "Sasami (ささみ)",
"lastModifiedTime": "2023-05-30T11:43:19Z",
"isDefault": false,
"links": {
"oneNoteClientUrl": {
"href": "onenote:https://■■■■■-my.sharepoint.com/personal/sasami_■■■■■_■■■■■_（省略）.one"
},
"oneNoteWebUrl": {
"href": "https://■■■■■-my.sharepoint.com/personal/sasami_■■■■■_■■■■■_（省略）.one%7C%2F%29"
}
},
"pagesUrl": "https://www.onenote.com/api/v1.0/myOrganization/siteCollections（省略）sites/（省略）/notes/sections/1-653e6450-f02a-450a-b936-6ee79ad340db/pages",
"size": 54015,
"parentNotebook@odata.context": "https://www.onenote.com/api/v1.0/$metadata#myOrganization/siteCollections（省略）/$entity",
"parentNotebook": {
"id": "1-681ace07-38a8-4512-b829-8aacfc578d02",
"name": "マイノートブック",
"self": "https://www.onenote.com/api/v1.0/myOrganization/siteCollections/（省略）"
},
"parentSectionGroup@odata.context": "https://www.onenote.com/api/v1.0/$metadata#myOrganization/siteCollections（省略）/$entity"
}
]
4.ページIDは「応答の一意識別子」
ノーツブックキー・セクションキーときましたが、ページを識別するキーはページIDです。「特定セクションのページを取得」アクションの出力に含まれていますので、ノートブック→セクション→ページと段階を踏んでアクセスしていけば問題ない…と思いきや、日本語訳が微妙でわかりづらくなっています。
同アクションの出力の「セクション内ページの値オブジェクト 応答の一意識別子」がページIDに対応しています。
5.ページコンテンツはHTML
「ページコンテンツの取得」アクションでページコンテンツが取得できます。
ページコンテンツはHTMLで構成されています。
※ページのメタデータは「特定セクションのページを取得」アクションで取得できます。
<html lang="en-US">
<head>
<title>ページ３</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="created" content="2023-05-29T18:15:00.0000000" />
</head>
<body data-absolute-enabled="true" style="font-family:Calibri;font-size:11pt">
<div style="position:absolute;left:48px;top:115px;width:624px">
<p lang="ja-JP" style="font-family:ＭＳ ゴシック;margin-top:0pt;margin-bottom:0pt">あいうえお</p>
<p lang="ja-JP" style="font-family:ＭＳ ゴシック;margin-top:0pt;margin-bottom:0pt">書きくけこ</p>
<br />
</div>
</body>
</html>
テキスト以外のオブジェクトがどのように格納されているかも調べてみました。
●画像 → img
●ファイル添付→object / ファイルリンク→リンク
●オーディオ→object
6.「ノートブックのセクションを取得」アクションでセクショングループないのセクションまで取得できる
「ノートブックのセクションを取得」アクションでこのようなノートブックを取得した場合は、セクショングループ内のセクションを含む形で取得可能です。
セクショングループ内のセクションには"parentSectionGroup"としてセクショングループが含まれます。
7.「特定セクションのページを取得」アクションでサブページも取得できる
「特定セクションのページを取得」アクションでこのようなサブページを含むセクションのページを取得すれば、サブページも含む形で取得されます。ただしサブページのレベル（階層）に関する情報は含まれていないようです。
参考資料
learn.microsoft.com
learn.microsoft.com
最後に
今回はOneNoteコネクタの調査ということで、OneNoteコネクタの読み込み系アクションで気になったりハマったポイントをまとめてみました。
OneNoteに書き込む際のポイントはまた別記事で作成するかもしれません。
