PowerAutomate クラウドフローで初めてOneNoteコネクタを使おうとしてハマったポイント #1

Teams チャネルのWikiが廃止されOneNoteの置き換わることで大きなメリットが一つ「PowerAutomateで扱うことができる！」ということに気づき、初めてOneNote(Business)コネクタを使ってみたのですがなかなか癖が強く苦戦中です。
今回はOneNoteノートブックのデータを取得する際にハマったポイントを備忘録的にまとめています。

※以降OneNoteコネクタとだけ記載していますがOneNote(Business)コネクタの話です。OneNote(Consumer)コネクタではありません。

はじめに - OneNoteノートブックの構造
1.自分がアクセス可能なノートブックを列挙するアクションはない
- 1-1.「ノートブックキー」の候補が１つも表示されないケースがある
2.ノートブックを動的に扱うにはノートブックキーの理解が必要
3.セクションキーはURLであってidではない
4.ページIDは「応答の一意識別子」
5.ページコンテンツはHTML
6.「ノートブックのセクションを取得」アクションでセクショングループないのセクションまで取得できる
7.「特定セクションのページを取得」アクションでサブページも取得できる
参考資料
最後に

はじめに - 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>