# 画面設計書 235-監査ファイル読み取り

## 概要

本ドキュメントは、dbatools PowerShell モジュールの `Read-DbaAuditFile` コマンドに関する設計書です。このコマンドは、SQL Server 監査ファイル（.sqlaudit）を解析し、セキュリティ分析やコンプライアンスレポート作成に使用できる構造化データとして出力します。

### 本画面の処理概要

**業務上の目的・背景**：SQL Server 監査機能は、データベースアクセスやセキュリティイベントをバイナリ形式の .sqlaudit ファイルに記録します。これらのファイルは直接読み取ることができないため、本コマンドは監査データを PowerShell オブジェクトに変換し、セキュリティ調査、コンプライアンス報告、アクセスパターン分析などに活用できるようにします。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから `Read-DbaAuditFile` コマンドを実行します。ファイルパス、FileInfo オブジェクト、または Get-DbaInstanceAudit の出力をパイプライン入力として受け取ることが可能です。

**主要な操作・処理内容**：
1. 入力パス（文字列、FileInfo、または Audit オブジェクト）を処理
2. ワイルドカードを展開して関連する監査ファイルを検出
3. Read-XEvent を使用してバイナリ監査データを読み取り
4. フィールドとアクションを抽出してカラムを動的構築
5. PSCustomObject としてパイプラインに出力

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

**権限による表示制御**：監査ファイルへの読み取りアクセス権限が必要です。リモートサーバーの場合は管理共有（admin$）へのアクセス権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 648 | Read-DbaAuditFile | 主機能 | 監査ファイルの読み取り |
| 96 | Get-DbaInstanceAudit | 補助機能 | インスタンス監査情報の取得 |

## 画面種別

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

## URL/ルーティング

PowerShell コマンド: `Read-DbaAuditFile`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Path | object[] | Yes | 監査ファイルパス（Alias: FullName） |
| Raw | switch | No | 生の列挙オブジェクトを返す |
| EnableException | switch | No | 例外を有効化 |

### Path パラメータで受け入れる型

| 型 | 説明 |
|----|------|
| System.String | ファイルパス文字列 |
| System.IO.FileInfo | Get-ChildItem からの FileInfo オブジェクト |
| Microsoft.SqlServer.Management.Smo.Audit | Get-DbaInstanceAudit からの Audit オブジェクト |

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| name | string | 監査イベント名 |
| timestamp | datetime | イベント発生日時 |
| Fields.* | dynamic | 監査ファイルに含まれるフィールド（動的） |
| Actions.* | dynamic | 監査アクション（動的、サフィックスのみ） |

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| (Raw Object) | object | Read-XEvent からの生データ |

## 表示項目

監査ファイルの内容に応じて動的にプロパティが追加されます。一般的なプロパティ例：
- event_time
- action_id
- succeeded
- session_id
- server_principal_name
- database_name
- object_name
- statement

## イベント仕様

### 1-コマンド実行

1. Path パラメータの型を判定（String、FileInfo、または Audit オブジェクト）
2. Audit オブジェクトの場合、IsLocalHost に応じてローカルまたはリモートパスを使用
3. ワイルドカード展開で関連する .sqlaudit ファイルを検出
4. 各ファイルのアクセシビリティを確認（Test-Path）
5. Read-XEvent で監査データを読み取り
6. Raw 指定時は生データをそのまま返却
7. フィールドとアクションからカラムを動的構築
8. PSCustomObject としてパイプラインに出力

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

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

このコマンドはファイルシステムから監査ファイルを読み取るのみで、データベースへのアクセスは行いません。

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| Error | "Unsupported file type." | サポートされない入力型 |
| Error | "This Audit does not have an associated file." | Audit オブジェクトにファイルなし |
| Error | "$fileName cannot be accessed from $env:COMPUTERNAME. Does $whoami have access?" | ファイルアクセス不可 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| サポートされない入力型 | Stop-Function で処理停止 |
| Audit にファイルなし | Stop-Function で処理停止 |
| ファイルアクセス不可 | Stop-Function で Continue、次のファイルへ |

## 備考

- .sqlaudit 拡張子のファイルのみ対象
- ワイルドカード展開: 基本ファイル名に `*` を付加して関連ファイルを検出（例: audit_*.sqlaudit）
- リモートファイルは管理共有（\\server\c$\...）経由でアクセス
- Read-XEvent は内部関数で拡張イベントファイルの読み取りを担当
- カラムはファイル内容に応じて動的に生成されるため、Select-Object * で全プロパティを確認可能
- アクションのプロパティ名はドット区切りの最後の部分のみ使用（例: server_principal_name.session_id -> session_id）

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Read-DbaAuditFile.ps1 | `public/Read-DbaAuditFile.ps1` | 行78, 121-129: カラム構築と出力オブジェクト |

**読解のコツ**: カラムは "name", "timestamp" の固定カラムに、動的に Fields と Actions から追加される。

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

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

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

**主要処理フロー**:
1. **行75-102**: 入力パスの型判定とファイルパス正規化
2. **行104-105**: ワイルドカード展開でファイル一覧取得
3. **行107-115**: ファイルアクセシビリティチェックと Read-XEvent 呼び出し
4. **行117-129**: カラム抽出（Fields、Actions）
5. **行131-147**: PSCustomObject の生成と出力

#### Step 3: Read-XEvent の役割を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Read-DbaAuditFile.ps1 | `public/Read-DbaAuditFile.ps1` | 行114: Read-XEvent 呼び出し |

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

```
Read-DbaAuditFile
    │
    ├─ 入力型判定 (行80-102)
    │      ├─ System.String → そのまま使用
    │      ├─ System.IO.FileInfo → FullName を使用
    │      └─ Microsoft.SqlServer.Management.Smo.Audit
    │             └─ IsLocalHost 判定 → FullName または RemoteFullName
    │
    ├─ Get-ChildItem (行105)
    │      └─ ワイルドカード展開
    │
    ├─ Test-Path (行108)
    │      └─ アクセシビリティ確認
    │
    ├─ Read-XEvent (行114)
    │      └─ バイナリ監査データ読み取り
    │
    └─ PSCustomObject 生成 (行132-147)
           ├─ Fields プロパティ展開
           └─ Actions プロパティ展開
```

### データフロー図

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

Path (String/FileInfo/   ───▶ 型判定・パス正規化 ──────────▶ $currentFile
  Audit Object)                    │
                          ワイルドカード展開
                                   │
                          Read-XEvent 呼び出し ────────────▶ $enum (Raw Data)
                                   │
                          カラム抽出
                                   │
                          PSCustomObject 生成 ─────────────▶ Pipeline Output
                                   or
Raw = $true ──────────────────────▶ $enum そのまま ─────────▶ Pipeline Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Read-DbaAuditFile.ps1 | `public/Read-DbaAuditFile.ps1` | ソース | メインコマンド実装 |
| Get-DbaInstanceAudit.ps1 | `public/Get-DbaInstanceAudit.ps1` | ソース | インスタンス監査情報取得 |
