# 機能設計書 483-Get-DbaAgentAlert

## 概要

本ドキュメントは、SQL Server Agent のアラート構成情報を取得する Get-DbaAgentAlert 関数の機能設計書である。

### 本機能の処理概要

Get-DbaAgentAlert は、1つ以上の SQL Server インスタンスから SQL Server Agent アラートの構成情報を取得する機能を提供する。アラート名、種別、重大度レベル、メッセージID、通知設定などの詳細情報を返す。

**業務上の目的・背景**：SQL Server Agent のアラートは、データベースエンジンからの重要なイベント（エラー、パフォーマンス条件、WMIイベント）に対して自動的に応答するための重要なコンポーネントである。複数サーバーにわたるアラート構成を監査し、欠落または誤設定されたアラートをトラブルシューティングし、コンプライアンスレポートのための情報収集を行う必要がある。

**機能の利用シーン**：
- 複数サーバー間でのアラート構成の監査
- 重大度別アラートの設定確認
- 未設定または無効化されたアラートの特定
- コンプライアンスレポートの作成
- アラート発生履歴の確認

**主要な処理内容**：
1. 指定されたインスタンスへの接続
2. Express Edition チェック（SQL Agent なし）
3. アラート一覧の取得
4. Alert/ExcludeAlert パラメータによるフィルタリング
5. カスタムプロパティの追加（Notifications, LastRaised）
6. 結果の出力

**関連システム・外部連携**：SQL Server Agent の Alerts コレクションを SMO (SQL Server Management Objects) 経由で取得。アラートに関連付けられたジョブやオペレーターの情報も取得可能。

**権限による制御**：msdb データベースへの読み取りアクセスが必要。Express Edition では SQL Agent が存在しないため、エラーを返す。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | Agentアラート管理 | 主機能 | SQLエージェントアラートの取得 |

## 機能種別

データ取得 / 監査・レポーティング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可 |
| SqlCredential | PSCredential | No | 認証用資格情報 | Windows/SQL認証対応 |
| Alert | string[] | No | 取得するアラート名（ワイルドカード対応） | - |
| ExcludeAlert | string[] | No | 除外するアラート名（ワイルドカード対応） | - |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

SMO を介した SQL Server インスタンスの JobServer.Alerts コレクションから取得。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverのコンピュータ名 |
| SqlInstance | String | 完全なインスタンス名 |
| InstanceName | String | SQL Serverインスタンス名 |
| Name | String | アラート名 |
| ID | Int | アラートID |
| JobName | String | 関連付けられたジョブ名 |
| AlertType | String | アラート種別（EventAlert, ErrorNumberAlert等） |
| CategoryName | String | アラートカテゴリ |
| Severity | Int | 重大度レベル（0-25） |
| MessageId | Int | トリガーとなるメッセージID |
| IsEnabled | Boolean | アラートの有効/無効状態 |
| DelayBetweenResponses | Int | 応答間の遅延秒数 |
| LastRaised | DbaDateTime | 最終発生日時 |
| OccurrenceCount | Int | 発生回数 |
| Notifications | DataTable | 通知先オペレーターと通知方法 |

### 出力先

パイプライン出力として Microsoft.SqlServer.Management.Smo.Alert オブジェクトを返す。

## 処理フロー

### 処理シーケンス

