# 通知設計書 25-Remove-DbaAgentOperator

## 概要

本ドキュメントは、SQL Server Agentオペレーターを削除するPowerShellコマンド `Remove-DbaAgentOperator` の通知設計書です。

### 本通知の処理概要

`Remove-DbaAgentOperator` は、指定されたSQL Server Agentオペレーター（通知連絡先）を削除するコマンドです。不要になった通知連絡先のクリーンアップや、退職者・異動者のオペレーターアカウント整理に使用されます。

**業務上の目的・背景**：SQL Server Agentのオペレーターは、アラートやジョブ失敗時の通知を受信する連絡先です。従業員の退職、連絡先情報の変更、通知リストの整理などにより、不要になったオペレーターを削除する必要が生じます。このコマンドは、手動でSSMSを操作する代わりに、スクリプトによる安全な削除を実現します。対話的な選択削除（Out-GridViewとの連携）も可能で、複数インスタンスへの一括適用が可能です。

**通知の送信タイミング**：このコマンドはオペレーターを削除する機能であり、削除時に通知は送信されません。操作結果として、削除の成功・失敗ステータスを含むPSCustomObjectが即座にパイプラインに出力されます。

**通知の受信者**：コマンド実行者がPowerShellコンソールまたはスクリプトの出力を通じて結果を受信します。

**通知内容の概要**：出力には以下の情報が含まれます：コンピュータ名、インスタンス名、SQL Serverインスタンス名、オペレーター名、ステータス（"Dropped" または エラーメッセージ）、削除成否のブール値。

**期待されるアクション**：コマンド実行者は出力結果を確認し、失敗した削除操作については原因を調査して再試行するか、依存関係（関連するアラートやジョブ）を解消してから再実行することが期待されます。

## 通知種別

コンソール出力 / パイプライン出力（PSCustomObject）

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 出力形式 | PSCustomObject |
| 表示プロパティ | ComputerName, InstanceName, SqlInstance, Name, Status, IsRemoved |

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

