# 通知設計書 13-Get-DbaAgentAlert

## 概要

本ドキュメントは、SQL ServerエージェントのアラートSQL設定を取得するdbatools PowerShellコマンド「Get-DbaAgentAlert」の設計仕様を記載します。

### 本通知の処理概要

Get-DbaAgentAlertは、SQL Server Agentに設定されたアラートの構成情報を取得するコマンドです。アラートはSQL Serverのエラー監視・通知システムの中核を成し、特定の重大度レベル、メッセージID、パフォーマンス条件、WMIイベントを監視して自動通知を行います。

**業務上の目的・背景**：DBAは複数のSQL Serverインスタンスにまたがるアラート設定を監査・確認する必要があります。コンプライアンス報告、トラブルシューティング、設定の標準化などにおいて、現在のアラート構成を一括で把握することは不可欠です。本コマンドは、アラートの有効/無効状態、最終発生日時、発生回数などの詳細情報を提供します。

**通知の送信タイミング**：本コマンドは「アラート設定情報を取得する」参照系コマンドであり、通知を送信しません。管理者がコマンドを実行した時点で即座に設定情報が返されます。

**通知の受信者**：本コマンドの実行結果はコマンド実行者（DBA、システム管理者）に返されます。取得されたアラート情報はSMO Alertオブジェクトとして出力されます。

**通知内容の概要**：アラートの名前、ID、種別、重大度レベル、メッセージID、有効状態、最終発生日時、発生回数、関連するジョブ名、通知設定などの情報が返されます。

**期待されるアクション**：管理者は取得したアラート情報を基に、設定の妥当性確認、不足しているアラートの特定、他サーバーへの設定コピー（Copy-DbaAgentAlert）などのアクションを行います。

## 通知種別

PowerShellコンソール出力 / パイプライン出力（Microsoft.SqlServer.Management.Smo.Agent.Alert）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（コマンド実行と同時に結果出力） |
| 優先度 | 低（参照系コマンド、ConfirmImpact未設定） |
| リトライ | 無（失敗時はエラーメッセージ出力） |

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

- SqlInstanceパラメータ：取得対象のSQL Serverインスタンスを指定
- Alertパラメータ：特定のアラート名を指定してフィルタリング（ワイルドカード対応）
- ExcludeAlertパラメータ：除外するアラート名を指定（ワイルドカード対応）

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力形式 | Microsoft.SqlServer.Management.Smo.Agent.Alert（カスタムプロパティ追加） |
| デフォルト表示 | Select-DefaultViewによる主要プロパティ表示 |

### 本文テンプレート