```
1. 各インスタンスに対してループ処理
   └─ Connect-DbaInstance で接続
   └─ 接続失敗時は Continue で次へ

2. Express Edition チェック
   └─ Edition が 'Express*' の場合はエラー
   └─ SQL Agent が存在しないため処理をスキップ

3. アラート一覧の取得
   └─ $server.Jobserver.Alerts から取得

4. フィルタリング処理
   └─ Alert パラメータ: ワイルドカードで名前フィルタ
   └─ ExcludeAlert パラメータ: ワイルドカードで除外

5. カスタムプロパティの追加
   └─ ComputerName, InstanceName, SqlInstance
   └─ Notifications: EnumNotifications() の結果
   └─ LastRaised: LastOccurrenceDate を DbaDateTime に変換

6. 結果の出力
   └─ Select-DefaultView で表示プロパティ設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[インスタンスループ開始]
    B --> C[インスタンス接続]
    C --> D{接続成功?}
    D -->|No| B
    D -->|Yes| E{Express Edition?}
    E -->|Yes| F[エラー: SQL Agentなし]
    F --> B
    E -->|No| G[Alerts取得]
    G --> H{Alert指定?}
    H -->|Yes| I[名前でフィルタ]
    H -->|No| J{ExcludeAlert指定?}
    I --> J
    J -->|Yes| K[除外フィルタ適用]
    J -->|No| L[アラートループ]
    K --> L
    L --> M[カスタムプロパティ追加]
    M --> N[Select-DefaultView]
    N --> O[結果出力]
    O --> P{次のアラート?}
    P -->|Yes| L
    P -->|No| Q{次のインスタンス?}
    Q -->|Yes| B
    Q -->|No| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Express除外 | Express Editionはサポート対象外 | Edition確認時 |
| BR-002 | ワイルドカード対応 | Alert/ExcludeAlertはワイルドカードをサポート | パラメータ指定時 |
| BR-003 | 最終発生日変換 | LastOccurrenceDate を DbaDateTime に変換 | 常時 |

### 計算ロジック

特になし。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| アラート取得 | msdb.dbo.sysalerts | SELECT | アラート一覧の取得（SMO経由） |
| 通知取得 | msdb.dbo.sysnotifications | SELECT | EnumNotifications()による取得 |

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

本機能は読み取り専用であり、データベースへの書き込みは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンス接続失敗 | Continue で次のインスタンスへ |
| ExpressEdition | エディションエラー | Express Editionを検出 | Stop-Function で警告出力、Continue |

### リトライ仕様

特になし。

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

読み取り専用のため、トランザクション制御は不要。

## パフォーマンス要件

- アラート数に依存するが、通常は少数のため問題なし
- EnumNotifications() の呼び出しが各アラートに対して実行される

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

- msdb データベースへの読み取りアクセスが必要
- SQL 認証を使用する場合、資格情報は PSCredential オブジェクトとして安全に渡される

## 備考

- Express Edition では SQL Agent が存在しないため、エラーメッセージを表示してスキップ
- LastRaised プロパティは LastOccurrenceDate から派生したカスタムプロパティ
- Notifications プロパティは EnumNotifications() メソッドで取得した DataTable

---

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

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

### 推奨読解順序

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

パラメータ定義と出力プロパティの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 93-101行目: パラメータ定義 |
| 1-2 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 43-75行目: .OUTPUTS ドキュメント |

**読解のコツ**: Alert/ExcludeAlert パラメータがワイルドカード対応であること、出力の Notifications と LastRaised がカスタムプロパティであることに注目。

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

処理の起点となる process ブロックを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 103-150行目: processブロック全体 |

**主要処理フロー**:
1. **104-109行目**: インスタンスへの接続
2. **111-116行目**: Edition確認とExpress除外
3. **118行目**: デフォルト表示プロパティの定義
4. **120行目**: Alerts コレクションの取得

#### Step 3: フィルタリングとプロパティ追加を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 122-136行目: Alert/ExcludeAlertフィルタ |
| 3-2 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 138-148行目: カスタムプロパティ追加 |

**主要処理フロー**:
- **122-130行目**: Alert パラメータによるフィルタ（ワイルドカード: -like）
- **132-136行目**: ExcludeAlert パラメータによる除外（-notlike）
- **139行目**: LastOccurrenceDate を DbaDateTime に変換
- **144行目**: EnumNotifications() で通知情報を取得
- **145行目**: LastRaised カスタムプロパティを追加

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

```
Get-DbaAgentAlert
    │
    └─ [process] foreach ($instance in $SqlInstance)
           │
           ├─ Connect-DbaInstance
           │      └─ インスタンス接続
           │
           ├─ Edition チェック
           │      └─ Express の場合は Stop-Function
           │
           ├─ $server.Jobserver.Alerts
           │      └─ アラートコレクション取得
           │
           ├─ Where-Object フィルタ
           │      ├─ Alert: -like でフィルタ
           │      └─ ExcludeAlert: -notlike で除外
           │
           ├─ foreach ($alrt in $alerts)
           │      ├─ [dbadatetime]$alrt.LastOccurrenceDate
           │      ├─ Add-Member (ComputerName, InstanceName, SqlInstance)
           │      ├─ Add-Member (Notifications: EnumNotifications())
           │      └─ Add-Member (LastRaised)
           │
           └─ Select-DefaultView
                  └─ 表示プロパティ設定
```

### データフロー図

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

SqlInstance ─────────────────▶ Connect-DbaInstance ─────────────▶ SMO Server
                                │
                                ▼
                          Edition チェック
                                │
                                ▼
Alert/ExcludeAlert ──────────▶ $server.Jobserver.Alerts ────────▶ Alert[]
                                │
                                ▼
                          Where-Object フィルタ
                                │
                                ▼
                          Add-Member
                          - Notifications (EnumNotifications())
                          - LastRaised (DbaDateTime)
                                │
                                ▼
                          Select-DefaultView ─────────────────────▶ Alert Objects
                                                                    - Name
                                                                    - AlertType
                                                                    - Severity
                                                                    - IsEnabled
                                                                    - LastRaised
                                                                    - Notifications
                                                                    ...
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | ソース | 関連機能（アラート作成） |
| Remove-DbaAgentAlert.ps1 | `public/Remove-DbaAgentAlert.ps1` | ソース | 関連機能（アラート削除） |
| Copy-DbaAgentAlert.ps1 | `public/Copy-DbaAgentAlert.ps1` | ソース | 関連機能（アラートコピー） |
