# 機能設計書 286-Set-DbaEndpoint

## 概要

本ドキュメントは、SQL Server エンドポイントのプロパティを変更する Set-DbaEndpoint コマンドの機能設計書です。

### 本機能の処理概要

Set-DbaEndpoint は、既存の SQL Server エンドポイントの所有者やタイプなどのプロパティを変更する PowerShell コマンドです。

**業務上の目的・背景**：セキュリティ監査やコンプライアンス要件により、エンドポイントの所有者を個人アカウントからサービスアカウントに変更したり、環境全体でエンドポイント所有者を標準化したりする必要があります。本機能は、これらの管理作業を効率化し、特定のエンドポイントまたは全エンドポイントに対して一括でプロパティ変更を適用できます。

**機能の利用シーン**：
- セキュリティ監査時のエンドポイント所有者変更
- サービスアカウント移行に伴う所有者更新
- 環境全体でのエンドポイント設定標準化
- エンドポイントタイプの変更（ServiceBroker から TSql 等）
- 複数サーバーへの一括設定変更

**主要な処理内容**：
1. 変更対象エンドポイントの特定（名前指定、全件指定、パイプライン入力）
2. 指定されたプロパティ（Owner, Type）の更新
3. Alter() メソッドによる変更のコミット
4. 更新されたエンドポイントオブジェクトの出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を介してエンドポイントを変更します。Get-DbaEndpoint と組み合わせて使用されることが多いです。

**権限による制御**：エンドポイントの変更には sysadmin 権限または CONTROL 権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SSMS Server Objects > Endpoints | 参照画面 | エンドポイント確認 |
| - | PowerShell Console | 主画面 | コマンド実行 |

## 機能種別

更新操作（ALTER ENDPOINT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象 SQL Server インスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Endpoint | string[] | No | 変更するエンドポイント名 | SqlInstance 使用時は必須（AllEndpoints と排他） |
| Owner | string | No | 新しい所有者ログイン名 | - |
| Type | string | No | 新しいエンドポイントタイプ | DatabaseMirroring, ServiceBroker, Soap, TSql |
| AllEndpoints | switch | No | 全エンドポイント変更フラグ | SqlInstance 使用時は必須（Endpoint と排他） |
| InputObject | Microsoft.SqlServer.Management.Smo.Endpoint[] | No | パイプライン入力されたエンドポイントオブジェクト | - |
| EnableException | switch | No | 例外スロー有効化 | - |

### 入力データソース

- PowerShell コマンドライン引数
- Get-DbaEndpoint からのパイプライン入力
- SQL Server インスタンスのエンドポイントメタデータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Microsoft.SqlServer.Management.Smo.Endpoint | SMO オブジェクト | 更新されたエンドポイントオブジェクト |

### 出力先

PowerShell パイプライン（Microsoft.SqlServer.Management.Smo.Endpoint オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstance 使用時は Endpoint または AllEndpoints が必要
2. SqlInstance からエンドポイントを取得
   └─ Get-DbaEndpoint で対象を特定し InputObject に追加
3. 各エンドポイントに対して更新処理
   ├─ ShouldProcess で確認
   ├─ Owner パラメータ指定時 → $ep.Owner を更新
   ├─ Type パラメータ指定時 → $ep.EndpointType を更新
   ├─ Alter() メソッド実行
   └─ 更新されたエンドポイントオブジェクト出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance 指定?}
    B -->|Yes| C{Endpoint or AllEndpoints<br/>指定あり?}
    C -->|No| D[エラー終了]
    C -->|Yes| E[Get-DbaEndpoint で取得]
    B -->|No| F[InputObject ループ開始]
    E --> F
    F --> G{ShouldProcess?}
    G -->|No| F
    G -->|Yes| H{Owner 指定?}
    H -->|Yes| I[$ep.Owner = Owner]
    H -->|No| J{Type 指定?}
    I --> J
    J -->|Yes| K[$ep.EndpointType = Type]
    J -->|No| L[$ep.Alter]
    K --> L
    L --> M{成功?}
    M -->|Yes| N[エンドポイント出力]
    M -->|No| O[Stop-Function]
    N --> F
    O --> F
    F -->|完了| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パラメータ必須チェック | SqlInstance 使用時は Endpoint または AllEndpoints が必要 | SqlInstance 指定時 |
