# 画面設計書 12-Agentアラート管理

## 概要

本ドキュメントは、SQL Server Agent アラートの作成・取得・設定・削除・コピー機能を提供するコマンド群の設計仕様を記述したものです。

### 本画面の処理概要

本機能は、SQL Server Agent のアラート設定を管理し、エラー、パフォーマンス状態、システムイベントに対する自動監視と通知を構成します。アラートは特定のエラー重大度、メッセージID、パフォーマンス条件、WMIイベントを監視し、オペレーターへの通知やジョブの自動実行をトリガーできます。

**業務上の目的・背景**：SQL Server の重大なエラーやパフォーマンス問題を自動検出し、DBA やオペレーターに即座に通知することで、障害対応時間を短縮し、システムの可用性を向上させます。手動での SQL Server Management Studio 操作の代わりに、複数サーバーに対して一括でアラート設定を展開・監査できます。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Get-DbaAgentAlert` - アラート設定の取得
- `New-DbaAgentAlert` - アラートの新規作成
- `Set-DbaAgentAlert` - アラートの設定変更
- `Remove-DbaAgentAlert` - アラートの削除
- `Copy-DbaAgentAlert` - アラートのインスタンス間コピー

**主要な操作・処理内容**：
1. SQL Server インスタンスからアラート設定一覧を取得し、構成を監査
2. 新規アラートの作成（重大度、メッセージID、パフォーマンス条件、WMIイベント）
3. 既存アラートの有効化・無効化・リネーム
4. 不要なアラートの削除
5. ソースサーバーから宛先サーバーへのアラート設定の移行

**画面遷移**：本機能はCLIコマンドであり、他のコマンドとパイプライン連携が可能です。
- `Get-DbaAgentAlert` から `Set-DbaAgentAlert` または `Remove-DbaAgentAlert` へパイプライン連携可能
- `Copy-DbaAgentOperator` と連携してオペレーターも含めた移行が可能

**権限による表示制御**：SQLAgentOperatorRole または sysadmin 権限が必要です。Express Edition では SQL Agent が存在しないため、エラーメッセージが表示されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 483 | Get-DbaAgentAlert | 主機能 | SQLエージェントアラートの取得 |
| 496 | New-DbaAgentAlert | 主機能 | SQLエージェントアラートの新規作成 |
| 504 | Remove-DbaAgentAlert | 主機能 | SQLエージェントアラートの削除 |
| 512 | Set-DbaAgentAlert | 補助機能 | SQLエージェントアラートのプロパティ変更 |
| 474 | Copy-DbaAgentAlert | 補助機能 | SQLエージェントアラートのコピー |
| 484 | Get-DbaAgentAlertCategory | 補助機能 | アラートカテゴリの取得 |
| 497 | New-DbaAgentAlertCategory | 補助機能 | アラートカテゴリの新規作成 |
| 505 | Remove-DbaAgentAlertCategory | 補助機能 | アラートカテゴリの削除 |
| 495 | Install-DbaAgentAdminAlert | 補助機能 | 標準システムアラートのインストール |

## 画面種別

一覧 / 登録 / 編集 / 削除

## URL/ルーティング

PowerShell コマンドとして提供（CLIベース）
- `Get-DbaAgentAlert`
- `New-DbaAgentAlert`
- `Set-DbaAgentAlert`
- `Remove-DbaAgentAlert`
- `Copy-DbaAgentAlert`

## 入出力項目

### Get-DbaAgentAlert パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Alert | string[] | No | 取得するアラート名（ワイルドカード対応） |
| ExcludeAlert | string[] | No | 除外するアラート名 |
| EnableException | switch | No | 例外を有効化 |

### New-DbaAgentAlert パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Alert | string | Yes | アラート名 |
| Category | string | No | カテゴリ名 |
| Database | string | No | 対象データベース |
| Operator | string[] | No | 通知オペレーター |
| DelayBetweenResponses | int | No | 通知間隔（秒）、デフォルト60 |
| Disabled | switch | No | 無効状態で作成 |
| EventDescriptionKeyword | string | No | イベント説明キーワード |
| EventSource | string | No | イベントソース（WMI用） |
| JobId | string | No | 実行ジョブのGUID |
| Severity | int | No | エラー重大度（0-25） |
| MessageId | int | No | メッセージID |
| NotificationMessage | string | No | 通知メッセージ |
| PerformanceCondition | string | No | パフォーマンス条件 |
| WmiEventNamespace | string | No | WMI名前空間 |
| WmiEventQuery | string | No | WMIクエリ |
| NotifyMethod | ValidateSet | No | 通知方法（None/NotifyEmail/Pager/NetSend/NotifyAll） |
| EnableException | switch | No | 例外を有効化 |

### Set-DbaAgentAlert パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Alert | object[] | No | アラート名 |
| NewName | string | No | 新しいアラート名 |
| Enabled | switch | No | アラートを有効化 |
| Disabled | switch | No | アラートを無効化 |
| Force | switch | No | 確認をスキップ |
| InputObject | Alert[] | No | パイプライン入力 |
| EnableException | switch | No | 例外を有効化 |

### Remove-DbaAgentAlert パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Alert | string[] | No | 削除するアラート名 |
| ExcludeAlert | string[] | No | 除外するアラート名 |
| InputObject | Alert[] | No | パイプライン入力 |
| EnableException | switch | No | 例外を有効化 |

### Copy-DbaAgentAlert パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Source | DbaInstanceParameter | Yes | コピー元インスタンス |
| SourceSqlCredential | PSCredential | No | コピー元認証情報 |
| Destination | DbaInstanceParameter[] | Yes | コピー先インスタンス |
| DestinationSqlCredential | PSCredential | No | コピー先認証情報 |
| Alert | object[] | No | コピーするアラート名 |
| ExcludeAlert | object[] | No | 除外するアラート名 |
| IncludeDefaults | switch | No | アラートデフォルト設定も含める |
| Force | switch | No | 既存アラートを上書き |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Get-DbaAgentAlert 出力

| 項目名 | 説明 |
|--------|------|
| ComputerName | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | SQL Serverインスタンス名 |
| SqlInstance | 完全なSQL Serverインスタンス名 |
| Name | アラート名 |
| ID | アラートID |
| JobName | 応答ジョブ名 |
| AlertType | アラートタイプ（EventAlert/ErrorNumberAlert等） |
| CategoryName | カテゴリ名 |
| Severity | エラー重大度（0-25） |
| MessageId | メッセージID |
| IsEnabled | 有効/無効 |
| DelayBetweenResponses | 通知間隔（秒） |
| LastRaised | 最終発生日時 |
| OccurrenceCount | 発生回数 |
| Notifications | 通知設定（DataTable） |

### Remove-DbaAgentAlert 出力

| 項目名 | 説明 |
|--------|------|
| ComputerName | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | SQL Serverインスタンス名 |
| SqlInstance | 完全なSQL Serverインスタンス名 |
| Name | 削除されたアラート名 |
| Status | 操作結果（Dropped/エラーメッセージ） |
| IsRemoved | 削除成功フラグ |

### Copy-DbaAgentAlert 出力

| 項目名 | 説明 |
|--------|------|
| SourceServer | コピー元サーバー名 |
| DestinationServer | コピー先サーバー名 |
| Name | アラート名 |
| Type | オブジェクトタイプ（Agent Alert/Job Association/Notification） |
| Status | 操作結果（Successful/Failed/Skipped） |
| Notes | 追加情報 |
| DateTime | 操作日時 |

## イベント仕様

### 1-アラート取得

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. Express Editionチェック（Express EditionにはSQL Agentが存在しない）
3. `$server.Jobserver.Alerts` からアラート一覧を取得
4. `-Alert` および `-ExcludeAlert` パラメータでフィルタリング
5. 各アラートに `EnumNotifications()` で通知設定を追加
6. `Select-DefaultView` で整形して出力

### 2-アラート作成

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. 既存アラート名との重複チェック
3. `New-Object Microsoft.SqlServer.Management.Smo.Agent.Alert` でアラートオブジェクト作成
4. Severity、MessageId、PerformanceCondition、WMIイベント等のプロパティ設定
5. `$newalert.Create()` でアラートを作成
6. オペレーター指定時は `AddNotification()` で通知設定を追加
7. `$newalert.Alter()` で変更をコミット
8. 作成されたアラートを `Get-DbaAgentAlert` で取得して返却

### 3-アラート設定変更

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. 対象アラートの存在確認
3. `$InputObject` または `$server.JobServer.Alerts[$a]` でアラートオブジェクト取得
4. `-NewName` 指定時は `$currentAlert.Rename()` を実行
5. `-Enabled/-Disabled` で `IsEnabled` プロパティを変更
6. `$currentAlert.Alter()` で変更をコミット
7. 変更後のアラートを返却

### 4-アラート削除

**処理フロー**:
1. `Get-DbaAgentAlert` でアラートオブジェクトを取得（または `InputObject` から）
2. `end` ブロックで削除処理（コレクション変更エラー防止）
3. `$dbAlert.Drop()` でアラートを削除
4. 結果オブジェクト（Status、IsRemoved）を出力

### 5-アラートコピー

**処理フロー**:
1. ソースサーバーから `$sourceServer.JobServer.Alerts` を取得
2. 各宛先サーバーに対してループ処理
3. `-IncludeDefaults` 時は `AlertSystem.Script()` でデフォルト設定をコピー
4. オペレーター存在チェック（不足時はスキップ）
5. 既存アラートチェック（`-Force` で上書き可能）
6. 競合チェック（同じSeverity/MessageId/Database/Keyword）
7. ジョブ関連付けチェック（ジョブが宛先に存在するか）
8. `$serverAlert.Script()` でSQLスクリプト生成・実行
9. 通知設定を `AddNotification()` で再構成

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaAgentAlert | msdb.dbo.sysalerts | SELECT | アラート設定の取得 |
| New-DbaAgentAlert | msdb.dbo.sysalerts | INSERT | アラートの新規作成 |
| Set-DbaAgentAlert | msdb.dbo.sysalerts | UPDATE | アラート設定の更新 |
| Remove-DbaAgentAlert | msdb.dbo.sysalerts | DELETE | アラートの削除 |
| Copy-DbaAgentAlert | msdb.dbo.sysalerts | INSERT | アラートのコピー先への作成 |

### テーブル別更新項目詳細

#### msdb.dbo.sysalerts

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | ユーザー指定のアラート名 | 一意制約あり |
| INSERT | severity | 0-25の重大度レベル | MessageIdと排他 |
| INSERT | message_id | SQL Serverメッセージ番号 | Severityと排他 |
| INSERT | enabled | 1（有効）/ 0（無効） | |
| INSERT | delay_between_responses | 通知間隔（秒） | デフォルト60 |
| UPDATE | enabled | -Enabled/-Disabled による変更 | |
| UPDATE | name | -NewName による変更 | |
| DELETE | - | Drop() による行削除 | |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| Error | Express Edition | "There is no SQL Agent on $server, it's a $($server.Edition)" |
| Error | アラート既存 | "Alert '$name' already exists on $instance" |
| Error | AG Listener経由 | "Cannot create agent alert through a contained availability group listener..." |
| Error | アラート不存在 | "Alert $a doesn't exists on $instance" |
| Warning | オペレーター不存在（Copy時） | "One or more operators alerted by [$alertName] is not present at the destination..." |
| Verbose | 競合検出（Copy時） | "Alert [$alertName] has already been defined to use..." |
| Info | 既存スキップ | "Alert [$alertName] exists at destination. Use -Force to drop and migrate." |

## 例外処理

| 例外条件 | 対応 |
|---------|------|
| SQL Serverインスタンスへの接続失敗 | Stop-Function でエラー出力し、次のインスタンスへ継続 |
| Express Editionへの接続 | Stop-Function で警告出力し、処理継続 |
| アラート名の重複 | Stop-Function でエラー出力し、処理継続 |
| AG Listener経由での作成 | Stop-Function でエラー出力し、プライマリレプリカへの接続を推奨 |
| 通知追加失敗 | Stop-Function でエラー出力し、処理継続 |
| 削除失敗 | Status に エラーメッセージを設定、IsRemoved = false |

## 備考

- Pager および NetSend オプションは将来の SQL Server バージョンで非推奨となる予定
- アラートには Severity、MessageId、PerformanceCondition、WmiEventQuery のいずれかを指定する必要がある
- AG Listener 経由ではアラート作成不可（インスタンスレベルのオブジェクトのため）
- Copy-DbaAgentAlert ではジョブIDが `00000000-0000-0000-0000-000000000000` に置換される

---

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

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

### 推奨読解順序

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

SMO の Alert クラス構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 43-76行: .OUTPUTS セクションでSMO Alertオブジェクト構造を確認 |

**読解のコツ**: `Microsoft.SqlServer.Management.Smo.Agent.Alert` クラスのプロパティと `EnumNotifications()` メソッドの戻り値を理解する。

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

各コマンドのパラメータ処理と前処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 93-101行: パラメータ定義 |
| 2-2 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 114-116行: Express Editionチェック |

**主要処理フロー**:
1. **106行**: `Connect-DbaInstance` でサーバー接続
2. **114-116行**: Express Edition の場合は SQL Agent が存在しないためエラー
3. **120行**: `$server.Jobserver.Alerts` でアラートコレクション取得

#### Step 3: アラート作成ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 161-185行: パラメータ定義 |
| 3-2 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 199-201行: MessageId/Severity排他ロジック |
| 3-3 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 217-237行: SMOオブジェクト作成とプロパティ設定 |

**主要処理フロー**:
- **218行**: `New-Object Microsoft.SqlServer.Management.Smo.Agent.Alert` でオブジェクト生成
- **227-235行**: プロパティリストをループして値を設定
- **237行**: `$newalert.Create()` で SQL Server に作成
- **239-248行**: オペレーター通知の設定

#### Step 4: コピー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Copy-DbaAgentAlert.ps1 | `public/Copy-DbaAgentAlert.ps1` | 115-124行: begin ブロックでソース接続 |
| 4-2 | Copy-DbaAgentAlert.ps1 | `public/Copy-DbaAgentAlert.ps1` | 180-195行: オペレーター存在チェック |
| 4-3 | Copy-DbaAgentAlert.ps1 | `public/Copy-DbaAgentAlert.ps1` | 249-265行: Script() によるSQLスクリプト生成と実行 |

**主要処理フロー**:
- **148行**: `$sourceServer.JobServer.AlertSystem.Script()` でデフォルト設定スクリプト生成
- **252行**: `$serverAlert.Script()` でアラートスクリプト生成
- **253行**: JobId プレースホルダー置換（後で正しいIDに更新）
- **320-338行**: 通知メソッドの再構成

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

```
Get-DbaAgentAlert
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- Express Editionチェック
    |
    +-- $server.Jobserver.Alerts (アラート一覧取得)
    |
    +-- Filter: -Alert, -ExcludeAlert
    |
    +-- $alrt.EnumNotifications() (通知設定取得)
    |
    +-- Select-DefaultView (出力整形)

