# 通知設計書 18-Install-DbaAgentAdminAlert

## 概要

本ドキュメントは、重大度17-25およびエラーメッセージ823-825の標準的なSQL Serverエージェントアラートを一括作成するdbatools PowerShellコマンド「Install-DbaAgentAdminAlert」の設計仕様を記載します。

### 本通知の処理概要

Install-DbaAgentAdminAlertは、SQL Server管理者向けの標準的なアラートセットを一括でインストールするコマンドです。重大度レベル17-25の致命的エラーと、メッセージID 823-825のディスクI/Oエラーを監視するアラートを作成します。

**業務上の目的・背景**：SQL Serverの本番環境では、ハードウェア障害、データベース破損、リソース不足などの致命的問題を即座に検知することが重要です。本コマンドは、DBAが手動で12個のアラートを個別に設定する手間を省き、ベストプラクティスに基づいた標準監視を迅速に展開できます。新規サーバーセットアップ時や複数環境の標準化に特に有用です。

**通知の送信タイミング**：本コマンドは「アラートを一括作成する」コマンドです。作成されたアラートがトリガーされると（重大度17-25のエラーまたは823-825のI/Oエラー発生時）、指定されたオペレーターに通知が送信されます。

**通知の受信者**：本コマンドの実行結果はコマンド実行者に返されます。作成されたアラートが将来トリガーされた場合、-Operatorパラメータで指定されたオペレーターが通知を受け取ります。

**通知内容の概要**：作成された各アラートの情報（ComputerName、SqlInstance、InstanceName、Name、Severity、MessageId等）が返されます。アラートトリガー時には、SQL Serverエラーの詳細が通知されます。

**期待されるアクション**：管理者はインストール後、オペレーターの通知設定（メールアドレス等）が正しく構成されていることを確認します。アラート発報時には、DBAが迅速に問題を調査・対処することが期待されます。

## 通知種別

SQL Server Agent Alert（オペレーターへのEmail/Pager/NetSend通知を設定）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（アラート作成は即座に完了） |
| 優先度 | 低（ConfirmImpact = 'Low'） |
| リトライ | 無（作成失敗時はエラーメッセージ出力） |

### 送信先決定ロジック

- Operatorパラメータ：通知を受け取るオペレーターを指定
- OperatorEmailパラメータ：オペレーターが存在しない場合に新規作成
- Categoryパラメータ：アラートカテゴリを指定（存在しない場合は作成）
- NotifyMethodパラメータ：通知方法（None/NotifyEmail/Pager/NetSend/NotifyAll）を指定

## 通知テンプレート

### 作成されるアラート一覧

| アラート名 | 種別 | 監視対象 |
|-----------|------|---------|
| Severity 017 - Insufficient Resources | Severity | 重大度17（リソース不足） |
| Severity 018 - Nonfatal Internal Error | Severity | 重大度18（非致命的内部エラー） |
| Severity 019 - SQL Server Error in Resource | Severity | 重大度19（リソースエラー） |
| Severity 020 - SQL Server Fatal Error in Current Process | Severity | 重大度20（現行プロセス致命的エラー） |
| Severity 021 - SQL Server Fatal Error in Database Process | Severity | 重大度21（データベースプロセス致命的エラー） |
| Severity 022 - Table Integrity Suspect | Severity | 重大度22（テーブル整合性疑念） |
| Severity 023 - Database Integrity Suspect | Severity | 重大度23（データベース整合性疑念） |
| Severity 024 - Hardware Error | Severity | 重大度24（ハードウェアエラー） |
| Severity 025 - Fatal System Error | Severity | 重大度25（致命的システムエラー） |
| Error Number 823 - Read/Write Error | MessageId | I/O読み書きエラー（823） |
| Error Number 824 - Read/Write Error | MessageId | I/O読み書きエラー（824） |
| Error Number 825 - Read/Write Error | MessageId | I/O読み書きエラー（825） |

### 本文テンプレート