| BR-002 | Type マッピング | Type パラメータは EndpointType プロパティにマッピング | Type 指定時 |
| BR-003 | 条件付き更新 | Owner, Type のいずれかが指定された場合のみ Alter() 実行 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| エンドポイント更新 | sys.endpoints | UPDATE | ALTER ENDPOINT 実行 |

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

#### sys.endpoints

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | principal_id | 新しい所有者の principal_id | Owner パラメータ指定時 |
| UPDATE | type_id | 新しいタイプの type_id | Type パラメータ指定時 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータ不足 | SqlInstance 使用時に Endpoint/AllEndpoints 未指定 | Endpoint または AllEndpoints を指定 |
| - | 更新失敗 | 権限不足、無効な Owner 等 | エラーメッセージを確認 |

### リトライ仕様

リトライは実装されていません。失敗時は Stop-Function でエラー出力して続行します。

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

各エンドポイントの Alter() は独立したトランザクションとして実行されます。

## パフォーマンス要件

特に定義されていません。

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

- sysadmin 権限または CONTROL 権限が必要
- SQL Server 認証または Windows 認証を使用

## 備考

- SupportsShouldProcess を実装（-WhatIf, -Confirm 対応）
- ConfirmImpact は Low に設定
- SMO Endpoint オブジェクトをそのまま出力

---

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

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

### 推奨読解順序

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

プロパティマッピングの処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaEndpoint.ps1 | `public/Set-DbaEndpoint.ps1` | 106-119行目: プロパティ更新ロジック |

**読解のコツ**: Type パラメータが EndpointType プロパティにマッピングされる仕組みを確認します。

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

パラメータ定義を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaEndpoint.ps1 | `public/Set-DbaEndpoint.ps1` | パラメータ定義 |

**主要処理フロー**:
1. **84-96行目**: パラメータ定義（Endpoint, Owner, Type, AllEndpoints, InputObject 等）
2. **90-91行目**: Type パラメータの ValidateSet

#### Step 3: 更新処理の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaEndpoint.ps1 | `public/Set-DbaEndpoint.ps1` | process ブロックのメインロジック |

**主要処理フロー**:
- **98-101行目**: パラメータ検証
- **102-104行目**: Get-DbaEndpoint でエンドポイント取得
- **106行目**: 変更対象プロパティの定義
- **107-122行目**: プロパティ更新と Alter() 実行

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

```
Set-DbaEndpoint
    │
    ├─ パラメータ検証
    │      └─ SqlInstance 使用時は Endpoint/AllEndpoints 必須
    │
    ├─ [SqlInstance] Get-DbaEndpoint
    │      └─ 対象エンドポイント取得
    │
    └─ foreach Endpoint
           │
           ├─ ShouldProcess 確認
           │
           ├─ foreach Property (Owner, Type)
           │      ├─ [Type] realprop = EndpointType
           │      └─ $ep.$prop = 新しい値
           │
           ├─ $ep.Alter()
           │
           └─ $ep 出力
```

### データフロー図

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

SqlInstance ────────┐
                    │
SqlCredential ──────┼──▶ Get-DbaEndpoint ──▶ InputObject
                    │           │
Endpoint ───────────┤           │
                    │           │
AllEndpoints ───────┤           │
                    │           │
Owner ──────────────┤           ▼
                    │    foreach Endpoint
Type ───────────────┤           │
                    │           ├──▶ ShouldProcess?
InputObject ────────┘           │
                                ├──▶ [Owner] $ep.Owner = Owner
                                │
                                ├──▶ [Type] $ep.EndpointType = Type
                                │
                                └──▶ $ep.Alter()
                                          │
                                          ▼
                                   SMO Endpoint ──▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaEndpoint.ps1 | `public/Set-DbaEndpoint.ps1` | ソース | メイン関数実装 |
| Set-DbaEndpoint.Tests.ps1 | `tests/Set-DbaEndpoint.Tests.ps1` | テスト | ユニット・統合テスト |
| Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | ソース | エンドポイント取得（依存） |
| New-DbaEndpoint.ps1 | `public/New-DbaEndpoint.ps1` | ソース | エンドポイント作成（関連） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続（依存） |
