# 機能設計書 491-Get-DbaAgentOperator

## 概要

本ドキュメントは、SQL Server Agent オペレーターの取得機能 `Get-DbaAgentOperator` の設計仕様を記載する。

### 本機能の処理概要

SQL Server Agent で設定されているオペレーター（通知先）の詳細情報を取得し、関連するジョブやアラートの情報も含めて返却する機能である。

**業務上の目的・背景**：SQL Server Agent によるジョブ監視・アラート通知の基盤において、オペレーター（通知受信者）の設定状況を把握することは運用管理上不可欠である。特にアラート配信のトラブルシューティング、災害復旧時の連絡先確認、複数インスタンスにまたがる通知設定の監査において、オペレーター情報の一括取得機能が必要となる。本機能により、SSMS を個別に開くことなく、PowerShell から効率的にオペレーター情報を収集・分析できる。

**機能の利用シーン**：
- 複数の SQL Server インスタンスにおけるオペレーター設定の一括監査
- アラート通知が届かない場合のトラブルシューティング
- 災害復旧計画書に記載する連絡先リストの作成
- オペレーターと関連ジョブ・アラートの依存関係の把握
- 新環境構築時のオペレーター設定移行準備

**主要な処理内容**：
1. 対象 SQL Server インスタンスへの接続
2. SQL Server Agent のオペレーター一覧取得
3. 指定された条件（名前指定、除外指定）によるフィルタリング
4. 各オペレーターに関連するジョブ情報の収集
5. 各オペレーターに関連するアラート情報の収集
6. 拡張プロパティの付与と結果の出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を使用して SQL Server Agent の情報を取得する。Express Edition では SQL Server Agent が存在しないため、処理をスキップする。

**権限による制御**：SQL Server への接続権限が必要。オペレーター情報の取得には、msdb データベースへの参照権限が必要となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 13 | Agentオペレーター管理 | 主画面 | SQLエージェントオペレーターの取得 |

## 機能種別

データ取得（SELECT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQLServerインスタンス。パイプライン入力可能 | 必須、配列対応 |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証/AD対応 |
| Operator | object[] | No | 取得対象オペレーター名の配列 | 完全一致 |
| ExcludeOperator | object[] | No | 除外対象オペレーター名の配列 | 完全一致 |
| EnableException | switch | No | 例外処理の制御フラグ | - |

### 入力データソース

- SQL Server インスタンスへの SMO 接続
- `$server.JobServer.Operators` コレクション
- `$server.JobServer.Alerts` コレクション
- `$server.JobServer.Jobs` コレクション

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | オペレーター名 |
| ID | int | オペレーターID |
| IsEnabled | bool | オペレーターが有効かどうか |
| EmailAddress | string | メールアドレス |
| LastEmail | dbadatetime | 最終メール送信日時 |
| RelatedJobs | Job[] | 関連するジョブオブジェクト配列 |
| RelatedAlerts | string[] | 関連するアラート名配列 |
| AlertLastEmail | dbadatetime | アラートからの最終メール日時 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstance の必須チェック
2. インスタンスループ開始
   └─ 各 SqlInstance に対して処理
3. SQL Server 接続
   └─ Connect-DbaInstance で接続確立
4. エディションチェック
   └─ Express Edition の場合は処理スキップ
5. オペレーター取得
   └─ フィルタ条件に基づきオペレーター取得
6. 関連情報収集ループ
   └─ 各オペレーターに対して関連ジョブ・アラート取得
7. プロパティ付与
   └─ 拡張プロパティの追加
8. 結果出力
   └─ Select-DefaultView でデフォルトプロパティ表示
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ受け取り]
    B --> C{SqlInstance ループ}
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function でエラー]
    F --> C
    E -->|Yes| G{Express Edition?}
    G -->|Yes| H[Stop-Function でスキップ]
    H --> C
    G -->|No| I[オペレーター取得]
    I --> J{Operator 指定?}
    J -->|Yes| K[Name -In フィルタ]
    J -->|No| L{ExcludeOperator 指定?}
    L -->|Yes| M[Name -NotIn フィルタ]
    L -->|No| N[全オペレーター取得]
    K --> O[関連ジョブ取得]
    M --> O
    N --> O
    O --> P[関連アラート取得]
    P --> Q[拡張プロパティ付与]
    Q --> R[Select-DefaultView 出力]
    R --> C
    C -->|終了| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-491-01 | Express Edition 除外 | Express Edition では SQL Agent が存在しないため処理をスキップ | サーバーエディションが Express* にマッチ |
| BR-491-02 | オペレーターフィルタ優先度 | Operator 指定時は ExcludeOperator は無視される | Operator パラメータ指定時 |
| BR-491-03 | 関連ジョブ判定 | OperatorToEmail, OperatorToNetSend, OperatorToPage のいずれかにオペレーター名が含まれるジョブを関連ジョブとする | 全オペレーター |

### 計算ロジック

