sharepoint-html

SharePoint への HTML の公開（OneUp HTML ビューアー）

SharePoint では、すでに HTML をホストできます。.html ファイルを OneDrive または SharePoint に保存して開くと、厳格な Content-Security-Policy が適用されたサンドボックス内の <iframe> である OneUp HTML ビューアーに表示されます。別途ホスティングサービスを用意する必要はありません。公開とは、サインイン中のユーザーとしてユーザーのドライブに .html ファイルを書き込み、そのファイルの webUrl を開くだけです。

このスキルでは、エージェントに次の 2 つを教えます。

1. 正しく表示される HTML を作成する — OneUp の CSP とサンドボックスは、要件を満たしていない HTML をエラーも表示せずに空白または不完全な状態で表示します。以下の仕様に従えば、正しく動作します。
2. 公開する — Microsoft Graph（優先）または SharePoint Vroom API（_api/v2.0。すでに SharePoint トークンを保持しているエージェント向け）を使ってファイルをアップロードし、返された webUrl をユーザーに渡します。

作成仕様の正規版（常に最新）は、テナントの検出エンドポイントにあります。https://<your-sharepoint-host>/_html（人間向けのページ）、/_html/llms.txt（エージェント向けテキスト）、/_html/help.json（構造化データ）です。不明な点があれば、/_html/llms.txt を取得してください。これは実際のビューアーのソースから生成されています。

---

⚠️ 公開する前に：ユーザーの実際のドライブに書き込みます

このスキルで公開すると、ユーザーとして認証された状態で、ユーザー自身の OneDrive または SharePoint にファイルが作成または上書きされます。使い捨てのサンドボックスではありません。

• ファイルが自動的に公開されることはありません。 ユーザーが明示的に共有するまでは、そのファイルはユーザーだけが利用できます。ただし、ユーザーのドライブに実際のドキュメントとして保存されます。
• アップロードおよび上書きのたびに、必ずユーザーの明示的な確認を得てください。 保存先（ドライブ、フォルダー、ファイル名）と、新規ファイルの作成か既存ファイルの置き換えかを正確に提示し、了承を待ってください。書き込み前の確認を参照してください。
• 上書きは破壊的な操作です。 既存のパスに対する PUT .../content は、ファイルの内容を置き換えます。パスと、上書きの意図があることを確認してください。

---

執筆時の契約（OneUp で HTML をレンダリングする）

HTML は、厳格な CSP が適用された <iframe sandbox="allow-scripts"> 内で実行されます。CSP 違反はエラーを表示せずに失敗します。以下のルールに従わないと、エラーが表示されないままページが真っ白になったり、一部しか表示されなくなったりします。

HTML に適用される Content-Security-Policy：

default-src 'none';
script-src 'unsafe-inline' 'unsafe-eval';
style-src 'unsafe-inline';
img-src data: blob:;
font-src data: blob:;
connect-src 'none';
worker-src 'none';
object-src 'none';
base-uri 'none';
form-action 'none';

ラッパーの iframe では、さらに frame-src 'none' が適用されます。

必須ルール：

1. 外部リソースは禁止です。 <script src>、<link href>、<img src=https://…>、 @import、url(https://…)、リモートフォント、CDN は使用できません。すべてインラインにするか、 data: / blob: URI を使用してください。
2. スクリプトはすべてインラインの <script> ブロックにしてください。モジュールのインポート、import()、 <script src> は使用できません。
3. スタイルはすべてインラインの <style> または style="…" にしてください。<link rel="stylesheet"> は使用できません。
4. 実行時のネットワークアクセスは禁止です — fetch、XMLHttpRequest、WebSocket、sendBeacon、 EventSource はすべてブロックされます（connect-src 'none'）。表示時に SharePoint ファイルのデータを 読み取るには、LiveData マニフェスト（以下）を使用してください。これが許可された唯一のデータ経路です。
5. ストレージプリミティブは禁止です — localStorage、sessionStorage、indexedDB、 document.cookie（不透明なオリジンのサンドボックス）。再読み込み後も状態を保持するには、location.hash を 直接設定してください（例：location.hash = '#slide=3'）。history.pushState / replaceState は使用しないでください — サンドボックス化されたドキュメントのベース URL はラッパーの blob: オリジンから継承されるため、url 引数（単なる #hash でも）は SecurityError をスローします。
6. トップレベルのナビゲーション、ポップアップ、フォーム送信、ワーカー、プラグインは禁止です。 alert / confirm / prompt は何も行いません。
7. インラインの on*= ハンドラーは動作します（nonce 付きスクリプトに書き換えられます）が、信頼できない データをテンプレートに埋め込むと XSS の発生源になります。計算したデータ、ユーザーデータ、取得したデータには addEventListener を使用してください。
8. UTF-8 で保存してください（以下のファイル作成 API は UTF-8 で書き込みます。手動で作成していて 非 ASCII 文字が正しく表示されない場合は、BOM を追加してください）。

