# 画面設計書 236-バックアップヘッダー読み取り

## 概要

本ドキュメントは、dbatools PowerShell モジュールの `Read-DbaBackupHeader` コマンドに関する設計書です。このコマンドは、SQL Server バックアップファイルからメタデータを抽出し、実際のリストア操作を行わずにバックアップの検証、リストア計画、バックアップインベントリ監査を可能にします。

### 本画面の処理概要

**業務上の目的・背景**：バックアップファイルの内容を確認することは、リストア操作の計画、バックアップの検証、バックアップインベントリの監査において不可欠です。本コマンドは SQL Server の RESTORE HEADERONLY 機能を利用して、バックアップファイルからデータベース名、バックアップタイプ、作成日時、ファイルリスト、サイズ情報などのメタデータを抽出します。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから `Read-DbaBackupHeader` コマンドを実行します。バックアップファイルのパスは SQL Server インスタンスからアクセス可能である必要があります。

**主要な操作・処理内容**：
1. SQL Server インスタンスに接続
2. バックアップファイルのパスを検証（Test-DbaPath）
3. Runspace プールを使用してマルチスレッド処理
4. SMO Restore.ReadBackupHeader() でメタデータを取得
5. Restore.ReadFileList() でファイルリストを取得
6. 結果をパイプラインに出力

**画面遷移**：CLI コマンドのため画面遷移は存在しませんが、出力結果は Restore-DbaDatabase などにパイプライン接続可能です。

**権限による表示制御**：バックアップファイルへのアクセス権限が必要です。SQL Server サービスアカウントがファイルを読み取れる必要があります。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 42 | Read-DbaBackupHeader | 主機能 | バックアップヘッダーの読み取り |
| 90 | Connect-DbaInstance | 補助機能 | SQL Server インスタンスへの接続 |
| 226 | Test-DbaPath | 補助機能 | パスのアクセシビリティ確認 |

## 画面種別

CLI コマンド（ファイル読み取り・メタデータ抽出）

## URL/ルーティング

PowerShell コマンド: `Read-DbaBackupHeader`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstance | Yes | SQL Server インスタンス |
| SqlCredential | PSCredential | No | SQL Server 認証情報 |
| Path | object[] | Yes | バックアップファイルパス |
| Simple | switch | No | 簡易出力モード |
| FileList | switch | No | ファイルリスト詳細を出力 |
| StorageCredential | string | No | Azure/S3 ストレージ資格情報名 |
| EnableException | switch | No | 例外を有効化 |

### 出力項目（デフォルト）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| DatabaseName | string | バックアップされたデータベース名 |
| BackupFinishDate | DateTime | バックアップ完了日時 |
| RecoveryModel | string | リカバリモデル |
| BackupSize | dbasize | バックアップサイズ |
| CompressedBackupSize | dbasize | 圧縮後サイズ |
| DatabaseCreationDate | DateTime | データベース作成日時 |
| UserName | string | バックアップ実行ユーザー |
| ServerName | string | バックアップ元サーバー名 |
| SqlVersion | string | SQL Server バージョン |
| BackupPath | string | バックアップファイルパス |
| FileList | object[] | ファイルリスト詳細 |
| BackupType | string | バックアップタイプ |
| Position | int | バックアップセット内の位置 |
| その他 | various | SMO ReadBackupHeader の全プロパティ |

### 出力項目（Simple 指定時）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| DatabaseName | string | データベース名 |
| BackupFinishDate | DateTime | 完了日時 |
| RecoveryModel | string | リカバリモデル |
| BackupSize | dbasize | サイズ |
| CompressedBackupSize | dbasize | 圧縮後サイズ |
| DatabaseCreationDate | DateTime | 作成日時 |
| UserName | string | 実行ユーザー |
| ServerName | string | サーバー名 |
| SqlVersion | string | バージョン |
| BackupPath | string | パス |

### 出力項目（FileList 指定時）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| LogicalName | string | 論理ファイル名 |
| PhysicalName | string | 物理ファイルパス |
| Type | string | ファイルタイプ（D/L） |
| FileGroupName | string | ファイルグループ名 |
| Size | long | ファイルサイズ |
| MaxSize | long | 最大サイズ |
| FileId | int | ファイル ID |
| その他 | various | ReadFileList の全プロパティ |

## 表示項目

デフォルトでは DataTable の全カラムが出力されます。Simple モードでは10カラムに限定されます。

## イベント仕様

### 1-コマンド実行

