# 機能設計書 495-Install-DbaAgentAdminAlert

## 概要

本ドキュメントは、標準的な SQL Server Agent 管理者向けアラートの一括作成機能 `Install-DbaAgentAdminAlert` の設計仕様を記載する。

### 本機能の処理概要

クリティカルなシステムエラー（重大度レベル17-25）とディスクI/O障害エラー（メッセージ823-825）に対する標準的な SQL Server Agent アラートを一括作成する機能である。

**業務上の目的・背景**：SQL Server で発生する重大なエラーには、ハードウェア障害、データベース破損、リソース不足、致命的システムエラーなど、DBA による即時対応が必要なものが多い。これらのエラーを検知し、適切なオペレーターに通知するアラートを各インスタンスに手動で設定することは、特に大規模環境では非効率である。本機能により、業界標準の管理者向けアラート（重大度17-25、メッセージ823-825）を一括で作成でき、複数インスタンスにわたる一貫した監視体制を効率的に構築できる。

**機能の利用シーン**：
- 新規 SQL Server インスタンスの初期設定時
- 複数インスタンスへの標準アラート展開
- 既存環境のアラート設定監査・補完
- コンプライアンス要件に対する監視体制整備
- 災害復旧計画に基づく監視設定

**主要な処理内容**：
1. 対象 SQL Server インスタンスへの接続
2. 必要に応じてオペレーターの作成（OperatorEmail 指定時）
3. 必要に応じてアラートカテゴリの作成
4. 重大度17-25のアラート作成（除外指定可能）
5. メッセージID 823-825のアラート作成（除外指定可能）
6. 作成したアラートの出力

**関連システム・外部連携**：SQL Server Agent アラートシステム、Database Mail（通知用）。New-DbaAgentAlert、New-DbaAgentOperator、New-DbaAgentAlertCategory など関連コマンドを内部で使用。

**権限による制御**：SQL Server への sysadmin 権限が必要。アラート作成には msdb への書き込み権限が必要となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | Agentアラート管理 | 補助機能 | 標準システムアラートのインストール |

## 機能種別

データ作成（INSERT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQLServerインスタンス | 必須、配列対応 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| ExcludeSeverity | int[] | No | 除外する重大度レベル | 17-25の範囲 |
| ExcludeMessageId | int[] | No | 除外するメッセージID | 823-825の範囲 |
| Operator | string | No | 通知先オペレーター名 | - |
| OperatorEmail | string | No | オペレーター作成時のメールアドレス | Operator と併用 |
| Category | string | No | アラートカテゴリ名 | - |
| Database | string | No | 対象データベース限定 | - |
| DelayBetweenResponses | int | No | 通知間隔（秒） | - |
| Disabled | switch | No | 無効状態で作成 | - |
| NotifyMethod | string | No | 通知方法 | None/NotifyEmail/Pager/NetSend/NotifyAll |
| NotificationMessage | string | No | 通知メッセージ | - |
| EventDescriptionKeyword | string | No | イベント説明フィルタキーワード | - |
| JobId | string | No | 応答ジョブID | GUID形式 |
| EventSource | string | No | イベントソース | - |
| EnableException | switch | No | 例外処理の制御フラグ | - |

### 入力データソース

- 内部定義の namehash（重大度/メッセージIDとアラート名のマッピング）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピューター名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| InstanceName | string | SQL Serverインスタンス名 |
| Name | string | アラート名 |
| Severity | int | 重大度レベル（重大度アラートの場合） |
| MessageId | int | メッセージID（メッセージIDアラートの場合） |
| JobName | string | 応答ジョブ名（指定時） |
| CategoryName | string | カテゴリ名（指定時） |
| DelayBetweenResponses | int | 通知間隔（指定時） |
| ID | int | アラートID |
| AlertType | enum | アラートタイプ |
| IsEnabled | bool | 有効フラグ |

### 出力先

PowerShell パイプラインへの出力（`Microsoft.SqlServer.Management.Smo.Agent.Alert` オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. 初期設定
   └─ namehash（重大度/メッセージIDとアラート名のマッピング）定義
2. インスタンスループ開始
   └─ 各 SqlInstance に対して処理
3. SQL Server 接続
   └─ Connect-DbaInstance で接続確立
4. オペレーター処理
   └─ 指定時は取得または作成
5. カテゴリ処理
   └─ 指定時は取得または作成
6. 既定オペレーター確認
   └─ 未指定時は既存オペレーターを使用（1件のみの場合）
