# 機能設計書 36-Get-DbaBackupInformation

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Get-DbaBackupInformation`コマンドレットに関する機能設計書です。このコマンドは、バックアップファイルをスキャンしてヘッダーを読み取り、リストア操作用の構造化されたバックアップ履歴オブジェクトを作成します。

### 本機能の処理概要

Get-DbaBackupInformationは、指定されたパスにあるSQL Serverバックアップファイルのヘッダーを読み取り、Restore-DbaDatabase互換のBackupHistoryオブジェクトを作成します。バックアップチェーンやファイルの場所を手動で追跡する必要がなくなり、データベースリストアの計画を効率化します。

**業務上の目的・背景**：データベースリストアを計画する際、バックアップファイルのメタデータ（LSNチェーン、ファイルリスト、バックアップタイプ等）を把握する必要があります。この機能により、バックアップファイル群を自動的にスキャンし、リストア可能な形式で情報を整理できます。

**機能の利用シーン**：
- ディザスタリカバリ準備としてのバックアップファイル分析
- 別サーバーへのデータベース移行前のバックアップ確認
- バックアップファイルの棚卸しとドキュメント化
- Ola Hallengrenメンテナンスソリューション環境での効率的なスキャン

**主要な処理内容**：
1. 指定パスまたはファイルオブジェクトの収集
2. xp_dirtreeまたはGet-ChildItemによるファイル列挙
3. Read-DbaBackupHeaderによるヘッダー情報読み取り
4. BackupSetGUIDでのグループ化とBackupHistoryオブジェクト構築
5. オプションでCliXmlエクスポート

**関連システム・外部連携**：
- Read-DbaBackupHeader（バックアップヘッダー読み取り）
- Restore-DbaDatabase（リストア実行先）
- Select-DbaBackupInformation（バックアップ選択）

**権限による制御**：バックアップファイルへの読み取りアクセス権限が必要です。xp_dirtree使用時はSQL Serverサービスアカウントからのアクセスも必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | バックアップ情報 | 主機能 | バックアップ情報の取得 |

## 機能種別

データ取得処理 / ファイルスキャン

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | object[] | Yes | バックアップファイルパス（文字列またはFileInfo） | パイプライン入力対応 |
| SqlInstance | DbaInstanceParameter | Yes (Create) | ヘッダー読み取り用SQL Server | ParameterSetName "Create" |
| SqlCredential | PSCredential | No | SQL Server接続資格情報 | - |
| DatabaseName | string[] | No | フィルタ対象データベース名 | - |
| SourceInstance | string[] | No | フィルタ対象ソースインスタンス | - |
| NoXpDirTree | switch | No | xp_dirtreeを使用しない | - |
| NoXpDirRecurse | switch | No | xp_dirtreeで再帰しない | - |
| DirectoryRecurse | switch | No | ディレクトリを再帰スキャン | - |
| MaintenanceSolution | switch | No | Ola Hallengren形式フォルダ | - |
| IgnoreLogBackup | switch | No | LOGフォルダをスキップ | MaintenanceSolutionと併用 |
| IgnoreDiffBackup | switch | No | DIFFフォルダをスキップ | MaintenanceSolutionと併用 |
| StorageCredential | string | No | Azure/S3ストレージ資格情報 | - |
| ExportPath | string | No | CliXmlエクスポート先 | - |
| NoClobber | switch | No | 上書き禁止 | ExportPathと併用 |
| PassThru | switch | No | エクスポート後も出力 | ExportPathと併用 |
| Import | switch | No | CliXmlインポートモード | ParameterSetName "Import" |
| Anonymise | switch | No | 出力をハッシュ化 | - |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- ファイルシステム（バックアップファイル）
- SQL Serverインスタンス（ヘッダー読み取り用）
- CliXmlファイル（Importモード時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | バックアップ元コンピュータ名 |
| InstanceName | string | バックアップ元インスタンス名 |
| SqlInstance | string | バックアップ元完全インスタンス名 |
| Database | string | データベース名 |
| UserName | string | バックアップ実行ユーザー |
| Start | DateTime | バックアップ開始日時 |
| End | DateTime | バックアップ終了日時 |
| Duration | TimeSpan | バックアップ所要時間 |
| Path | string[] | バックアップファイルパス |
| FullName | string[] | バックアップファイルパス |
| FileList | object[] | ファイル情報（Type, LogicalName, PhysicalName, Size） |
| TotalSize | long | バックアップサイズ（バイト） |
| CompressedBackupSize | long | 圧縮後サイズ（バイト） |
| Type | string | バックアップタイプ（Full/Differential/Log） |
| BackupSetId | guid | バックアップセットGUID |
| DeviceType | string | デバイスタイプ（Disk） |
| Position | int | メディア内位置 |
| FirstLsn | bigint | 最初のLSN |
| DatabaseBackupLsn | bigint | データベースバックアップLSN |
| CheckpointLSN | bigint | チェックポイントLSN |
| LastLsn | bigint | 最後のLSN |
| SoftwareVersionMajor | int | SQL Serverメジャーバージョン |
| RecoveryModel | string | リカバリモデル |
| IsCopyOnly | bool | コピーオンリーフラグ |

### 出力先

- PowerShellパイプライン（Dataplat.Dbatools.Database.BackupHistory）
- CliXmlファイル（ExportPath指定時）

## 処理フロー

### 処理シーケンス

```
1. begin ブロック
   └─ ExportPath検証（NoClobber）
   └─ SqlInstance接続（Createモード）
   └─ IgnoreLogBackup/MaintenanceSolution整合性チェック