1. Path パラメータの検証（拡張子チェック）
2. SQL Server インスタンスへの接続
3. バックアップファイルパスの正規化（FileInfo からの展開）
4. Test-DbaPath でファイルアクセシビリティを確認
5. Runspace プール作成（最大10スレッド）
6. 各ファイルに対してマルチスレッドで処理:
   - BackupDeviceItem の作成
   - Restore.ReadBackupHeader() の実行
   - Restore.ReadFileList() の実行
7. 結果の収集と出力

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ヘッダー読み取り | (バックアップファイル) | RESTORE HEADERONLY | メタデータ取得 |
| ファイルリスト取得 | (バックアップファイル) | RESTORE FILELISTONLY | ファイル一覧取得 |

### テーブル別更新項目詳細

このコマンドは読み取り専用であり、データベースの更新は行いません。

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| Verbose | "Checking: $p" | パスチェック時 |
| Verbose | "$pathCount unique files to scan." | ファイル数確認時 |
| Verbose | "Checking accessibility for all the files." | アクセシビリティ確認時 |
| Verbose | "Scanning file $file." | ファイルスキャン時 |
| Warning | "File $file does not exist or access denied." | アクセス不可 |
| Error | "Path should be a file, not a folder" | フォルダパス指定時 |
| Error | "Problem found with $file" | ファイル読み取りエラー |
| Error | "Unable to read $file, check credential" | URL アクセスエラー |
| Error | "$file appears to be from a new version of SQL Server" | バージョン不一致 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| フォルダパス指定 | Stop-Function で処理停止 |
| 接続失敗 | Stop-Function で処理停止 |
| ファイルアクセス不可 | Warning を出力し、次のファイルへ |
| バックアップ読み取りエラー | Stop-Function で Continue |
| バージョン不一致 | Stop-Function で Continue |

## 備考

- バックアップファイルは SQL Server インスタンスからアクセス可能である必要がある
- Azure Blob Storage および S3 ストレージをサポート（StorageCredential パラメータ）
- S3 は SQL Server 2022 以降が必要
- マルチスレッド処理（最大10スレッド）によりパフォーマンス向上
- BackupSize と CompressedBackupSize は dbasize 型（Byte, KB, MB, GB プロパティを持つ）
- SqlVersion は Convert-DbVersionToSqlVersion で変換（例: "SQL Server 2019"）
- INCOMPLETE バックアップは自動的にスキップ

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

出力される DataRow の構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | 行236-263: ReadBackupHeader の処理 |

**読解のコツ**: SMO Restore クラスの ReadBackupHeader() が返す DataTable 構造を理解する。

#### Step 2: エントリーポイントを理解する

処理の起点となるファイル・関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | 関数全体の構造と処理フロー |

**主要処理フロー**:
1. **行204-211**: begin ブロック - パス検証
2. **行213-218**: SQL Server 接続
3. **行219-265**: $getHeaderScript スクリプトブロック定義
4. **行287-288**: Test-DbaPath でアクセシビリティ確認
5. **行290-294**: Runspace プール作成
6. **行298-336**: マルチスレッド処理の開始
7. **行338-376**: 結果の収集と出力

#### Step 3: マルチスレッド処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | 行290-294: Runspace プール作成 |
| 3-2 | Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | 行318-332: スレッド作成と起動 |
| 3-3 | Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | 行338-376: 結果収集ループ |

### プログラム呼び出し階層図

```
Read-DbaBackupHeader
    │
    ├─ Connect-DbaInstance (行214)
    │      └─ SQL Server SMO 接続
    │
    ├─ Test-DbaPath (行287)
    │      └─ ファイルアクセシビリティ確認
    │
    ├─ Runspace Pool 処理 (行290-376)
    │      │
    │      └─ $getHeaderScript (行219-265)
    │             ├─ BackupDeviceItem 作成 (行234)
    │             ├─ Restore.ReadBackupHeader() (行236)
    │             └─ Restore.ReadFileList() (行262)
    │
    └─ Convert-DbVersionToSqlVersion (行357)
           └─ バージョン文字列変換
```

### データフロー図

```
[入力]                    [処理]                           [出力]

Path ──────────────────▶ パス検証 ─────────────────────────▶ 有効パスリスト
                               │
SqlInstance ───────────▶ Connect-DbaInstance ──────────────▶ Server Object
                               │
                         Test-DbaPath ─────────────────────▶ アクセス可能ファイル
                               │
                         Runspace Pool 並列処理
                               │
                         ReadBackupHeader/ReadFileList
                               │
Simple ────────────────▶ 出力カラム選択 ───────────────────▶ DataRow[]
FileList ──────────────▶

StorageCredential ─────▶ URL アクセス設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | ソース | メインコマンド実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続処理 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パスアクセシビリティ確認 |