リンク： <a href> で開けるのは、同一テナントの SharePoint ホストまたは外部許可リストに含まれるホストのみです。 javascript: / vbscript: / data: の href は拒否されます。

SharePoint のライブデータ（唯一の実行時データソース）

実行時の fetch はブロックされます。SharePoint のファイル内容をライブ表示するには、LiveData マニフェストを埋め込みます。ホストが閲覧者の認証情報を使ってサーバー側で各項目を事前取得し、 スクリプトの実行前に結果を挿入します。

<script type="application/json" class="ka-livedata-manifest">
[{ "spItemUrl": "https://contoso.sharepoint.com/_api/v2.0/drives/{driveId}/items/{itemId}", "fileName": "data.csv" }]
</script>

スクリプトの実行前に、ホストは正確な spItemUrl をキーとして window.__LD_RESULTS__ を設定します。 各値は { format, content, error?, metadata } です。content（文字列）を読み取り、error を確認してください。

見落としやすい重要事項：

• 各項目には必ず拡張子付きの fileName を含めてください。ホストはそれを基に csv／xlsx-sheets／ text のデコーダーを選びます。指定しないと、.xlsx は読み取り不能になり、.csv も CSV として解析されません。
• spItemUrl には /drives/{driveId}/items/{itemId} を含める必要があります（オリジンは無視され、閲覧者の セッションから再構築されます）。ファイルを解決して ID を取得してください：GET /shares/{u!token}/driveItem → parentReference.driveId + id。
• 更新すると、新しいデータで iframe が再読み込みされます。postMessage({type:'ka-html-viewer-refresh'}, '*') （5 秒間のデバウンス）。受信する「updated」イベントを待ち受ける必要はありません。
• コンテンツは信頼できないものとして扱ってください。DOM の構築には textContent を使い、innerHTML に設定しないでください。
• 上限：1 ページあたり 32 項目（上限を超えるとすべての結果が破棄されます）、1 項目あたり 50 MB。形式：text、csv、xlsx-sheets、rows。

SharePoint リスト — マニフェスト項目ではリストも指定できます（kind:"list" と webUrl + listId、 さらに任意で内部列名の select を指定）。ホストはサーバー側でリストを描画し、format:"rows" として挿入します。 content は { headers, rows } の JSON 文字列です（フラット化済み。最大 100,000 行で、切り詰めが発生した場合は 処理を妨げない warning が設定されます）。作成時に GET {webUrl}/_api/web/lists/getbytitle('{Name}')/fields?$select=InternalName,Title,TypeAsString（または Graph /sites/{site-id}/lists/{list-id}/columns）を使って listId と内部列名を解決してください。内部名は表示タイトルと異なる場合があります（例：「City」 → Ciity）。references/live-data.md を参照してください。

プロトコルの全容と完全なダッシュボード例： references/live-data.md （テナントの /_html/llms.txt にも複製されています）。テーブル専用のスターター： assets/templates/livedata-dashboard.html。

---

まだ HTML がありませんか？テンプレートから始めましょう

ユーザーが何かを公開したいものの HTML がない場合は、手書きする代わりに assets/templates/ にある、CSP に準拠した既製のテンプレートを使用します。

テンプレート	次の用途をユーザーが希望する場合に使用します…
dashboard.html	…外部データを使わない、自己完結型のメトリクス／ステータスダッシュボードを構築する。
livedata-dashboard.html	…LiveData マニフェストを使ってSharePoint ファイルのライブデータ（csv／xlsx／text）を表示する。
livedata-list-dashboard.html	…SharePoint リストのライブデータ（kind:"list" → format:"rows"）を表示する（KPI、カテゴリ別グラフ、テーブル）。

選んだファイルを読み込み、`` のプレースホルダーをユーザーの実際の コンテンツに置き換え、上記の要件に適合していることを確認してから公開します。

---

手順 1 — 要件に準拠した HTML を作成（または記入）する

