# 機能設計書 361-Copy-DbaInstanceAuditSpecification

## 概要

本ドキュメントは、SQL Serverインスタンス間でサーバー監査仕様をコピーするための dbatools コマンド `Copy-DbaInstanceAuditSpecification` の機能設計を記述する。

### 本機能の処理概要

`Copy-DbaInstanceAuditSpecification` は、ソースSQL Serverインスタンスからターゲットインスタンスへサーバー監査仕様（Server Audit Specification）を移行するためのコマンドレットである。

**業務上の目的・背景**：コンプライアンス要件を満たすためのセキュリティ監査構成を複数のSQL Server環境で標準化する必要がある。手動でサーバー監査仕様を各インスタンスに作成することは非効率であり、設定漏れや不整合が発生しやすい。また、ディザスタリカバリやサーバー移行時に監査構成を迅速に復元する必要がある。

**機能の利用シーン**：
- 本番環境と同等の監査構成を開発・テスト環境に展開する場合
- 新しいSQL Serverインスタンスのセットアップ時にセキュリティ標準を適用する場合
- ディザスタリカバリサイトへの監査仕様の複製
- サーバー統合・移行プロジェクトでの監査設定の移行

**主要な処理内容**：
1. ソースサーバーへの接続確立（SQL Server 2008以上必須、sysadmin権限必須）
2. ソースサーバーからServerAuditSpecificationsコレクションの取得
3. ターゲットサーバーへの接続確立（sysadmin権限必須）
4. バージョン互換性チェック（ターゲットがソースより古いバージョンの場合はエラー）
5. 各監査仕様について:
   - フィルタリング条件の確認（AuditSpecification/ExcludeAuditSpecificationパラメータ）
   - 対応するサーバー監査がターゲットに存在するかの確認
   - 既存監査仕様の存在確認と-Forceパラメータによる上書き処理
   - SMOスクリプト機能を使用したT-SQLスクリプト生成
   - ターゲットサーバーでのスクリプト実行

**関連システム・外部連携**：SQL Server SMO (Server Management Objects)を介したスクリプト生成とクエリ実行

**権限による制御**：ソースおよびターゲットの両方でsysadmin権限が必要。sysadmin以外のユーザーで実行した場合は処理を中断する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIツール | 主機能 | PowerShellコンソールから実行 |

## 機能種別

データ連携 / 移行処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | ソースSQL Serverインスタンス | SQL Server 2008以上必須 |
| SourceSqlCredential | PSCredential | No | ソースへの接続資格情報 | - |
| Destination | DbaInstanceParameter[] | Yes | ターゲットSQL Serverインスタンス（複数可） | SQL Server 2008以上必須 |
| DestinationSqlCredential | PSCredential | No | ターゲットへの接続資格情報 | - |
| AuditSpecification | object[] | No | コピー対象の監査仕様名 | - |
| ExcludeAuditSpecification | object[] | No | コピー除外する監査仕様名 | - |
| Force | switch | No | 既存の監査仕様を上書きする | - |
| EnableException | switch | No | 例外を有効化する | - |

### 入力データソース

- ソースSQL Serverインスタンスの `ServerAuditSpecifications` コレクション（SMO経由）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | コピー操作の実行日時 |
| SourceServer | String | ソースSQL Serverインスタンス名 |
| DestinationServer | String | ターゲットSQL Serverインスタンス名 |
| Name | String | 監査仕様名 |
| Type | String | 常に "Server Audit Specification" |
| Status | String | Successful / Skipped / Failed |
| Notes | String | 操作結果の詳細（スキップ理由、エラーなど） |

### 出力先

PowerShellパイプライン（MigrationObject TypeName）

## 処理フロー

### 処理シーケンス

