# 機能設計書 492-Get-DbaAgentProxy

## 概要

本ドキュメントは、SQL Server Agent プロキシアカウントの取得機能 `Get-DbaAgentProxy` の設計仕様を記載する。

### 本機能の処理概要

SQL Server Agent で設定されているプロキシアカウント（代理実行アカウント）の詳細情報を取得する機能である。プロキシアカウントは、ジョブステップを SQL Agent サービスアカウント以外のセキュリティコンテキストで実行するために使用される。

**業務上の目的・背景**：SQL Server Agent のジョブステップは通常、Agent サービスアカウントの権限で実行されるが、特定のジョブステップでは異なる Windows 資格情報が必要となる場合がある（ファイルシステムアクセス、ネットワークリソースへのアクセス等）。プロキシアカウントにより、ジョブステップごとに適切なセキュリティコンテキストを設定できる。本機能は、セキュリティ監査、コンプライアンス報告、ジョブステップの実行権限トラブルシューティングに不可欠である。

**機能の利用シーン**：
- セキュリティ監査でのプロキシアカウント設定確認
- コンプライアンス報告書の作成
- ジョブステップの実行権限に関するトラブルシューティング
- 新環境への設定移行準備
- 複数インスタンスにおけるプロキシアカウント設定の一括確認

**主要な処理内容**：
1. 対象 SQL Server インスタンスへの接続
2. SQL Server Agent のプロキシアカウント一覧取得
3. 指定された条件（名前指定、除外指定）によるフィルタリング
4. 拡張プロパティの付与と結果の出力

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

**権限による制御**：SQL Server への接続権限が必要。プロキシアカウント情報の取得には、msdb データベースへの参照権限が必要となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | Agentプロキシ管理 | 主画面 | SQLエージェントプロキシの取得 |

## 機能種別

データ取得（SELECT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQLServerインスタンス。パイプライン入力可能 | 必須、配列対応 |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証/AD対応 |
| Proxy | string[] | No | 取得対象プロキシ名の配列 | ワイルドカード対応 |
| ExcludeProxy | string[] | No | 除外対象プロキシ名の配列 | ワイルドカード対応 |
| EnableException | switch | No | 例外処理の制御フラグ | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピューター名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| InstanceName | string | SQL Serverインスタンス名 |
| Name | string | プロキシアカウント名 |
| ID | int | プロキシアカウントID |
| CredentialID | int | 関連する資格情報のID |
| CredentialIdentity | string | 資格情報のWindowsアカウントID |
| CredentialName | string | 関連する資格情報名 |
| Description | string | プロキシアカウントの説明 |
| IsEnabled | bool | プロキシアカウントが有効かどうか |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstance の必須チェック
2. インスタンスループ開始
   └─ 各 SqlInstance に対して処理
3. SQL Server 接続
   └─ Connect-DbaInstance で接続確立
4. エディションチェック
   └─ Express Edition の場合は処理スキップ
5. プロキシアカウント取得
   └─ $server.JobServer.ProxyAccounts から取得
6. フィルタリング処理
   └─ Proxy / ExcludeProxy に基づきフィルタ
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[ProxyAccounts 取得]
    I --> J{Proxy 指定?}
    J -->|Yes| K[Name -like フィルタ]
    K --> L{ExcludeProxy 指定?}
    J -->|No| L
    L -->|Yes| M[Name -notlike フィルタ]
    L -->|No| N[プロキシループ]
    M --> N
    N --> O[拡張プロパティ付与]
    O --> P[Select-DefaultView 出力]
    P --> C
    C -->|終了| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-492-01 | Express Edition 除外 | Express Edition では SQL Agent が存在しないため処理をスキップ | サーバーエディションが Express* にマッチ |
| BR-492-02 | ワイルドカード対応 | Proxy および ExcludeProxy パラメータでワイルドカード（*、?）使用可能 | フィルタリング時 |
| BR-492-03 | フィルタ適用順序 | Proxy フィルタ適用後に ExcludeProxy フィルタを適用 | 両パラメータ指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プロキシ取得 | msdb.dbo.sysproxies | SELECT | プロキシアカウント情報の取得（SMO経由） |
| 資格情報取得 | master.sys.credentials | SELECT | 関連資格情報の取得（SMO経由） |

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

#### msdb.dbo.sysproxies

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

- 各インスタンスへの接続は順次処理
- プロキシアカウントの取得はメモリ内で行われる

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

- SQL Server への接続には SqlCredential による認証情報指定が可能
- Windows 認証、SQL Server 認証、Active Directory 認証をサポート
- MFA 対応は Connect-DbaInstance を事前に使用する必要あり
- プロキシアカウントの CredentialIdentity は Windows アカウント情報を含むため、出力結果の取り扱いに注意

## 備考

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

---

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

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

### 推奨読解順序

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

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

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

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

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

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

**主要処理フロー**:
1. **93行目**: foreach ($instance in $SqlInstance) でインスタンスループ開始
2. **95行目**: Connect-DbaInstance で SMO 接続確立
3. **103-105行目**: Express Edition チェック
4. **109行目**: ProxyAccounts コレクション取得
5. **111-125行目**: フィルタリング処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentProxy.ps1 | `public/Get-DbaAgentProxy.ps1` | 111-125行目のプロキシフィルタリング処理 |

**主要処理フロー**:
- **111-118行目**: Proxy パラメータ指定時は Name -like でフィルタ（ワイルドカード対応）
- **121-124行目**: ExcludeProxy パラメータ指定時は Name -notlike でフィルタ

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

```
Get-DbaAgentProxy
    │
    ├─ Connect-DbaInstance
    │      └─ SMO 接続確立
    │
    ├─ Stop-Function
    │      └─ エラー/警告処理
    │
    ├─ Write-Message
    │      └─ Verbose ログ出力
    │
    ├─ Test-Bound
    │      └─ パラメータ指定チェック
    │
    ├─ $server.JobServer.ProxyAccounts
    │      └─ プロキシアカウント取得
    │
    ├─ Add-Member
    │      └─ 拡張プロパティ追加
    │
    └─ Select-DefaultView
           └─ デフォルト表示プロパティ設定
```

### データフロー図

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

SqlInstance ───────────┬─► Connect-DbaInstance ───────────► SMO Server オブジェクト
SqlCredential ─────────┘                                            │
                                                                    ▼
                                                   $server.JobServer.ProxyAccounts
                                                            │
Proxy ────────────────────► Where-Object -like ◄────────────┘
                                    │
ExcludeProxy ─────────────► Where-Object -notlike ◄─────────┘
                                    │
                                    ▼
                            各プロキシアカウント
                                    │
                                    ▼
                             Add-Member (拡張)
                                    │
                                    ▼
                          Select-DefaultView ───────► ProxyAccount オブジェクト
                                                      (拡張プロパティ付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentProxy.ps1 | `public/Get-DbaAgentProxy.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` | ソース | ログ出力ヘルパー |
| Test-Bound.ps1 | `internal/functions/Test-Bound.ps1` | ソース | パラメータ指定チェック |
| Select-DefaultView.ps1 | `internal/functions/Select-DefaultView.ps1` | ソース | デフォルト表示設定 |