- LastEmail: SMO オブジェクトの LastEmailDate を dbadatetime 型に変換
- AlertLastEmail: 関連アラートの LastOccurrenceDate を dbadatetime 型に変換

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| オペレーター取得 | msdb.dbo.sysoperators | SELECT | オペレーター情報の取得（SMO経由） |
| アラート取得 | msdb.dbo.sysalerts | SELECT | アラート情報の取得（SMO経由） |
| ジョブ取得 | msdb.dbo.sysjobs | SELECT | ジョブ情報の取得（SMO経由） |

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

#### msdb.dbo.sysoperators

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, id, enabled, email_address, last_email_date など | 全件または名前フィルタ | SMO経由で取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server への接続失敗 | Stop-Function で Continue、次のインスタンスへ |
| ExpressEdition | 非対応 | Express Edition インスタンス | Stop-Function で Continue、警告メッセージ出力 |

### リトライ仕様

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

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- 各インスタンスへの接続は順次処理
- 関連ジョブ・アラートの取得はメモリ内で行われる
- 大量のジョブ・アラートが存在する環境では処理時間が増加する可能性あり

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

- SQL Server への接続には SqlCredential による認証情報指定が可能
- Windows 認証、SQL Server 認証、Active Directory 認証をサポート
- MFA 対応は Connect-DbaInstance を事前に使用する必要あり
- オペレーターのメールアドレス等の個人情報が含まれる可能性があるため、出力結果の取り扱いに注意

## 備考

- Select-DefaultView により、デフォルトでは主要プロパティのみ表示される
- 全プロパティを確認するには `Select-Object *` を使用
- パイプライン入力により複数インスタンスの一括処理が可能

---

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

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

### 推奨読解順序

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

SMO の Operator オブジェクト構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | 133行目のデフォルト表示プロパティ定義、145-166行目の拡張プロパティ追加処理 |

**読解のコツ**: PowerShell の Add-Member を使用した動的プロパティ追加パターン。SMO オブジェクトに NoteProperty を追加して情報を拡張している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | 108-117行目のパラメータ定義、118行目の process ブロック開始 |

**主要処理フロー**:
1. **119行目**: foreach ($instance in $SqlInstance) でインスタンスループ開始
2. **121行目**: Connect-DbaInstance で SMO 接続確立
3. **129-131行目**: Express Edition チェック
4. **135-141行目**: オペレーターフィルタリング処理
5. **145-167行目**: 関連情報収集と出力

#### Step 3: フィルタリング処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | 135-141行目のオペレーターフィルタリング条件分岐 |

**主要処理フロー**:
- **135-136行目**: Operator パラメータ指定時は Name -In でフィルタ
- **137-138行目**: ExcludeOperator パラメータ指定時は Name -NotIn でフィルタ
- **139-140行目**: いずれも指定なしの場合は全オペレーター取得

#### Step 4: 関連情報収集処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | 143-157行目の関連ジョブ・アラート収集処理 |

**主要処理フロー**:
- **147行目**: ジョブの OperatorToEmail, OperatorToNetSend, OperatorToPage プロパティをチェック
- **151-156行目**: 各アラートの EnumNotifications メソッドでオペレーター通知設定を確認

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

```
Get-DbaAgentOperator
    │
    ├─ Connect-DbaInstance
    │      └─ SMO 接続確立
    │
    ├─ Stop-Function
    │      └─ エラー/警告処理
    │
    ├─ Write-Message
    │      └─ Verbose ログ出力
    │
    ├─ $server.JobServer.Operators
    │      └─ オペレーター取得
    │
    ├─ $server.JobServer.Jobs
    │      └─ 関連ジョブ検索
    │
    ├─ $server.JobServer.Alerts
    │      └─ 関連アラート検索
    │
    ├─ Add-Member
    │      └─ 拡張プロパティ追加
    │
    └─ Select-DefaultView
           └─ デフォルト表示プロパティ設定
```

### データフロー図

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

SqlInstance ───────────┬─► Connect-DbaInstance ───────────► SMO Server オブジェクト
SqlCredential ─────────┘                                            │
                                                                    ▼
                                                   $server.JobServer.Operators
                                                            │
Operator ─────────────────► Where-Object (フィルタ) ◄───────┘
ExcludeOperator ──────────►                │
                                           ▼
                                    各オペレーター
                                           │
                              ┌────────────┼────────────┐
                              ▼            ▼            ▼
                        RelatedJobs   RelatedAlerts  LastEmail
                              │            │            │
                              └────────────┴────────────┘
                                           │
                                           ▼
                                    Add-Member (拡張)
                                           │
                                           ▼
                                  Select-DefaultView ───────► Operator オブジェクト
                                                              (拡張プロパティ付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続ヘルパー |
| Stop-Function.ps1 | `internal/functions/Stop-Function.ps1` | ソース | エラー処理ヘルパー |
| Write-Message.ps1 | `internal/functions/Write-Message.ps1` | ソース | ログ出力ヘルパー |
| Select-DefaultView.ps1 | `internal/functions/Select-DefaultView.ps1` | ソース | デフォルト表示設定 |