```
アラート作成成功時の出力:
ComputerName : {ComputerName}
SqlInstance  : {SqlInstance}
InstanceName : {InstanceName}
Name         : Severity 017 - Insufficient Resources
Severity     : 17
MessageId    : 0

Name         : Error Number 823 - Read/Write Error
Severity     : 0
MessageId    : 823
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | 本コマンドは添付ファイルを出力しない |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| Category | アラートカテゴリ | パラメータ指定 | No |
| Database | 対象データベース | パラメータ指定 | No |
| Operator | 通知先オペレーター | パラメータ指定/自動検出 | No |
| OperatorEmail | 新規オペレーターのメールアドレス | パラメータ指定 | No |
| DelayBetweenResponses | 通知間隔（秒） | パラメータ指定 | No |
| Disabled | 無効状態で作成 | パラメータ指定 | No |
| EventDescriptionKeyword | イベント説明キーワード | パラメータ指定 | No |
| EventSource | イベントソース | パラメータ指定 | No |
| JobId | 応答ジョブID | パラメータ指定 | No |
| ExcludeSeverity | 除外する重大度 | パラメータ指定 | No |
| ExcludeMessageId | 除外するメッセージID | パラメータ指定 | No |
| NotificationMessage | カスタム通知メッセージ | パラメータ指定 | No |
| NotifyMethod | 通知方法 | パラメータ指定（デフォルトNotifyAll） | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コマンド実行 | Install-DbaAgentAdminAlert実行 | オペレーター存在または作成可能 | 標準アラートを一括作成 |
| パイプライン入力 | SqlInstanceのパイプ入力 | 複数インスタンス対応 | 複数サーバーに一括インストール |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 同名アラート存在 | 既存アラートがある場合はスキップ |
| オペレーター不存在 | 単一オペレーターでない場合はエラー |
| -WhatIf指定時 | 実際の作成は行わず、処理内容のみ表示 |
| ExcludeSeverity | 指定重大度をスキップ |
| ExcludeMessageId | 指定メッセージIDをスキップ |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コマンド実行開始] --> B[namehash初期化]
    B --> C[foreach instance in 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| L[オペレーター使用]
    J --> L
    G -->|No| M{オペレーター自動検出}
    M --> N{単一オペレーター?}
    N -->|No| O[Stop-Function: 複数/なし]
    O --> C
    N -->|Yes| L
    L --> P{Category指定?}
    P -->|Yes| Q{カテゴリ存在?}
    Q -->|No| R[New-DbaAgentAlertCategory]
    Q -->|Yes| S[カテゴリ使用]
    R --> S
    P -->|No| S
    S --> T[ExcludeSeverity/MessageId適用]
    T --> U[foreach item in namehash]
    U --> V{既存アラート?}
    V -->|Yes| W[Stop-Function: 既存]
    W --> U
    V -->|No| X[New-DbaAgentAlert]
    X --> Y[Get-DbaAgentAlert出力]
    Y --> Z{次のアラート?}
    Z -->|Yes| U
    Z -->|No| AA{次のインスタンス?}
    AA -->|Yes| C
    AA -->|No| AB[終了]
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| msdb.dbo.sysalerts | 既存アラートチェック | SMO経由 |
| msdb.dbo.sysoperators | オペレーター確認 | Get-DbaAgentOperator経由 |

### テーブル別参照項目詳細

#### msdb.dbo.sysalerts

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| name | 重複チェック | 作成前に同名存在確認 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| msdb.dbo.sysalerts | INSERT | 新規アラートの作成 |
| msdb.dbo.sysnotifications | INSERT | オペレーター通知設定の追加 |
| msdb.dbo.sysoperators | INSERT | 新規オペレーターの作成（OperatorEmail指定時） |
| msdb.dbo.syscategories | INSERT | 新規カテゴリの作成（Category指定時） |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 接続失敗 | SqlInstanceに接続不可 | Stop-Function -Continue |
| オペレーター未特定 | 複数または0個のオペレーター | Stop-Function -Continue |
| オペレーター作成失敗 | New-DbaAgentOperator失敗 | Stop-Function -Continue |
| カテゴリ作成失敗 | New-DbaAgentAlertCategory失敗 | Stop-Function -Continue |
| 既存アラート | 同名アラートが存在 | Stop-Function -Continue |
| アラート作成失敗 | New-DbaAgentAlert失敗 | Stop-Function -Continue |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（任意のタイミングで実行可能）

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

- sysadmin権限が必要
- SqlCredentialパラメータによりSQL Server認証、Windows認証、AD認証をサポート
- オペレーター作成時にメールアドレスが平文で渡される
- NotifyMethodでNotifyAllを指定すると全通知方法が有効化される

## 備考

- デフォルトで12個のアラート（Severity 17-25の9個 + MessageId 823-825の3個）を作成
- Operator未指定時は、インスタンスに1つだけオペレーターが存在すれば自動使用
- NotifyMethodのデフォルト値はNotifyAll
- Disabledスイッチで無効状態のアラートを作成可能
- ExcludeSeverity/ExcludeMessageIdで特定のアラートを除外可能
- New-DbaAgentAlertを内部で呼び出し

---

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

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

### 推奨読解順序

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

まず、作成されるアラートの名前定義（namehash）を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | 160-173行目: namehashでアラート名を定義 |
| 1-2 | Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | 97-130行目: .OUTPUTSセクションで出力プロパティを確認 |

**読解のコツ**: namehashは数値（Severity/MessageId）をキーとし、アラート名を値として持つ。823以上の数値はMessageId、それ未満はSeverityとして扱われる（325行目参照）。

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

処理の起点となるパラメータ定義を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | 138-158行目: パラメータ定義 |
| 2-2 | Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | 175-188行目: デフォルト表示プロパティ定義 |

**主要処理フロー**:
1. **143-146行目**: Category, Database, Operator, OperatorEmail - オプションパラメータ
2. **151-152行目**: ExcludeSeverity, ExcludeMessageId - 除外指定
3. **156行目**: NotifyMethod デフォルト値 "NotifyAll"

#### Step 3: オペレーターとカテゴリの事前準備を理解する

アラート作成前のオペレーター・カテゴリ処理を確認します。

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

**主要処理フロー**:
- **199-200行目**: オペレーター存在確認、OperatorEmail指定時は新規作成
- **254-265行目**: Operator未指定時、単一オペレーターを自動検出

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

namehashを使用したアラート一括作成処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | 307-317行目: ExcludeSeverity/ExcludeMessageId処理 |
| 4-2 | Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | 319-344行目: アラート作成ループ |

**主要処理フロー**:
- **308-316行目**: ExcludeSeverity/ExcludeMessageIdでnamehashから除外
- **319行目**: `foreach ($item in $namehash.Keys)` でループ
- **325-328行目**: 823未満ならSeverity、以上ならMessageIdに設定
- **337行目**: `New-DbaAgentAlert @parms` で作成
- **343行目**: `Get-DbaAgentAlert` で結果出力

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

```
Install-DbaAgentAdminAlert (エントリーポイント)
    |
    +-- [beginブロック]
    |       ├── namehash初期化（12アラート定義）
    |       └── defaults配列初期化
    |
    └── [processブロック]
            |
            └── foreach ($instance in $SqlInstance)
                    |
                    ├── Connect-DbaInstance
                    |
                    ├── オペレーター処理
                    |       ├── Get-DbaAgentOperator（存在確認）
                    |       └── New-DbaAgentOperator（作成）
                    |
                    ├── カテゴリ処理
                    |       ├── Get-DbaAgentAlertCategory（存在確認）
                    |       └── New-DbaAgentAlertCategory（作成）
                    |
                    ├── オペレーター自動検出（未指定時）
                    |
                    ├── パラメータ構築（$parms）
                    |
                    ├── ExcludeSeverity/ExcludeMessageId適用
                    |
                    └── foreach ($item in $namehash.Keys)
                            |
                            ├── Severity/MessageId判定
                            ├── 既存アラートチェック
                            ├── New-DbaAgentAlert
                            └── Get-DbaAgentAlert + Select-DefaultView