```
1. Begin ブロック
   └─ ソースサーバーへの接続（Connect-DbaInstance -MinimumVersion 10）
   └─ sysadmin権限の確認（Test-SqlSa）
   └─ ServerAuditSpecificationsコレクションの取得
   └─ Forceフラグによる確認設定の調整

2. Process ブロック - 各Destinationに対して
   └─ ターゲットサーバーへの接続
   └─ sysadmin権限の確認
   └─ バージョン互換性の確認（ターゲット >= ソース）
   └─ 各監査仕様について:
       ├─ フィルタ条件の確認（AuditSpecification/ExcludeAuditSpecification）
       ├─ 対応するサーバー監査の存在確認
       │   └─ 存在しない場合: Skipped（警告出力）
       ├─ 既存監査仕様の確認
       │   ├─ 存在 & Force=false: Skipped
       │   └─ 存在 & Force=true: Drop処理
       └─ スクリプト生成・実行（$auditSpec.Script() → $destServer.Query()）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ソースサーバー接続]
    B --> C{sysadmin?}
    C -->|No| D[エラー終了]
    C -->|Yes| E[監査仕様コレクション取得]
    E --> F[各Destinationループ]
    F --> G[ターゲットサーバー接続]
    G --> H{sysadmin?}
    H -->|No| D
    H -->|Yes| I{バージョン互換?}
    I -->|No| D
    I -->|Yes| J[各監査仕様ループ]
    J --> K{フィルタ条件?}
    K -->|除外| J
    K -->|対象| L{サーバー監査存在?}
    L -->|No| M[Skipped出力]
    M --> J
    L -->|Yes| N{既存存在?}
    N -->|Yes & !Force| O[Skipped出力]
    O --> J
    N -->|Yes & Force| P[Drop処理]
    P --> Q[スクリプト実行]
    N -->|No| Q
    Q --> R[Successful出力]
    R --> J
    J --> S{次の仕様?}
    S -->|Yes| J
    S -->|No| T{次のDestination?}
    T -->|Yes| F
    T -->|No| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | sysadmin必須 | ソースとターゲット両方でsysadmin権限が必要 | 常に |
| BR-02 | 監査依存関係 | 対応するサーバー監査がターゲットに存在する必要がある | 監査仕様コピー時 |
| BR-03 | バージョン制約 | 低バージョンから高バージョンへの移行のみサポート | 常に |
| BR-04 | 既存スキップ | -Forceなしで既存監査仕様が存在する場合はスキップ | 既存チェック時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 読取 | sys.server_audit_specifications | SELECT | ソースから監査仕様情報取得（SMO経由） |
| 作成 | sys.server_audit_specifications | CREATE | ターゲットに監査仕様を作成 |
| 削除 | sys.server_audit_specifications | DROP | -Force時に既存監査仕様を削除 |

### テーブル別操作詳細

#### sys.server_audit_specifications

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | SMO ServerAuditSpecifications経由 | ソースサーバー |
| CREATE | * | SMO Script()メソッドで生成 | ターゲットサーバー |
| DROP | name | 監査仕様名で指定 | -Force時のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | ソース/ターゲットに接続できない | 接続情報確認、ネットワーク確認 |
| - | 権限エラー | sysadmin権限がない | 適切な権限を持つアカウントで実行 |
| - | バージョンエラー | ターゲットがソースより低バージョン | 移行方向を確認 |
| - | 依存関係エラー | 対応するサーバー監査が存在しない | 先にサーバー監査をコピー |

### リトライ仕様

リトライ処理は実装されていない

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

各監査仕様のコピーは独立した操作として実行される。1つの監査仕様のコピー失敗は他の監査仕様のコピーに影響しない（continue文で次の処理に進む）。

## パフォーマンス要件

特に定義なし。監査仕様の数に応じて処理時間が増加する。

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

- sysadmin権限が必須
- 資格情報はPSCredentialオブジェクトで安全に取り扱う
- SQL認証、Active Directory認証、MFA対応（Connect-DbaInstance経由）

## 備考

- SQL Server 2008 (v10) 以上が必要
- WhatIf/Confirmパラメータによる事前確認が可能
- 本機能は `Start-DbaMigration` コマンドの一部として呼び出される（ServerAuditSpecifications除外でなければ自動実行）

---

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

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

### 推奨読解順序

#### Step 1: コマンドの概要を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaInstanceAuditSpecification.ps1 | `public/Copy-DbaInstanceAuditSpecification.ps1` | コメントベースヘルプ（1-95行目）で機能の目的と使用方法を把握 |

**読解のコツ**: PowerShellの `<# .SYNOPSIS ... #>` 形式のコメントブロックでコマンドの概要、パラメータ、使用例を確認できる。

#### Step 2: パラメータ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaInstanceAuditSpecification.ps1 | `public/Copy-DbaInstanceAuditSpecification.ps1` | param ブロック（97-108行目）でパラメータ構造を確認 |

**主要処理フロー**:
- **97-98行目**: CmdletBinding属性でSupportsShouldProcessを有効化
- **99行目**: [parameter(Mandatory)]でSourceを必須パラメータとして定義
- **102行目**: Destination配列で複数ターゲット対応

#### Step 3: Begin ブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaInstanceAuditSpecification.ps1 | `public/Copy-DbaInstanceAuditSpecification.ps1` | beginブロック（110-126行目）で初期化処理を確認 |

**主要処理フロー**:
- **111-116行目**: Connect-DbaInstanceでソースサーバー接続（MinimumVersion 10でSQL2008以上を要求）
- **118-121行目**: Test-SqlSaでsysadmin権限を確認
- **123行目**: ServerAuditSpecificationsコレクションを取得
- **125行目**: Forceフラグ時にConfirmPreferenceを無効化

#### Step 4: Process ブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Copy-DbaInstanceAuditSpecification.ps1 | `public/Copy-DbaInstanceAuditSpecification.ps1` | processブロック（127-216行目）でメイン処理を確認 |

**主要処理フロー**:
- **129-134行目**: 各Destinationへの接続ループ
- **141-144行目**: バージョン互換性チェック
- **146-161行目**: 各監査仕様のループとフィルタリング
- **163-172行目**: 対応するサーバー監査の存在確認
- **174-196行目**: 既存監査仕様の処理（Skip/Drop）
- **198-213行目**: スクリプト生成と実行

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

```
Copy-DbaInstanceAuditSpecification
    │
    ├─ Connect-DbaInstance (ソース接続)
    │      └─ -MinimumVersion 10 でSQL 2008以上を要求
    │
    ├─ Test-SqlSa (権限確認)
    │
    ├─ Connect-DbaInstance (ターゲット接続)
    │
    ├─ Test-SqlSa (ターゲット権限確認)
    │
    ├─ $auditSpec.Script() (SMOスクリプト生成)
    │
    ├─ $destServer.ServerAuditSpecifications[].Drop() (既存削除)
    │
    └─ $destServer.Query() (スクリプト実行)
```

### データフロー図

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

Source Instance ───────▶ ServerAuditSpecifications取得
                              │
                              ▼
                         Script()でT-SQL生成
                              │
                              ▼
Destination Instance ───▶ Query()でT-SQL実行 ───────▶ MigrationObject
                                                      (Status/Notes)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaInstanceAuditSpecification.ps1 | `public/Copy-DbaInstanceAuditSpecification.ps1` | ソース | メインコマンド実装 |
| Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | ソース | 上位コマンド（本機能を呼び出す） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続ヘルパー |