New-DbaAgentAlert
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- 重複チェック
    |
    +-- New-Object Alert (SMOオブジェクト作成)
    |
    +-- プロパティ設定
    |
    +-- $newalert.Create() (作成)
    |
    +-- $newalert.AddNotification() (通知設定)
    |
    +-- $newalert.Alter() (変更確定)
    |
    +-- Get-DbaAgentAlert (結果取得)

Copy-DbaAgentAlert
    |
    +-- Connect-DbaInstance (Source)
    |
    +-- Connect-DbaInstance (Destination)
    |
    +-- [IncludeDefaults]
    |       +-- AlertSystem.Script() (デフォルト設定)
    |
    +-- オペレーター存在チェック
    |
    +-- 既存アラートチェック
    |       +-- [Force] Drop既存アラート
    |
    +-- 競合チェック (Severity/MessageId/Database)
    |
    +-- ジョブ関連付けチェック
    |
    +-- $serverAlert.Script() (SQLスクリプト生成)
    |
    +-- $destServer.Query($sql) (実行)
    |
    +-- $newAlert.AddNotification() (通知設定)
```

### データフロー図

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

SqlInstance ────────> Connect-DbaInstance ─────────> SMO Server Object
                            |
                      Edition チェック
                            |
Alert/ExcludeAlert ──> フィルタリング ───────────────> Alert Objects
                            |
                      EnumNotifications()
                            |
                      Add-Member (カスタムプロパティ)
                            |
                      Select-DefaultView ────────────> [出力オブジェクト]
                                                        - ComputerName
                                                        - Name
                                                        - AlertType
                                                        - Severity
                                                        - IsEnabled
                                                        - Notifications
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | ソース | アラート取得のメインコマンド |
| New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | ソース | アラート作成コマンド |
| Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | ソース | アラート設定変更コマンド |
| Remove-DbaAgentAlert.ps1 | `public/Remove-DbaAgentAlert.ps1` | ソース | アラート削除コマンド |
| Copy-DbaAgentAlert.ps1 | `public/Copy-DbaAgentAlert.ps1` | ソース | アラートコピーコマンド |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続管理 |
| Select-DefaultView.ps1 | `internal/functions/Select-DefaultView.ps1` | ソース | 出力整形ユーティリティ |