7. 除外処理
   └─ ExcludeSeverity/ExcludeMessageId に基づき namehash から除外
8. アラート作成ループ
   └─ namehash の各エントリに対してアラート作成
9. 結果出力
   └─ 作成したアラートを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[namehash 定義]
    B --> C{SqlInstance ループ}
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function]
    F --> C
    E -->|Yes| G{Operator 指定?}
    G -->|Yes| H{オペレーター存在?}
    H -->|No| I{OperatorEmail あり?}
    I -->|Yes| J[New-DbaAgentOperator]
    I -->|No| K[オペレーター取得のみ]
    H -->|Yes| K
    G -->|No| L{既存オペレーター1件?}
    L -->|Yes| M[既存オペレーターを使用]
    L -->|No| N[Stop-Function]
    J --> O{Category 指定?}
    K --> O
    M --> O
    O -->|Yes| P{カテゴリ存在?}
    P -->|No| Q[New-DbaAgentAlertCategory]
    P -->|Yes| R[除外処理]
    O -->|No| R
    Q --> R
    R --> S{namehash ループ}
    S --> T{アラート存在?}
    T -->|Yes| U[Stop-Function でスキップ]
    T -->|No| V[New-DbaAgentAlert]
    U --> W[Get-DbaAgentAlert で出力]
    V --> W
    W --> S
    S -->|終了| C
    C -->|終了| X[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-495-01 | 標準アラート定義 | 重大度17-25、メッセージID 823-825のアラートを作成 | デフォルト |
| BR-495-02 | 既存アラートスキップ | 同名アラートが存在する場合は作成をスキップ | 常時 |
| BR-495-03 | オペレーター自動検出 | Operator 未指定時、既存オペレーターが1件のみなら自動使用 | Operator 未指定時 |
| BR-495-04 | オペレーター作成 | Operator と OperatorEmail の両方指定時、オペレーターを新規作成 | 両パラメータ指定時 |
| BR-495-05 | カテゴリ自動作成 | 指定カテゴリが存在しない場合は自動作成 | Category 指定時 |
| BR-495-06 | 重大度823未満は重大度アラート | namehash のキーが823未満の場合は Severity パラメータを使用 | namehash処理時 |
| BR-495-07 | 重大度823以上はメッセージIDアラート | namehash のキーが823以上の場合は MessageId パラメータを使用 | namehash処理時 |

### 計算ロジック

**アラート種別判定**:
```powershell
if ($item -lt 823) {
    $parms.Severity = $item    # 重大度アラート
} else {
    $parms.MessageId = $item   # メッセージIDアラート
}
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| オペレーター確認/作成 | msdb.dbo.sysoperators | SELECT/INSERT | オペレーター情報の確認・作成 |
| カテゴリ確認/作成 | msdb.dbo.syscategories | SELECT/INSERT | アラートカテゴリの確認・作成 |
| アラート作成 | msdb.dbo.sysalerts | INSERT | アラートの作成 |

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

#### msdb.dbo.sysalerts

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name, severity, message_id, enabled, delay_between_responses など | New-DbaAgentAlert 経由 | SMO経由で作成 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server への接続失敗 | Stop-Function で Continue |
| OperatorError | オペレーターエラー | オペレーター作成失敗 | Stop-Function で Continue |
| AlertExists | 重複エラー | 同名アラートが存在 | Stop-Function で Continue（スキップ） |
| NoOperator | オペレーターなし | オペレーター未指定で複数/0件存在 | Stop-Function で Continue |

### リトライ仕様

リトライ処理は実装されていない。エラー時は次の処理へ継続する。

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

各アラートは個別に作成される。ロールバック機能は提供されない。

## パフォーマンス要件

- 各インスタンスへの接続は順次処理
- 最大12個のアラート（重大度9個 + メッセージID3個）を作成
- 各アラート作成は SMO の Create() メソッドを使用

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

- SQL Server への接続には SqlCredential による認証情報指定が可能
- sysadmin 権限が必要
- ShouldProcess（WhatIf/Confirm）をサポート

## 備考

- デフォルトで作成されるアラート:
  - Severity 017 - Insufficient Resources
  - Severity 018 - Nonfatal Internal Error
  - Severity 019 - SQL Server Error in Resource
  - Severity 020 - SQL Server Fatal Error in Current Process
  - Severity 021 - SQL Server Fatal Error in Database Process
  - Severity 022 - Table Integrity Suspect
  - Severity 023 - Database Integrity Suspect
  - Severity 024 - Hardware Error
  - Severity 025 - Fatal System Error
  - Error Number 823 - Read/Write Error
  - Error Number 824 - Read/Write Error
  - Error Number 825 - Read/Write Error

---

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

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

### 推奨読解順序

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

namehash の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | 160-173行目の namehash 定義 |

**読解のコツ**: namehash はキーが重大度レベルまたはメッセージID、値がアラート名のハッシュテーブル。823未満は重大度、823以上はメッセージID。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | 138-158行目のパラメータ定義、189行目の process ブロック開始 |

**主要処理フロー**:
1. **160-173行目**: namehash 定義（begin ブロック）
2. **190-195行目**: Connect-DbaInstance で接続
3. **197-225行目**: オペレーター処理
4. **227-252行目**: カテゴリ処理
5. **254-266行目**: 既定オペレーター検出
6. **307-317行目**: 除外処理
7. **319-344行目**: アラート作成ループ

#### Step 3: オペレーター/カテゴリ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | 197-252行目のオペレーター/カテゴリ処理 |

**主要処理フロー**:
- **199行目**: Get-DbaAgentOperator でオペレーター確認
- **200-220行目**: OperatorEmail 指定時は New-DbaAgentOperator で作成
- **229行目**: Get-DbaAgentAlertCategory でカテゴリ確認
- **230-247行目**: 存在しない場合は New-DbaAgentAlertCategory で作成

#### Step 4: アラート作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | 319-344行目のアラート作成ループ |

**主要処理フロー**:
- **319行目**: foreach ($item in $namehash.Keys)
- **325-329行目**: 重大度/メッセージID 判定
- **331-332行目**: 既存アラートチェック
- **337行目**: New-DbaAgentAlert で作成
- **343行目**: Get-DbaAgentAlert で出力

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

```
Install-DbaAgentAdminAlert
    │
    ├─ begin ブロック
    │      └─ namehash 定義
    │
    ├─ Connect-DbaInstance
    │      └─ SMO 接続確立
    │
    ├─ Get-DbaAgentOperator
    │      └─ オペレーター確認
    │
    ├─ New-DbaAgentOperator
    │      └─ オペレーター作成（必要時）
    │
    ├─ Get-DbaAgentAlertCategory
    │      └─ カテゴリ確認
    │
    ├─ New-DbaAgentAlertCategory
    │      └─ カテゴリ作成（必要時）
    │
    ├─ New-DbaAgentAlert
    │      └─ アラート作成
    │
    └─ Get-DbaAgentAlert
           └─ 作成したアラートの取得・出力
```

### データフロー図

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

SqlInstance ─────────────┬─► Connect-DbaInstance ──────────────► SMO Server
SqlCredential ───────────┘                                              │
                                                                        ▼
Operator ────────────────────► Get-DbaAgentOperator ◄──────────────────┤
OperatorEmail ───────────────► New-DbaAgentOperator（必要時）           │
                                        │                               │
Category ────────────────────► Get-DbaAgentAlertCategory ◄─────────────┤
                               New-DbaAgentAlertCategory（必要時）       │
                                        │                               │
                                        ▼                               │
ExcludeSeverity ─────────────► namehash から除外                        │
ExcludeMessageId ────────────►         │                               │
                                        ▼                               │
                               foreach (namehash.Keys)                  │
                                        │                               │
                               ┌────────┴────────┐                      │
                               ▼                 ▼                      │
                         Severity < 823    Severity >= 823              │
                               │                 │                      │
                               ▼                 ▼                      │
                         重大度アラート    メッセージIDアラート          │
                               │                 │                      │
                               └────────┬────────┘                      │
                                        ▼                               │
                               New-DbaAgentAlert ◄──────────────────────┘
                                        │
                                        ▼
                               Get-DbaAgentAlert ───────────► Alert オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | ソース | メイン機能実装 |
| New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | ソース | アラート作成 |
| New-DbaAgentOperator.ps1 | `public/New-DbaAgentOperator.ps1` | ソース | オペレーター作成 |
| New-DbaAgentAlertCategory.ps1 | `public/New-DbaAgentAlertCategory.ps1` | ソース | カテゴリ作成 |
| Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | ソース | オペレーター取得 |
| Get-DbaAgentAlertCategory.ps1 | `public/Get-DbaAgentAlertCategory.ps1` | ソース | カテゴリ取得 |
| Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | ソース | アラート取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続 |
