定期実行・無人実行ガイド（Windows Server）

定期実行の基本

1. 「設定 ＞ 定期実行」で、毎日／毎週と時刻を指定して登録します（Windows タスクスケジューラ連携）。
2. 「設計書・差分レポートまで生成する」をオンにすると、取得・差分の計算だけでなく設計書（Word／PDF）と差分レポートまで自動生成します。
   • オフのときは「取得 → 差分の計算」までです。

既定は「ログオン中のみ実行」です。実行時刻に PC が起動し、サインインしている必要があります。サインアウト中も実行したい場合は次の「無人実行」を設定してください。

無人実行（サインアウト中も実行）

1. サーバーに、定期実行を担当させる専用の Windows ユーザーでサインインします（以降のセットアップ・タスク実行をすべて同じユーザーで行うのが重要です）。
2. TenantSnap を起動し、初回セットアップで認証情報を保存します（シークレットはこのユーザーに紐づけて暗号化＝DPAPI 保存されます）。
3. 「設定 ＞ 定期実行」で「無人実行（サインアウト中も実行する）」をオンにし、実行ユーザー（手順 1〜2 と同じユーザー。例：SERVER01\ユーザー名）と Windows のパスワードを入力して保存します。

パスワードはタスク登録にのみ使われ、アプリには保存されません（保存し直すたびに再入力が必要）。タスク登録は Windows のタスクスケジューラ API 経由で行い、パスワードがコマンドライン（プロセス起動の引数）に載ることはありません（コマンドライン監査を有効にした環境でもイベントログに平文が記録されません）。

定期実行が動いているかを確かめる

「設定 ＞ 定期実行」の「前回の実行」に前回の実行日時と結果（成功／失敗）を、「次回の予定」に次に実行される日時を表示します。タスク スケジューラを開かなくても、この画面で確かめられます。

予定の日時を待たずに確かめたいときは、定期実行を保存したあと、同じ画面の「今すぐ実行」を押します。登録した定期実行をその場で 1 回動かします。定期実行と同じ Windows ユーザー（無人実行ならそのユーザー）として動くため、認証情報を読めるか・データフォルダに書き込めるか・パスワードが正しいかを、登録した直後に確かめられます。予定の日時と同じ処理が動くため、テナントの規模により数分〜数十分かかります。終わると「前回の実行」に結果が表示されます。

「作成したファイル」には、前回の実行で作られた設計書・差分レポートのファイル名を表示します。

「状態」の行は、タスクが登録されているかどうかを表すだけです。動いているかどうかは「前回の実行」でご確認ください（登録されたまま失敗し続けていることもあります）。

定期実行は、実行のたびにデータフォルダの scheduled_runs.jsonl へ、実行の日時と結果（成功か・失敗した手順）だけを 1 行ずつ記録します。設定の内容・認証情報・個人データは含まず、外部にも送信しません。複数テナント運用では、各テナントのデータフォルダに記録します。

アプリを新しい版にしたときは、アプリを一度起動すると、設定済みの定期実行も自動で新しい版の動作になります（バージョン 1.55.0 以降。保存し直す必要はありません）。ただし、別の場所にある TenantSnap で登録した定期実行は、「設定 ＞ 定期実行」に表示される案内に従って「保存」してください（無人実行の場合は、保存のときに Windows ユーザーのパスワードの入力が必要です）。

定期実行とアプリからの実行は同時に行いません

同じデータフォルダで 2 つの処理が同時に動くと、取得データや設計書が正しく作られないおそれがあるため、定期実行とアプリからの実行は同時には行いません（バージョン 1.55.0 以降）。また、実行の途中でアプリを閉じたときは、実行中の処理も止まります。その回の設計書・差分レポートは作られないため、終わるまでお待ちください（バージョン 1.56.0 以降）。

• 定期実行が動いている間にアプリから実行しようとすると、「定期実行が実行中です」と表示して実行しません。定期実行が終わってから、もう一度実行してください。
• アプリで取得・設計書の生成などを実行している間は、「今すぐ実行」を押せません。
• アプリで実行している最中に予定の時刻が来たときは、定期実行はアプリの実行が終わるのを待ってから始まります。3 時間待っても終わらない場合は、その回は実行せず、「前回の実行」に理由を表示します（タスク スケジューラの「前回の実行結果」も失敗の値になります。on_failure.ps1 による通知は行いません）。

実行している間だけ、データフォルダに tenantsnap_run.lock という中身の無いファイルができ、終わると消えます。バックアップの対象から外していただいてかまいません。

重要：認証情報（DPAPI）の制約

認証情報は「保存したユーザー」だけが復号できます。次の構成では復号に失敗するため対応外です。

• 別アカウントでの実行
• SYSTEM や gMSA での実行
• 「パスワードを保存しない」（プロファイルを読み込まない S4U）タスク