要件を満たす、自己完結型の .html ドキュメントを 1 つ作成します。すべてをインラインにし、 外部参照は使わず、SharePoint データが必要な場合は LiveData マニフェストを使用します。

ステップ 2 — アクセストークンを取得する

公開はユーザーとして認証されます。OAuth 2.0 の ベアラートークン（Azure AD）が必要です。

第一の方法 — Microsoft Graph：

• スコープ（委任）： Files.ReadWrite（ユーザー自身のドライブへの書き込み）。ユーザーがアクセスできる他のライブラリ／サイトに書き込むには、 Files.ReadWrite.All または Sites.ReadWrite.All を使用します。
• 取得方法： MSAL を使用してユーザーの ID で取得します（対話型、デバイスコード、または既存のサインイン済みセッション）。トークンを捏造したり、ハードコードしたりしないでください。Graph トークンをまだ持っていない場合は、MSAL フローを実行してください。詳しくは references/api.md を参照してください。

代替方法 — SharePoint Vroom（エージェントがすでに SharePoint OAuth トークン（アドイン／SPFx／オンビハーフオブ フローなど）を使用できる場合に利用）：対象が SharePoint リソース（https://{tenant}.sharepoint.com または -my.sharepoint.com）で、スコープが AllSites.Write／MyFiles.Write のトークンを使用します。同じ driveItem 呼び出しを使用しますが、ベース URL は異なります。

トークンのフロー、スコープ、同意については、references/api.md を参照してください。

ステップ 3 — 確認してから公開する

書き込む前に確認する

まず HTML を事前チェックします。scripts/preflight.sh <file> を実行して、禁止 API を grep し、LiveData マニフェスト項目を確認します（ファイル項目には spItemUrl と fileName が必要です。kind:"list" 項目には spItemUrl と webUrl と listId が必要です）。最も多い失敗は「エラーは出ないが空白で表示される」です。次に出力先フォルダーを一覧表示（GET …/children）して名前の競合を検出し、これが新規作成か上書きかを正確にユーザーに伝えられるようにします。

アップロードを呼び出す前に、実行する内容を正確にユーザーに示し、承認を得てください。

About to publish to SharePoint/OneDrive:
  Account:   [email protected]
  Location:  OneDrive  ›  Documents/Agent HTML/
  File:      sales-dashboard.html
  Action:    Create new file            (or: Overwrite existing file — REPLACES its contents)
  Renders at: <webUrl>?web=1   (?web=1 opens the OneUp viewer; the bare webUrl downloads)
Proceed?

明示的な承認があった場合にのみ続行します。上書きの場合は、破壊的な操作であることを明確に伝えてください。

Microsoft Graph 経由で公開する（第一の方法）

シンプルなアップロード（4 MB 以下のファイル。HTML をインライン化する場合には十分です）。パスを指定して新しいファイルを作成します。

PUT https://graph.microsoft.com/v1.0/me/drive/root:/Agent HTML/<name>.html:/content
Authorization: Bearer <token>
Content-Type: text/html

<!DOCTYPE html> … your document …

応答 201 Created（新規）／200 OK（置換）で driveItem が返されます。webUrl を読み取り、ユーザーに <webUrl>?web=1 を渡してください。?web=1 は OneUp ビューアーで開き、webUrl のみの場合は .html ファイルをダウンロードします。

{
  "id": "01ABC…",
  "name": "sales-dashboard.html",
  "size": 84213,
  "webUrl": "https://contoso-my.sharepoint.com/personal/user_contoso_com/Documents/Agent%20HTML/sales-dashboard.html",
  "file": { "mimeType": "text/html" }
}

4 MB を超えるファイルにはアップロードセッション（createUploadSession）を使用してください。詳しくは references/api.md を参照してください。

SharePoint Vroom 経由で公開する（代替方法）

同じ形式で SharePoint ベース URL と SharePoint を対象とするトークンを使用します。すでに SharePoint OAuth トークン（SPFx／アドイン／オンビハーフオブ）を持っている場合や、特定の SharePoint ホストまたはサイトを直接指定したい場合に利用します。（graph.microsoft.com はすでに、自分のドライブへのアップロードを呼び出し元のファームにルーティングします。*.sharepoint-df.com などの dogfood リングも含まれるため、通常は Graph だけで十分です。）

PUT https://{tenant}-my.sharepoint.com/_api/v2.0/me/drive/root:/Agent HTML/<name>.html:/content
Authorization: Bearer <sharepoint-token>
Content-Type: text/html