```
デフォルト表示プロパティ:
ComputerName         : {ComputerName}
SqlInstance          : {SqlInstance}
InstanceName         : {InstanceName}
Name                 : {AlertName}
ID                   : {AlertID}
JobName              : {JobName}
AlertType            : {AlertType}
CategoryName         : {CategoryName}
Severity             : {Severity}
MessageId            : {MessageId}
IsEnabled            : {True/False}
DelayBetweenResponses: {Seconds}
LastRaised           : {DateTime}
OccurrenceCount      : {Count}
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| ComputerName | SQL Serverのコンピュータ名 | $server.ComputerName | Yes |
| InstanceName | SQL Serverのインスタンス名 | $server.ServiceName | Yes |
| SqlInstance | 完全修飾インスタンス名 | $server.DomainInstanceName | Yes |
| Name | アラート名 | $alrt.Name | Yes |
| ID | アラートID | $alrt.ID | Yes |
| JobName | 応答ジョブ名 | $alrt.JobName | No |
| AlertType | アラート種別 | $alrt.AlertType | Yes |
| CategoryName | カテゴリ名 | $alrt.CategoryName | No |
| Severity | 重大度レベル（0-25） | $alrt.Severity | Yes |
| MessageId | メッセージID | $alrt.MessageID | Yes |
| IsEnabled | 有効/無効状態 | $alrt.IsEnabled | Yes |
| DelayBetweenResponses | 応答間隔（秒） | $alrt.DelayBetweenResponses | Yes |
| LastRaised | 最終発生日時 | $alrt.LastOccurrenceDate（dbadatetime変換） | Yes |
| OccurrenceCount | 発生回数 | $alrt.OccurrenceCount | Yes |
| Notifications | 通知設定 | $alrt.EnumNotifications() | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コマンド実行 | Get-DbaAgentAlert実行 | SqlInstanceに接続可能 | 指定インスタンスからアラート情報を取得 |
| パイプライン入力 | SqlInstanceのパイプ入力 | 複数インスタンス指定 | 複数サーバーから一括取得 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| Express Edition | SQL Server Express Editionの場合はSQL Agentなしのため停止 |
| 接続失敗 | SqlInstanceへの接続失敗時はエラー出力して継続 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コマンド実行開始] --> B[foreach instance in SqlInstance]
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function: 接続エラー]
    E --> B
    D -->|Yes| F{Express Edition?}
    F -->|Yes| G[Stop-Function: Agent未サポート]
    G --> B
    F -->|No| H[JobServer.Alertsコレクション取得]
    H --> I{Alert指定あり?}
    I -->|Yes| J[名前でフィルタリング]
    I -->|No| K[全アラート対象]
    J --> L{ExcludeAlert指定あり?}
    K --> L
    L -->|Yes| M[除外フィルタ適用]
    L -->|No| N[foreach alert in alerts]
    M --> N
    N --> O[カスタムプロパティ追加]
    O --> P[Select-DefaultView出力]
    P --> Q{次のアラート?}
    Q -->|Yes| N
    Q -->|No| R{次のインスタンス?}
    R -->|Yes| B
    R -->|No| S[終了]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| msdb.dbo.sysalerts | アラート構成情報 | SMO JobServer.Alerts経由 |
| msdb.dbo.syscategories | アラートカテゴリ | CategoryNameの取得 |
| msdb.dbo.sysoperators | オペレーター情報 | EnumNotifications()で参照 |
| msdb.dbo.sysnotifications | 通知設定 | EnumNotifications()で参照 |

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

#### msdb.dbo.sysalerts

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| id | アラートID | SMO経由で全アラート |
| name | アラート名 | Alertパラメータでフィルタ |
| enabled | 有効フラグ | IsEnabledプロパティ |
| message_id | メッセージID | MessageIdプロパティ |
| severity | 重大度 | Severityプロパティ |
| delay_between_responses | 応答間隔 | DelayBetweenResponsesプロパティ |
| last_occurrence_date | 最終発生日 | LastRaisedカスタムプロパティ |
| occurrence_count | 発生回数 | OccurrenceCountプロパティ |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | 本コマンドは参照専用 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 接続失敗 | SqlInstanceに接続不可 | Stop-Function -Continue で次インスタンスへ |
| Express Edition | SQL Agent未サポート | Stop-Function -Continue で次インスタンスへ |
| 権限不足 | sysadmin権限なし | SMOからエラー返却 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

- sysadmin権限またはSQLAgentReaderRole以上の権限が必要
- SqlCredentialパラメータによりSQL Server認証、Windows認証、AD認証をサポート
- 参照専用コマンドのため、データ変更リスクなし
- 機密情報（パスワード等）は出力に含まれない

## 備考

- Express EditionではSQL Server Agentが利用不可のため、明示的にエラーメッセージを出力
- LastRaisedプロパティはdbatools独自のdbadatetime型に変換して出力
- Notificationsプロパティは EnumNotifications() DataTableを含み、通知設定の詳細を提供
- 他のdbatools Agent系コマンド（Copy-DbaAgentAlert, Remove-DbaAgentAlertなど）とパイプラインで連携可能

---

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

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

### 推奨読解順序

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

まず、出力されるAlertオブジェクトの構造と追加されるカスタムプロパティを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 44-75行目: .OUTPUTSセクションで出力プロパティを確認 |
| 1-2 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 118行目: デフォルト表示プロパティの定義 |

**読解のコツ**: `Microsoft.SqlServer.Management.Smo.Agent.Alert`型がSMOのアラートオブジェクトであり、カスタムプロパティ（ComputerName, InstanceName, SqlInstance, Notifications, LastRaised）が動的に追加されることを理解する。

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

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

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

**主要処理フロー**:
1. **95行目**: `[parameter(Mandatory, ValueFromPipeline)]` - SqlInstanceは必須でパイプライン入力対応
2. **98-99行目**: Alert/ExcludeAlertパラメータでフィルタリング

#### Step 3: 接続とEditionチェックを理解する

SQL Server接続とExpress Editionの除外処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 104-116行目: 接続とEditionチェック |

**主要処理フロー**:
- **105-108行目**: Connect-DbaInstanceによる接続とエラーハンドリング
- **111-115行目**: Express Editionチェックと除外処理

#### Step 4: アラート取得とフィルタリングを理解する

実際のアラート取得とワイルドカードフィルタリングを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 120-136行目: フィルタリング処理 |

**主要処理フロー**:
- **120行目**: `$server.Jobserver.Alerts` - SMOからアラートコレクション取得
- **122-130行目**: Alertパラメータによるワイルドカードフィルタ
- **132-136行目**: ExcludeAlertパラメータによる除外フィルタ

#### Step 5: カスタムプロパティ追加と出力を理解する

出力オブジェクトの拡張処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | 138-148行目: プロパティ追加と出力 |

**主要処理フロー**:
- **139行目**: LastOccurrenceDate を dbadatetime に変換
- **141-145行目**: Add-Member でカスタムプロパティ追加
- **147行目**: Select-DefaultView で表示プロパティ制御

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

```
Get-DbaAgentAlert (エントリーポイント)
    |
    └── [processブロック]
            |
            └── foreach ($instance in $SqlInstance)
                    |
                    ├── Connect-DbaInstance
                    |       └── SQL Server接続
                    |
                    ├── Express Edition チェック
                    |       └── Stop-Function (Express時)
                    |
                    ├── $server.JobServer.Alerts
                    |       └── SMOアラートコレクション取得
                    |
                    ├── フィルタリング
                    |       ├── Alert パラメータ (ワイルドカード)
                    |       └── ExcludeAlert パラメータ
                    |
                    └── foreach ($alrt in $alerts)
                            ├── [dbadatetime] LastOccurrenceDate変換
                            ├── Add-Member (ComputerName)
                            ├── Add-Member (InstanceName)
                            ├── Add-Member (SqlInstance)
                            ├── Add-Member (Notifications)
                            ├── Add-Member (LastRaised)
                            └── Select-DefaultView
```

### データフロー図

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

SqlInstance ────────┐
SqlCredential ──────┼──▶ Connect-DbaInstance ──▶ $server
Alert ──────────────┤                               │
ExcludeAlert ───────┘                               ▼
                                          $server.JobServer.Alerts
                                                    │
                                                    ▼
                                          フィルタリング処理
                                          (Alert/ExcludeAlert)
                                                    │
                                                    ▼
                                          foreach ($alrt)
                                                    │
                                                    ▼
                                          Add-Member (カスタムプロパティ)
                                          - ComputerName
                                          - InstanceName
                                          - SqlInstance
                                          - Notifications
                                          - LastRaised
                                                    │
                                                    ▼
                                          Select-DefaultView
                                                    │
                                                    ▼
                                    Microsoft.SqlServer.Management.Smo.Agent.Alert
                                    (拡張プロパティ付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | ソース | メインコマンド実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ユーティリティ |
| Test-Bound.ps1 | `private/functions/Test-Bound.ps1` | ソース | パラメータ指定チェック |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | デフォルト表示プロパティ制御 |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | ログ出力ユーティリティ |