必ず、セットアップしたユーザー自身の資格情報を保存する形にしてください。PC 入替や Windows ユーザー変更後は復号できなくなるため、設定画面から認証情報を再設定します。

失敗したときに通知を受け取る（任意）

無人で運用していると失敗に気づきにくいため、取得や設計書の生成が失敗したときに、メールや Teams などお客様の任意の方法で通知できる仕組みを用意しています。通知の中身はお客様が自由に記述でき、ツール自身が外部へ送信することはありません（テレメトリなしの方針は変わりません）。

1. データフォルダ（config.json や .env があるフォルダ。既定は %APPDATA%\TenantSnap）に、on_failure.ps1 という名前の PowerShell スクリプトを置きます。
2. 定期実行が次のいずれかで失敗したとき、このスクリプトが自動的に呼ばれます。
   • 設定の取得（Intune からのダウンロード）に失敗したとき（認証エラー・通信障害など。無人運用で最も重要です）
   • 「設計書・差分レポートまで生成する」をオンにしていて、設計書の生成に失敗したとき（ディスク不足など）
3. スクリプトには、失敗した工程・データフォルダ・ログフォルダ・終了コード・テナント名が引数として渡されます。ログフォルダにはその日のログがあるため、原因の確認やメールへの添付に使えます。

差分（変更履歴）の計算に失敗しても通知されません。初回の実行ではスナップショットが1世代しかなく差分は正常にスキップされるため、これを失敗として通知すると毎回誤報になるからです。on_failure.ps1 を置かない場合の動作は従来と変わりません。

on_failure.ps1 を置いていなくても、定期実行の失敗は Windows の「タスク スケジューラ」で確認できます。該当タスクの「前回の実行結果」が、成功なら 0x0、失敗ならそれ以外の値になります。失敗として扱うのは、設定の取得・設計書の作成・差分レポートの作成ができなかったとき、複数テナント運用で納品先を指定している場合は共有フォルダへのコピーができなかったときや納品する設計書・差分レポートが 1 つも見つからなかったとき、処理の前に出力フォルダを確かめられなかった（読めない・ドライブやネットワークの共有に届かない）とき、そしてアプリでの実行が 3 時間たっても終わらず、その回を実行しなかったときです。初回の実行のように比較する前回の記録がまだ無い場合は、成功として扱います。タスクの結果を監視ツールで見ている場合は、失敗時にそちらでも気づけます。同じ内容は、アプリの「設定 ＞ 定期実行」の「前回の実行」にも表示されます（上の「定期実行が動いているかを確かめる」参照）。

古い記録を圧縮してディスクを節約する（任意）

取得データ（スナップショット）とログは、実行のたびに少しずつ溜まっていきます。無人サーバーで定期実行を長く続ける場合に備えて、指定した日数より古い記録を自動で圧縮し、ディスクの使用量を抑えられます（既定はオフ）。

1. 「設定 ＞ 定期実行」の「古い記録を圧縮してディスクを節約する」をオンにします。
2. 同じ画面で、何日より古いものを圧縮するかをスナップショット・ログそれぞれ設定できます（既定：スナップショット30日・ログ7日）。

削除ではなく圧縮です。圧縮した記録からでも、設計書の作り直しや過去との差分抽出はこれまでどおり行えます（圧縮したファイルは自動で読み込まれます・外部送信はありません）。差分に必要な直近2回分のスナップショットは、日数に関わらず圧縮しません。

圧縮が動くのは設定の取得が成功した直後です（手動実行・定期実行のどちらでも動きます）。取得が失敗したときは何も変更しません。圧縮すると古いスナップショットのファイル名は tenantsnap_config_YYYYMMDD.json.gz になるため、snapshots フォルダのファイルを参照する独自スクリプトをお使いの場合はご注意ください。

アクセス制限のあるサーバーでの WebView2 の事前導入

前提：TenantSnap は構成の取得のために Microsoft の公式エンドポイント（login.microsoftonline.com／graph.microsoft.com）へ接続できる必要があります。完全にインターネットから切り離されたサーバーでは動作しません。この節は「これらの Microsoft エンドポイントは（直接または社内プロキシ経由で）許可されているが、それ以外の一般のインターネットは遮断されている」サーバーを対象とします。

アプリの画面表示には Microsoft Edge WebView2 ランタイムが必要です。一般のインターネットに出られる環境なら初回起動時に自動で導入されますが、上記のように一般のインターネットが遮断されたサーバーでは、WebView2 の配布サイトにも出られないため、事前に手動で導入します。

1. 一般のインターネットに出られる別の PC で、Microsoft の「WebView2 ランタイム」の Evergreen Standalone Installer（x64／オフライン用の単体インストーラー）をダウンロードします。
2. そのインストーラーをサーバーへコピーし、管理者として実行します。
3. 導入後に TenantSnap をインストール・起動してください。