# 通知設計書 22-Get-DbaAgentOperator

## 概要

本ドキュメントは、SQL Server Agentオペレーター（通知先連絡先）の設定と関連するジョブ/アラート情報を取得するPowerShellコマンド `Get-DbaAgentOperator` の通知設計書です。

### 本通知の処理概要

`Get-DbaAgentOperator` は、SQL Server Agentで設定されているオペレーター（通知受信者）の詳細情報を取得するコマンドです。メールアドレス、有効/無効状態、関連するジョブやアラートとの紐付け情報など、通知インフラストラクチャの監査やトラブルシューティングに必要な情報を提供します。

**業務上の目的・背景**：SQL Server Agentのオペレーターは、アラートやジョブ失敗時の通知を受信する連絡先です。データベース管理者は、監視・警告システムが正しく構成されているか、誰が通知を受け取るのか、最後に通知が送信されたのはいつかを把握する必要があります。このコマンドは、通知構成の監査、アラート配信問題のトラブルシューティング、災害復旧用の連絡先リスト維持に不可欠な情報を提供します。

**通知の送信タイミング**：このコマンドは通知を送信する機能ではなく、オペレーター設定情報を取得（参照）するコマンドです。コマンド実行時に即座にSMOオペレーターオブジェクトがパイプラインに出力されます。

**通知の受信者**：コマンド実行者がPowerShellコンソールまたはスクリプトの出力を通じて結果を受信します。取得したオペレーター情報は、実際にSQL Server Agentから通知を受信する連絡先の設定を示しています。

**通知内容の概要**：出力には以下の情報が含まれます：コンピュータ名、インスタンス名、オペレーター名、ID、有効/無効状態、メールアドレス、最終メール送信日時、関連ジョブ一覧、関連アラート一覧、アラートからの最終メール送信日時。

**期待されるアクション**：コマンド実行者は取得した情報をもとに、オペレーター設定の監査、不適切な設定の修正（Set-DbaAgentOperator使用）、未使用オペレーターの削除（Remove-DbaAgentOperator使用）などのアクションを実施することが期待されます。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（即座にパイプライン出力） |
| 優先度 | 中 |
| リトライ | 無（コマンド再実行により対応） |

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

コマンド実行者のPowerShellセッションに直接出力されます。出力はパイプラインを通じて後続のコマンドに渡すことも、変数に格納することも可能です。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 出力形式 | Microsoft.SqlServer.Management.Smo.Agent.Operator（SMOオブジェクト） |
| デフォルト表示プロパティ | ComputerName, InstanceName, SqlInstance, Name, ID, IsEnabled, EmailAddress, LastEmail |

### 出力オブジェクト構造

