# 画面設計書 15-Agentプロキシ管理

## 概要

本ドキュメントは、SQL Server Agent プロキシアカウントの作成・取得・削除・コピー機能を提供するコマンド群の設計仕様を記述したものです。

### 本画面の処理概要

本機能は、SQL Server Agent のプロキシアカウントを管理します。プロキシアカウントにより、ジョブステップを SQL Agent サービスアカウントとは異なるセキュリティコンテキストで実行できます。

**業務上の目的・背景**：SQL Server Agent ジョブステップの実行権限を細かく制御するため、プロキシアカウントの管理が必要です。セキュリティ監査、コンプライアンスレポート、ジョブステップ実行権限のトラブルシューティングに使用されます。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Get-DbaAgentProxy` - プロキシ設定の取得
- `New-DbaAgentProxy` - プロキシの新規作成
- `Remove-DbaAgentProxy` - プロキシの削除
- `Copy-DbaAgentProxy` - プロキシのインスタンス間コピー

**主要な操作・処理内容**：
1. SQL Server インスタンスからプロキシアカウント一覧を取得
2. 新規プロキシアカウントの作成（資格情報との関連付け）
3. 不要なプロキシアカウントの削除
4. ソースサーバーから宛先サーバーへのプロキシ設定の移行

**画面遷移**：本機能はCLIコマンドであり、他のコマンドとパイプライン連携が可能です。

**権限による表示制御**：sysadmin 権限が必要です。Express Edition では SQL Agent が存在しないため、エラーメッセージが表示されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 492 | Get-DbaAgentProxy | 主機能 | SQLエージェントプロキシの取得 |
| 502 | New-DbaAgentProxy | 主機能 | SQLエージェントプロキシの新規作成 |
| 510 | Remove-DbaAgentProxy | 主機能 | SQLエージェントプロキシの削除 |
| 479 | Copy-DbaAgentProxy | 補助機能 | プロキシのコピー |

## 画面種別

一覧 / 登録 / 削除

## URL/ルーティング

PowerShell コマンドとして提供（CLIベース）

## 入出力項目

### Get-DbaAgentProxy パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Proxy | string[] | No | 取得するプロキシ名（ワイルドカード対応） |
| ExcludeProxy | string[] | No | 除外するプロキシ名 |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Get-DbaAgentProxy 出力

| 項目名 | 説明 |
|--------|------|
| ComputerName | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | SQL Serverインスタンス名 |
| SqlInstance | 完全なSQL Serverインスタンス名 |
| Name | プロキシアカウント名 |
| ID | プロキシID |
| CredentialID | 関連付けられた資格情報ID |
| CredentialIdentity | 資格情報のWindows アカウントID |
| CredentialName | 資格情報名 |
| Description | プロキシの説明 |
| IsEnabled | 有効/無効 |

## イベント仕様

### 1-プロキシ取得

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. Express Editionチェック
3. `$server.Jobserver.ProxyAccounts` からプロキシ一覧を取得
4. `-Proxy` および `-ExcludeProxy` でフィルタリング（ワイルドカード対応）
5. `Select-DefaultView` で整形して出力

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaAgentProxy | msdb.dbo.sysproxies | SELECT | プロキシ設定の取得 |
| New-DbaAgentProxy | msdb.dbo.sysproxies | INSERT | プロキシの新規作成 |
| Remove-DbaAgentProxy | msdb.dbo.sysproxies | DELETE | プロキシの削除 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| Error | Express Edition | "There is no SQL Agent on $server, it's a $($server.Edition)" |
| Error | 接続失敗 | "Failure" (ConnectionError) |

## 備考

- プロキシアカウントは資格情報（Credential）と関連付けられる必要がある
- プロキシはサブシステム（ActiveX Scripting, Operating System等）への権限を付与できる

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentProxy.ps1 | `public/Get-DbaAgentProxy.ps1` | 48-71行: .OUTPUTS セクションでProxyAccountオブジェクト構造を確認 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentProxy.ps1 | `public/Get-DbaAgentProxy.ps1` | 83-91行: パラメータ定義 |
| 2-2 | Get-DbaAgentProxy.ps1 | `public/Get-DbaAgentProxy.ps1` | 109行: $server.Jobserver.ProxyAccountsでプロキシ取得 |

**主要処理フロー**:
- **111-119行**: -Proxyパラメータでワイルドカードフィルタリング
- **121-125行**: -ExcludeProxyパラメータで除外フィルタリング

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

```
Get-DbaAgentProxy
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- Express Editionチェック
    |
    +-- $server.Jobserver.ProxyAccounts (プロキシ一覧取得)
    |
    +-- Filter: -Proxy (Where-Object -like)
    |
    +-- Filter: -ExcludeProxy (Where-Object -notlike)
    |
    +-- Select-DefaultView (出力整形)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentProxy.ps1 | `public/Get-DbaAgentProxy.ps1` | ソース | プロキシ取得のメインコマンド |
| New-DbaAgentProxy.ps1 | `public/New-DbaAgentProxy.ps1` | ソース | プロキシ作成コマンド |
| Remove-DbaAgentProxy.ps1 | `public/Remove-DbaAgentProxy.ps1` | ソース | プロキシ削除コマンド |
| Copy-DbaAgentProxy.ps1 | `public/Copy-DbaAgentProxy.ps1` | ソース | プロキシコピーコマンド |