<!DOCTYPE html> … your document …

同じ driveItem が返されます（webUrl を読み取ります）。サイトのドライブパス（/_api/v2.0/drives/{driveId}/items/{itemId}/content）を含む詳細は、references/api.md を参照してください。

OneDrive ではなく SharePoint サイトのライブラリに公開する

サイトドライブに対して同じ呼び出しを行います。Graph（スコープ Sites.ReadWrite.All）を使用する場合：

PUT https://graph.microsoft.com/v1.0/sites/{site-id}/drive/root:/Agent HTML/<name>.html:/content

または、サイトホストに対して Vroom を使用する場合：

PUT {siteUrl}/_api/v2.0/drive/root:/Agent HTML/<name>.html:/content

サイトドライブのルートは既定のドキュメントライブラリ（「Shared Documents」）なので、パスはルート相対のままにしてください。GET /sites/{host}:/sites/{path}（または /teams/{path}）で {site-id} を解決します。

フォルダー URL で公開する — 呼び出し回数が最少（Shares API）

保存先フォルダーの URL だけが分かっている場合は、ドライブ ID やサイト ID の解決を省略し、URL を共有トークンとしてエンコードして、そのフォルダーに直接アップロードできます。

1. エンコードします。u! + フォルダー URL のパディングなし base64url（base64 の = を削除し、/→_、+→-）。
2. GET /shares/{u!token}/driveItem → フォルダーの id と parentReference.driveId を取得します（1 回の呼び出し）。
3. PUT /drives/{driveId}/items/{folderId}:/<name>.html:/content → アップロードします。

呼び出しは 2 回で、あらゆる OneDrive、サイト、ライブラリで動作します。詳細は references/api.md を参照してください。すぐに使える スクリプト：scripts/publish-to-folder.sh。

ステップ 4 — 開く

ユーザーに <webUrl>?web=1 を渡します（レスポンスの webUrl の末尾に ?web=1 を追加します）。?web=1 を付けると OneUp ビューアーで HTML が表示され、webUrl だけの場合は .html ファイルがダウンロードされます。 webUrl は更新後も変わらないため、変更後もリンクを引き続き使用できます。

---

作成したアセットの更新／変更

公開済みのファイルを変更するには、上書きします。同じパス（またはアイテム ID）を使い、同じ呼び出しを行います。

PUT https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/content
Authorization: Bearer <token>
Content-Type: text/html

<!DOCTYPE html> … updated document …

またはパスで指定します：PUT /me/drive/root:/Agent HTML/<name>.html:/content。

上書きするとファイルの内容が置き換わります。先にユーザーに確認してください（対象と、既存ファイルが置き換わることを示します）。webUrl は変わりません。Vroom もベース URL を含めて同様です。内容を置き換えるのではなく名前を変更したり移動したりする場合は、PATCH …/items/{item-id} を使用してください（references/api.md を参照）。

---

エラーコード

コード	意味	対応
401	認証されていません	トークンがない、期限切れ、またはオーディエンスが間違っています（Graph と SharePoint）。適切なスコープで再取得してください。
403	アクセスが拒否されました	トークンに書き込みスコープ（Files.ReadWrite）がないか、ユーザーにその場所への書き込み権限がありません。
404	見つかりません	ドライブ／アイテム／パスが間違っているか、親フォルダーが存在しません（先に作成してください）。
413	ペイロードが大きすぎます	シンプルアップロードでファイルが 4 MB を超えています — アップロードセッションを使用してください。
423	ロックされています	アイテムがチェックアウト済み、またはロックされています。
507	ストレージが不足しています	ユーザーのドライブがいっぱいです。

開いたときにページが空白になる／一部しか表示されない場合は、オーサリング契約に違反しています（通常は外部リソースまたは実行時の fetch が原因です）。契約 を再確認してください。

---

リファレンス

• references/api.md — Graph + Vroom エンドポイントの完全なリファレンス： 認証とスコープ、トークンの取得、リクエスト／レスポンスのスキーマ、アップロードセッション、 メタデータの更新、driveItem の形式。
• references/contract.md — OneUp オーサリング契約の全文。
• assets/templates/ — すぐに使える CSP 準拠のテンプレート。
• 最新のドキュメント（正式な情報、テナント固有）：https://<your-sharepoint-host>/_html、 /_html/llms.txt、/_html/help.json。