```powershell
# SMO Operatorオブジェクトに追加されるプロパティ
Add-Member -MemberType NoteProperty -Name ComputerName -Value "サーバー名"
Add-Member -MemberType NoteProperty -Name InstanceName -Value "インスタンス名"
Add-Member -MemberType NoteProperty -Name SqlInstance -Value "完全修飾インスタンス名"
Add-Member -MemberType NoteProperty -Name RelatedJobs -Value @(ジョブオブジェクト配列)
Add-Member -MemberType NoteProperty -Name LastEmail -Value [dbadatetime]
Add-Member -MemberType NoteProperty -Name RelatedAlerts -Value @(アラート名配列)
Add-Member -MemberType NoteProperty -Name AlertLastEmail -Value [dbadatetime]
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| ComputerName | SQLサーバーのコンピュータ名 | $server.ComputerName | Yes |
| InstanceName | SQLサーバーのサービス名 | $server.ServiceName | Yes |
| SqlInstance | ドメインインスタンス名 | $server.DomainInstanceName | Yes |
| Name | オペレーター名 | SMO Operator.Name | Yes |
| ID | オペレーターID | SMO Operator.ID | Yes |
| Enabled/IsEnabled | 有効/無効状態 | SMO Operator.Enabled | Yes |
| EmailAddress | メールアドレス | SMO Operator.EmailAddress | No |
| LastEmail | 最終メール送信日時 | SMO Operator.LastEmailDate | No |
| RelatedJobs | 関連ジョブ配列 | ジョブのフィルタリング結果 | No |
| RelatedAlerts | 関連アラート名配列 | EnumNotifications結果 | No |
| AlertLastEmail | アラートからの最終メール | Alert.LastOccurrenceDate | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コマンド実行 | Get-DbaAgentOperator実行 | 常に | SQL Server接続成功時に出力 |
| パイプライン入力 | SqlInstanceの値受信 | ValueFromPipeline | パイプラインからインスタンス名を受け取り処理 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| Express Edition | SQL Server Expressエディションの場合、SQL Agentがないためスキップ |
| Operatorフィルタ不一致 | -Operatorパラメータで指定した名前に一致しない場合 |
| ExcludeOperatorフィルタ一致 | -ExcludeOperatorパラメータで指定した名前に一致した場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[インスタンスループ開始]
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function + Continue]
    D -->|Yes| F{Express Edition?}
    F -->|Yes| G[Stop-Function + Continue]
    F -->|No| H[オペレーター取得]
    H --> I{Operatorフィルタ?}
    I -->|Yes| J[名前でフィルタリング]
    I -->|No| K{ExcludeOperatorフィルタ?}
    K -->|Yes| L[除外フィルタリング]
    K -->|No| M[全オペレーター]
    J --> N[アラート取得]
    L --> N
    M --> N
    N --> O[各オペレーターをループ]
    O --> P[関連ジョブ検索]
    P --> Q[関連アラート検索]
    Q --> R[NotePropertyを追加]
    R --> S[Select-DefaultView]
    S --> T[出力]
    T --> O
    O -->|完了| U[次のインスタンス]
    U --> B
    E --> U
    G --> U
    B -->|完了| V[終了]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| msdb.dbo.sysoperators | オペレーター情報の取得 | SMO経由でアクセス |
| msdb.dbo.sysjobs | 関連ジョブの検索 | OperatorToEmail等でフィルタ |
| msdb.dbo.sysalerts | 関連アラートの検索 | EnumNotifications経由 |
| msdb.dbo.sysnotifications | 通知関連付け | EnumNotifications経由 |

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

#### msdb.dbo.sysoperators

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| id | オペレーター識別 | SMOオブジェクト経由 |
| name | オペレーター名 | SMOオブジェクト経由 |
| enabled | 有効/無効状態 | SMOオブジェクト経由 |
| email_address | メールアドレス | SMOオブジェクト経由 |
| last_email_date/time | 最終メール送信日時 | SMOオブジェクト経由 |
| netsend_address | NetSendアドレス | SMOオブジェクト経由 |
| pager_address | ページャーアドレス | SMOオブジェクト経由 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | 参照のみ（更新なし） |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 接続エラー | SQL Serverインスタンスに接続できない | 接続情報を確認し再試行 |
| Express Edition | SQL Server Expressを指定 | Standard以上のエディションを使用 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A（手動で再実行が必要） |

## 配信設定

### レート制限

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

### 配信時間帯

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

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

- SQL Serverインスタンスへの接続権限が必要
- SqlCredentialパラメータを使用して安全に認証情報を渡すことが可能
- オペレーターのメールアドレス情報を含むため、出力の取り扱いに注意

## 備考

- SQL Server Expressエディションには SQL Agent がないため、このコマンドは使用できない
- オペレーターの関連ジョブは、OperatorToEmail、OperatorToNetSend、OperatorToPage プロパティでフィルタリングして検索
- 関連アラートは EnumNotifications メソッドを使用して取得
- パイプライン入力により複数インスタンスの一括処理が可能

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | 63-106行目の.OUTPUTSセクションで出力構造を確認 |
| 1-2 | Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | 159-166行目でAdd-Memberによるプロパティ追加を確認 |

**読解のコツ**: SMOオブジェクト `Microsoft.SqlServer.Management.Smo.Agent.Operator` は基本プロパティを持ちますが、dbatools固有のプロパティ（RelatedJobs、RelatedAlerts等）はAdd-Memberで動的に追加されます。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | 1-117行目でfunction宣言とパラメータ定義を確認 |

**主要処理フロー**:
1. **108-117行目**: パラメータ定義（SqlInstanceがMandatoryでValueFromPipeline）
2. **118行目**: processブロック開始
3. **119行目**: foreachでインスタンスループ

#### Step 3: 接続とエディションチェックを理解する

SQL Server接続とExpressエディションの判定ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | 120-131行目で接続とエディションチェックを確認 |

**主要処理フロー**:
- **120-124行目**: Connect-DbaInstance呼び出しとエラーハンドリング
- **129-131行目**: Expressエディション判定とスキップ処理

#### Step 4: オペレーター取得と関連情報検索を理解する

オペレーターの取得、フィルタリング、関連ジョブ/アラートの検索ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | 133-167行目でオペレーター処理を確認 |

**主要処理フロー**:
- **135-141行目**: オペレーターフィルタリング（Operator/ExcludeOperator）
- **147行目**: 関連ジョブの検索（OperatorToEmail等でフィルタ）
- **150-157行目**: 関連アラートの検索（EnumNotifications使用）
- **159-166行目**: NotePropertyの追加

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

```
Get-DbaAgentOperator
    |
    +-- [processブロック]
            +-- foreach ($instance in $SqlInstance)
                    |
                    +-- Connect-DbaInstance
                    |       +-- SQL Server接続
                    |
                    +-- Edition Check ($server.Edition)
                    |
                    +-- $server.JobServer.Operators
                    |       +-- Where-Object Name -In $Operator
                    |       +-- Where-Object Name -NotIn $ExcludeOperator
                    |
                    +-- foreach ($operat in $operators)
                            |
                            +-- $server.JobServer.jobs | Where-Object
                            |       (OperatorToEmail, OperatorToNetSend, OperatorToPage)
                            |
                            +-- foreach ($alert in $alerts)
                            |       +-- $alert.EnumNotifications($operat.Name)
                            |
                            +-- Add-Member (ComputerName, InstanceName, etc.)
                            |
                            +-- Select-DefaultView