2. process ブロック
   ├─ Importモード:
   │   └─ Import-Clixml でBackupHistory読み込み
   │   └─ LSN値をBigIntに変換
   │
   └─ Createモード:
       ├─ クラウドURL検出（http/s3）→ NoXpDirTree有効化
       │
       ├─ xp_dirtree使用時:
       │   ├─ 単一ファイル: Test-DbaPathで検証
       │   ├─ MaintenanceSolution: Get-XpDirTreeRestoreFile
       │   └─ フォルダ: Get-XpDirTreeRestoreFile
       │
       └─ NoXpDirTree時:
           ├─ FileInfo: Get-ChildItem
           └─ MaintenanceSolution: FULL/DIFF/LOG サブフォルダ検索

3. ファイル処理
   └─ MaintenanceSolution + IgnoreLogBackup: LOGパス除外
   └─ MaintenanceSolution + IgnoreDiffBackup: DIFFパス除外
   └─ Read-DbaBackupHeader でヘッダー読み取り

4. グループ化と出力構築
   └─ BackupSetGUIDでGroup-Object
   └─ BackupHistoryオブジェクト構築
   └─ SourceInstance/DatabaseNameフィルタ適用
   └─ Anonymise処理（オプション）
   └─ Export-Clixml（ExportPath指定時）
   └─ End降順ソートで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Importモード?}
    B -->|Yes| C[Import-Clixml]
    C --> D[LSN変換]
    B -->|No| E[SQL Server接続]
    E --> F{クラウドURL?}
    F -->|Yes| G[NoXpDirTree有効化]
    F -->|No| H{NoXpDirTree?}
    G --> H
    H -->|No| I[xp_dirtree経由ファイル列挙]
    H -->|Yes| J[Get-ChildItem/直接指定]
    I --> K[MaintenanceSolutionフィルタ]
    J --> K
    K --> L[Read-DbaBackupHeader]
    L --> M[BackupSetGUIDでグループ化]
    M --> N[BackupHistoryオブジェクト構築]
    N --> O{Anonymise?}
    O -->|Yes| P[ハッシュ化処理]
    O -->|No| Q{ExportPath?}
    P --> Q
    Q -->|Yes| R[Export-Clixml]
    Q -->|No| S[パイプライン出力]
    R --> S
    D --> S
    S --> T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | xp_dirtree優先 | デフォルトでxp_dirtreeを使用 | NoXpDirTree未指定時 |
| BR-02 | クラウド自動検出 | http/s3 URLでNoXpDirTree自動有効化 | パスがURL形式時 |
| BR-03 | Ola形式最適化 | FULL/DIFF/LOGフォルダ構造を認識 | MaintenanceSolution指定時 |
| BR-04 | グループ化 | BackupSetGUIDで同一バックアップセットをグループ化 | 常時 |
| BR-05 | LSN BigInt変換 | Import時にLSN値をBigIntに変換 | Importモード時 |

### 計算ロジック

Duration計算：
```
Duration = BackupFinishDate - BackupStartDate
```

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ヘッダー読み取り | - | RESTORE HEADERONLY | バックアップファイルメタデータ取得 |
| ファイル列挙 | - | xp_dirtree | ディレクトリ内容取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | 接続情報確認 |
| - | FileNotFound | バックアップファイルなし | パス確認 |
| - | AccessDenied | ファイルアクセス権限なし | 権限確認 |
| - | ExportExists | NoClobber時にファイル存在 | 別パス指定 |

### リトライ仕様