```powershell
[PSCustomObject]@{
    ComputerName = "サーバー名"
    InstanceName = "インスタンス名"
    SqlInstance  = "完全修飾インスタンス名"
    Name         = "削除されたオペレーター名"
    Status       = "Dropped" または "エラーメッセージ"
    IsRemoved    = $true または $false
}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| ComputerName | SQLサーバーのコンピュータ名 | $dbOperator.Parent.Parent.ComputerName | Yes |
| InstanceName | SQLサーバーのサービス名 | $dbOperator.Parent.Parent.ServiceName | Yes |
| SqlInstance | ドメインインスタンス名 | $dbOperator.Parent.Parent.DomainInstanceName | Yes |
| Name | オペレーター名 | $dbOperator.Name | Yes |
| Status | 削除結果ステータス | 処理結果から動的に設定 | Yes |
| IsRemoved | 削除成否フラグ | 処理結果から動的に設定 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コマンド実行 | Remove-DbaAgentOperator実行 | ShouldProcess確認後 | 各オペレーターの削除処理完了時に出力 |
| パイプライン入力 | Get-DbaAgentOperatorからのパイプ | InputObject受信時 | パイプラインから受け取ったオペレーターを処理 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| WhatIf指定時 | -WhatIfパラメータ指定時は実際の削除は行わず、予定される動作のみ表示 |
| Confirm拒否時 | -Confirmで確認を求められた際にユーザーが拒否した場合 |
| ExcludeOperator一致 | -ExcludeOperatorパラメータで指定した名前に一致した場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaAgentOperator呼び出し]
    B -->|No| D[InputObjectを使用]
    C --> E[オペレーター一覧取得]
    D --> E
    E --> F[endブロックで処理開始]
    F --> G{各オペレーターをループ}
    G --> H{ShouldProcess確認}
    H -->|Yes| I[出力オブジェクト初期化]
    H -->|No| G
    I --> J[Drop実行]
    J --> K{成功?}
    K -->|Yes| L[Status=Dropped, IsRemoved=true]
    K -->|No| M[Stop-Function呼び出し]
    M --> N[Status=エラーメッセージ, IsRemoved=false]
    L --> O[出力オブジェクト出力]
    N --> O
    O --> G
    G -->|完了| P[終了]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| msdb.dbo.sysoperators | オペレーター情報の取得 | SMO/Get-DbaAgentOperator経由でアクセス |

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

#### msdb.dbo.sysoperators

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| id | オペレーター識別 | SMOオブジェクト経由 |
| name | オペレーター名フィルタリング | Operator/ExcludeOperatorパラメータ |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| msdb.dbo.sysoperators | DELETE | 指定オペレーターの削除 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 接続エラー | SQL Serverインスタンスに接続できない | 接続情報を確認し再試行 |
| 権限エラー | sysadmin権限がない | 適切な権限を持つアカウントで再実行 |
| 依存関係エラー | オペレーターが他のオブジェクトに参照されている | 依存関係を解消してから再実行 |
| SMOエラー | Drop操作失敗 | エラーメッセージを確認し原因対処 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

- SQL Serverインスタンスへのsysadmin権限が必要
- SqlCredentialパラメータを使用して安全に認証情報を渡すことが可能
- WhatIfパラメータを使用して、実行前に影響を確認可能
- ConfirmImpactがHighに設定されているため、デフォルトで確認プロンプトが表示される
- フェールセーフオペレーターとして設定されているオペレーターは削除前に再検討が必要

## 備考

- Get-DbaAgentOperatorとパイプラインで連携し、Out-GridViewを使用した対話的な選択削除が可能
- endブロックで削除処理を行うことで、パイプライン入力時の「コレクション変更」エラーを回避
- DefaultParameterSetNameは'Default'に設定
- Operatorパラメータで名前指定、ExcludeOperatorパラメータで除外指定が可能

---

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

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

### 推奨読解順序

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

まず、処理対象となるオペレーターオブジェクトと出力オブジェクトの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Remove-DbaAgentOperator.ps1 | `public/Remove-DbaAgentOperator.ps1` | 57-66行目の.OUTPUTSセクションで出力構造を確認 |
| 1-2 | Remove-DbaAgentOperator.ps1 | `public/Remove-DbaAgentOperator.ps1` | 109-116行目でPSCustomObject出力構造を確認 |

**読解のコツ**: SMOオブジェクト `Microsoft.SqlServer.Management.Smo.Agent.Operator` は Parent プロパティを通じてJobServer、さらにその親としてServerオブジェクトにアクセスできます。`$dbOperator.Parent.Parent` でServerオブジェクトを参照しています。

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

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

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

**主要処理フロー**:
1. **79-88行目**: パラメータ定義（DefaultとPipelineの2つのParameterSet）
2. **90-92行目**: beginブロックで空配列を初期化
3. **94-103行目**: processブロックでオペレーターを収集
4. **105-129行目**: endブロックで実際の削除処理

#### Step 3: オペレーター収集を理解する

SqlInstance指定時とパイプライン入力時のオペレーター収集ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Remove-DbaAgentOperator.ps1 | `public/Remove-DbaAgentOperator.ps1` | 94-103行目でオペレーター収集を確認 |

**主要処理フロー**:
- **95-99行目**: SqlInstance指定時にGet-DbaAgentOperatorを呼び出し
- **100-102行目**: InputObject（パイプライン）の場合は配列に追加

#### Step 4: 削除処理の詳細を理解する

endブロックでの削除処理とエラーハンドリングを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Remove-DbaAgentOperator.ps1 | `public/Remove-DbaAgentOperator.ps1` | 105-129行目で削除処理とエラーハンドリングを確認 |

**主要処理フロー**:
- **106-108行目**: foreachループとShouldProcess確認
- **117-120行目**: Drop()メソッド呼び出しと成功時の処理
- **121-125行目**: catch節でのエラー処理

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

```
Remove-DbaAgentOperator
    |
    +-- [beginブロック]
    |       +-- $dbOperators = @( ) 初期化
    |
    +-- [processブロック]
    |       +-- SqlInstance指定時
    |       |       +-- Get-DbaAgentOperator
    |       |               +-- Connect-DbaInstance
    |       |               +-- Operator/ExcludeOperatorフィルタリング
    |       +-- InputObject指定時
    |               +-- $dbOperators に追加
    |
    +-- [endブロック]
            +-- foreach ($dbOperator in $dbOperators)
                    +-- ShouldProcess確認
                    +-- PSCustomObject作成
                    +-- $dbOperator.Drop()
                    +-- 成功/失敗に応じてStatus設定
                    +-- 出力
```

### データフロー図

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

SqlInstance ──────────────────> Get-DbaAgentOperator ─┐
                                                      │
Operator[] ─────────────────────────────────────────────┼────> $dbOperators
                                                      │
ExcludeOperator[] ──────────────────────────────────────┤
                                                      │
InputObject (Pipeline) ───────────────────────────────┘
                                        |
                                        v
                               ┌────────────────────┐
                               │ foreach + Drop()   │
                               └────────────────────┘
                                        |
                                        v
                               PSCustomObject ────────> パイプライン出力
                               - ComputerName
                               - InstanceName
                               - SqlInstance
                               - Name
                               - Status
                               - IsRemoved
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaAgentOperator.ps1 | `public/Remove-DbaAgentOperator.ps1` | ソース | オペレーター削除の本体 |
| Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | ソース | オペレーター取得（依存コマンド） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `internal/functions/Stop-Function.ps1` | ソース | エラーハンドリング共通関数 |
| Get-ErrorMessage.ps1 | `internal/functions/Get-ErrorMessage.ps1` | ソース | エラーメッセージ取得 |
| New-DbaAgentOperator.ps1 | `public/New-DbaAgentOperator.ps1` | ソース | オペレーター作成（関連コマンド） |
| Set-DbaAgentOperator.ps1 | `public/Set-DbaAgentOperator.ps1` | ソース | オペレーター更新（関連コマンド） |