```

### データフロー図

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

SqlInstance ──────────┐
SqlCredential ────────┤
Category ─────────────┤
Database ─────────────┤
Operator ─────────────┼──▶ Connect-DbaInstance ──▶ $server
OperatorEmail ────────┤                               │
DelayBetweenResponses─┤                               ▼
Disabled ─────────────┤                    オペレーター/カテゴリ処理
ExcludeSeverity ──────┤                               │
ExcludeMessageId ─────┤                               ▼
NotificationMessage ──┤                    $parms構築
NotifyMethod ─────────┘                               │
                                                      ▼
                                           namehash.Keys ループ
                                                      │
                                           ┌──────────┼──────────┐
                                           ▼          ▼          ▼
                                      Severity判定  既存チェック  New-DbaAgentAlert
                                           │          │          │
                                           └──────────┼──────────┘
                                                      ▼
                                           Get-DbaAgentAlert
                                                      │
                                                      ▼
                                Microsoft.SqlServer.Management.Smo.Agent.Alert
                                (12アラート分の出力)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaAgentAdminAlert.ps1 | `public/Install-DbaAgentAdminAlert.ps1` | ソース | メインコマンド実装 |
| New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | ソース | アラート作成（内部呼び出し） |
| Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | ソース | アラート取得（結果出力） |
| Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | ソース | オペレーター取得 |
| New-DbaAgentOperator.ps1 | `public/New-DbaAgentOperator.ps1` | ソース | オペレーター作成 |
| Get-DbaAgentAlertCategory.ps1 | `public/Get-DbaAgentAlertCategory.ps1` | ソース | カテゴリ取得 |
| New-DbaAgentAlertCategory.ps1 | `public/New-DbaAgentAlertCategory.ps1` | ソース | カテゴリ作成 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ユーティリティ |