リトライ機能は実装されていません。

## トランザクション仕様

読み取り専用操作のためトランザクションは使用しません。

## パフォーマンス要件

- xp_dirtreeはSQL Server経由でリモートパスをスキャン可能
- 大量ファイルの場合、ヘッダー読み取りに時間がかかる
- MaintenanceSolutionモードで効率的なスキャンが可能

## セキュリティ考慮事項

- バックアップファイルへの読み取り権限が必要
- xp_dirtree使用時はSQL Serverサービスアカウントからのアクセスも必要
- Anonymiseで機密情報をハッシュ化可能

## 備考

- Ola Hallengrenメンテナンスソリューション形式に特別対応
- Azure Blob Storage / S3オブジェクトストレージ対応（SQL Server 2022+）

---

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

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

### 推奨読解順序

#### Step 1: パラメータ定義とParameterSetを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaBackupInformation.ps1 | `public/Get-DbaBackupInformation.ps1` | パラメータ定義（179-208行目）、Create/Importの2つのParameterSet |

**読解のコツ**: `ParameterSetName`で"Create"と"Import"の2モードがあり、Importモードは既存のCliXmlファイルを読み込む。

#### Step 2: begin ブロックの初期化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaBackupInformation.ps1 | `public/Get-DbaBackupInformation.ps1` | beginブロック（210-245行目）でのGet-HashString関数とバリデーション |

**主要処理フロー**:
1. **211-221行目**: Get-HashString内部関数（Anonymise用）
2. **225-232行目**: ExportPath検証
3. **233-240行目**: SQL Server接続
4. **242-244行目**: IgnoreLogBackup/MaintenanceSolution整合性チェック

#### Step 3: process ブロックのファイル収集を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaBackupInformation.ps1 | `public/Get-DbaBackupInformation.ps1` | processブロック（246-406行目）でのファイル収集とBackupHistory構築 |

**主要処理フロー**:
- **248-261行目**: Importモード処理
- **267行目**: クラウドURL検出
- **268-335行目**: xp_dirtree/Get-ChildItemによるファイル列挙
- **337-345行目**: MaintenanceSolution + IgnoreLog/Diffフィルタ
- **347-354行目**: Read-DbaBackupHeader実行
- **356-405行目**: BackupSetGUIDグループ化とオブジェクト構築

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

```
Get-DbaBackupInformation
    │
    ├─ begin ブロック
    │      │
    │      ├─ Get-HashString (内部関数定義)
    │      │
    │      ├─ Test-Bound + Test-Path (ExportPath検証)
    │      │
    │      └─ Connect-DbaInstance
    │
    └─ process ブロック
           │
           ├─ Importモード
           │      └─ Import-Clixml
           │
           └─ Createモード
                  │
                  ├─ ファイル収集
                  │      ├─ Get-XpDirTreeRestoreFile
                  │      └─ Get-ChildItem
                  │
                  ├─ Read-DbaBackupHeader
                  │
                  ├─ Group-Object -Property BackupSetGUID
                  │
                  ├─ New-Object Dataplat.Dbatools.Database.BackupHistory
                  │
                  ├─ Get-HashString (Anonymise時)
                  │
                  └─ Export-Clixml (ExportPath時)
```

### データフロー図

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

$Path ─────────────────▶ ファイル列挙 ────────────────▶ $Files
(文字列/FileInfo)                │
                         xp_dirtree or Get-ChildItem
                                 │
$Files ────────────────▶ Read-DbaBackupHeader ────────▶ $FileDetails
                                 │
$FileDetails ──────────▶ Group-Object BackupSetGUID ──▶ $groupDetails
                                 │
$groupDetails ─────────▶ BackupHistory構築 ───────────▶ $groupResults
                                 │
$DatabaseName ─────────▶ フィルタリング ───────────────▶ $groupResults (フィルタ後)
$SourceInstance                  │
                                 │
$Anonymise ────────────▶ Get-HashString ───────────────▶ ハッシュ化
                                 │
$ExportPath ───────────▶ Export-Clixml ────────────────▶ CliXmlファイル
                                 │
                         Sort-Object -Property End
                                 │
                                 └─────────────────────────▶ BackupHistory[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaBackupInformation.ps1 | `public/Get-DbaBackupInformation.ps1` | ソース | メイン関数実装 |
| Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | ソース | ヘッダー読み取り |
| Get-XpDirTreeRestoreFile.ps1 | `internal/functions/Get-XpDirTreeRestoreFile.ps1` | ソース | xp_dirtree経由ファイル列挙 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス存在確認 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