```

### データフロー図

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

SqlInstance[] ────────────────> Connect-DbaInstance
        |                              |
        v                              v
        |                       $server.JobServer.Operators ─────> フィルタリング
        |                              |
        |                              v
        |                       各オペレーターループ
        |                              |
        |                       ┌──────┴──────┐
        |                       |             |
        |                       v             v
        |               関連ジョブ検索   関連アラート検索
        |               (Where-Object)  (EnumNotifications)
        |                       |             |
        |                       └──────┬──────┘
        |                              |
        |                              v
        |                       Add-Member (プロパティ追加)
        |                              |
        |                              v
        └──────────────────────> SMO Operator ────────> パイプライン出力
                                 + ComputerName
                                 + InstanceName
                                 + SqlInstance
                                 + RelatedJobs
                                 + LastEmail
                                 + RelatedAlerts
                                 + AlertLastEmail
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | ソース | オペレーター取得の本体 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `internal/functions/Stop-Function.ps1` | ソース | エラーハンドリング共通関数 |
| Select-DefaultView.ps1 | `internal/functions/Select-DefaultView.ps1` | ソース | デフォルト表示プロパティ設定 |
| New-DbaAgentOperator.ps1 | `public/New-DbaAgentOperator.ps1` | ソース | オペレーター作成（関連コマンド） |
| Set-DbaAgentOperator.ps1 | `public/Set-DbaAgentOperator.ps1` | ソース | オペレーター更新（関連コマンド） |
| Remove-DbaAgentOperator.ps1 | `public/Remove-DbaAgentOperator.ps1` | ソース | オペレーター削除（関連コマンド） |
