# 機能設計書 284-New-DbaEndpoint

## 概要

本ドキュメントは、SQL Server エンドポイントを新規作成する New-DbaEndpoint コマンドの機能設計書です。

### 本機能の処理概要

New-DbaEndpoint は、Database Mirroring、Service Broker、SOAP、T-SQL 通信用の SQL Server エンドポイントを作成する PowerShell コマンドです。

**業務上の目的・背景**：Always On Availability Groups や Database Mirroring を構成するには、インスタンス間の通信を可能にするエンドポイントが必須です。本機能は、これらの高可用性機能のセットアップに必要なエンドポイントを、暗号化設定や認証オプションを含めて一貫した方法で作成します。ポート番号を指定しない場合は自動的に利用可能なポートを選択し、証明書ベースの認証もサポートすることで、セキュアな通信環境を構築できます。

**機能の利用シーン**：
- Always On AG 環境の初期セットアップ
- Database Mirroring パートナーシップの構成
- Service Broker メッセージング環境の構築
- カスタム TCP エンドポイントの作成
- 証明書ベース認証の高可用性環境構築

**主要な処理内容**：
1. 対象 SQL Server インスタンスへの接続確立
2. エンドポイント名の決定（DatabaseMirroring の場合はデフォルト名を使用）
3. 所有者の決定（指定がない場合は sa）
4. 証明書の存在確認（Certificate パラメータ指定時）
5. TCP ポートの決定（指定がない場合は自動生成）
6. SMO Endpoint オブジェクトの作成と設定
7. エンドポイントの作成（Create メソッドまたは証明書付きスクリプト実行）
8. 作成されたエンドポイントの取得と出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を介してエンドポイントを作成します。証明書パラメータ使用時は Get-DbaDbCertificate で証明書の存在を確認します。

**権限による制御**：エンドポイントの作成には sysadmin 権限または CREATE ENDPOINT 権限が必要です。証明書を使用する場合は、証明書への適切なアクセス権も必要です。

## 関連画面

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

## 機能種別

作成操作（CREATE ENDPOINT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象 SQL Server インスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Name | string | No※ | エンドポイント名 | ※DatabaseMirroring 以外では必須 |
| Type | string | No | エンドポイントタイプ | DatabaseMirroring, ServiceBroker, Soap, TSql（デフォルト: DatabaseMirroring） |
| Protocol | string | No | 通信プロトコル | Tcp, NamedPipes, Http, Via, SharedMemory（デフォルト: Tcp） |
| Role | string | No | ミラーリングロール | All, None, Partner, Witness（デフォルト: All） |
| IPAddress | IPAddress | No | リスナーIPアドレス | デフォルト: 0.0.0.0 |
| Port | int | No | リスナーポート番号 | 未指定時は自動生成（5022〜） |
| SslPort | int | No | SSLポート番号（HTTP用） | - |
| Certificate | string | No | 認証用証明書名 | master データベースに存在すること |
| EndpointEncryption | string | No | 暗号化設定 | Disabled, Required, Supported（デフォルト: Required） |
| EncryptionAlgorithm | string | No | 暗号化アルゴリズム | Aes, AesRC4, None, RC4, RC4Aes（デフォルト: Aes） |
| AuthenticationOrder | string | No | 認証方式 | Certificate, Kerberos, Negotiate 等 |
| Owner | string | No | 所有者ログイン名 | 未指定時は sa |
| EnableException | switch | No | 例外スロー有効化 | - |

### 入力データソース

- PowerShell コマンドライン引数
- SQL Server インスタンスの既存エンドポイント情報（ポート自動生成時）
- master データベースの証明書情報（Certificate パラメータ使用時）

## 出力仕様

### 出力データ

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

Get-DbaEndpoint 経由で出力されるため、以下のプロパティが含まれます：

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Server ホスト名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Name | string | エンドポイント名 |
| EndpointType | EndpointType | エンドポイントタイプ |
| ProtocolType | ProtocolType | プロトコルタイプ |
| Owner | string | 所有者 |
| IsAdminOnly | bool | 管理者専用フラグ |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. Name パラメータ検証
   ├─ Type = DatabaseMirroring の場合 → デフォルト名 "hadr_endpoint"
   └─ その他の場合 → Name 必須でエラー
2. 各 SqlInstance に対してループ
   ├─ Connect-DbaInstance で接続
   ├─ Owner 未指定時は Get-SaLoginName で sa ログイン名を取得
   ├─ Certificate 指定時は Get-DbaDbCertificate で存在確認
   └─ Port 未指定時は自動生成
       ├─ 既存エンドポイントの最大ポートを取得
       └─ 最大ポート + 1〜500 のランダムポートを選択
3. SMO Endpoint オブジェクトの作成
   ├─ ProtocolType 設定
   ├─ EndpointType 設定
   ├─ Owner 設定
   └─ TCP プロトコルの場合
       ├─ ListenerIPAddress 設定
       ├─ ListenerPort 設定
       ├─ ServerMirroringRole 設定
       ├─ EndpointEncryption 設定
       ├─ EncryptionAlgorithm 設定
       └─ AuthenticationOrder 設定（指定時）
4. エンドポイント作成
   ├─ Certificate 指定時 → Script() + 証明書句追加 + Query() 実行
   └─ 通常 → $endpoint.Create()
5. サーバーのエンドポイント更新
6. Get-DbaEndpoint で作成されたエンドポイントを取得して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Name 指定あり?}
    B -->|No| C{Type = DatabaseMirroring?}
    C -->|Yes| D[Name = hadr_endpoint]
    C -->|No| E[エラー: Name 必須]
    B -->|Yes| F[SqlInstance ループ開始]
    D --> F
    F --> G[Connect-DbaInstance]
    G --> H{Owner 指定あり?}
    H -->|No| I[Get-SaLoginName]
    H -->|Yes| J{Certificate 指定あり?}
    I --> J
    J -->|Yes| K[Get-DbaDbCertificate]
    K --> L{証明書存在?}
    L -->|No| M[エラー終了]
    L -->|Yes| N{Port 指定あり?}
    J -->|No| N
    N -->|No| O[既存ポートから自動生成]
    N -->|Yes| P[SMO Endpoint 作成]
    O --> P
    P --> Q[Protocol/Type/Owner 設定]
    Q --> R{Protocol = TCP?}
    R -->|Yes| S[TCP 設定<br/>IP, Port, Role,<br/>Encryption 等]
    R -->|No| T{Certificate 指定?}
    S --> T
    T -->|Yes| U[Script() + 証明書句 + Query()]
    T -->|No| V[endpoint.Create()]
    U --> W[Endpoints.Refresh()]
    V --> W
    W --> X[Get-DbaEndpoint で出力]
    X --> F
    F -->|完了| Y[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 名前必須 | DatabaseMirroring 以外では Name パラメータ必須 | Type != DatabaseMirroring |
| BR-002 | デフォルト名 | DatabaseMirroring の場合は "hadr_endpoint" をデフォルト使用 | Type = DatabaseMirroring |
| BR-003 | 所有者デフォルト | 未指定時は sa ログインを使用 | Owner 未指定時 |
| BR-004 | ポート自動生成 | 既存最大ポート + 1〜500 のランダム値 | Port 未指定時 |
| BR-005 | 証明書確認 | 指定された証明書が存在しない場合はエラー | Certificate 指定時 |

### 計算ロジック

ポート自動生成:
```
if 既存ポート = 0:
    tcpPort = 5022
else:
    maxPort = 既存ポートの最大値
    tcpPort = maxPort + Random(1, 500)
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| エンドポイント作成 | sys.endpoints | INSERT | CREATE ENDPOINT 実行 |

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

#### sys.endpoints

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name, endpoint_id, protocol_id, type_id 等 | パラメータで指定された値 | CREATE ENDPOINT |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータ不足 | Name 未指定（DatabaseMirroring 以外） | Name パラメータを指定 |
| - | 接続エラー | SQL Server に接続できない | インスタンス名と認証情報を確認 |
| - | 証明書不在 | 指定された証明書が存在しない | 証明書を作成または名前を確認 |
| - | 作成失敗 | ポート重複、権限不足等 | エラーメッセージを確認 |

### リトライ仕様

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

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

CREATE ENDPOINT は暗黙的トランザクションで実行されます。

## パフォーマンス要件

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

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

- sysadmin 権限または CREATE ENDPOINT 権限が必要
- SQL Server 認証または Windows 認証を使用
- EndpointEncryption デフォルトは Required（暗号化必須）
- EncryptionAlgorithm デフォルトは Aes（最強）
- 証明書ベース認証をサポート

## 備考

- SupportsShouldProcess を実装（-WhatIf, -Confirm 対応）
- ConfirmImpact は Low に設定
- 作成後は Get-DbaEndpoint で結果を取得して出力

---

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

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

### 推奨読解順序

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

SMO Endpoint オブジェクトの構造と設定項目を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaEndpoint.ps1 | `public/New-DbaEndpoint.ps1` | 206-222行目: SMO Endpoint オブジェクトの設定 |

**読解のコツ**: SMO の EndpointType、ProtocolType、EndpointEncryption 等の列挙型を使用してオブジェクトを構成していることを確認します。

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

パラメータ定義とバリデーションを確認します。

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

**主要処理フロー**:
1. **131-155行目**: パラメータ定義（Type, Protocol, Role, Encryption 等）
2. **137-148行目**: ValidateSet による入力値の制限

#### Step 3: エンドポイント作成処理を理解する

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

**主要処理フロー**:
- **157-164行目**: Name パラメータの検証とデフォルト設定
- **173-175行目**: Owner の取得（Get-SaLoginName）
- **177-182行目**: 証明書の存在確認
- **185-201行目**: ポートの自動生成ロジック
- **206-222行目**: SMO オブジェクトの設定
- **223-228行目**: 証明書使用時のスクリプト実行

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

```
New-DbaEndpoint
    │
    └─ foreach SqlInstance
           │
           ├─ Connect-DbaInstance
           │
           ├─ Get-SaLoginName (Owner 未指定時)
           │
           ├─ Get-DbaDbCertificate (Certificate 指定時)
           │
           ├─ Get-DbaEndpoint (ポート自動生成時)
           │      └─ 既存ポートの最大値取得
           │
           ├─ New-Object Microsoft.SqlServer.Management.Smo.EndPoint
           │      ├─ ProtocolType 設定
           │      ├─ EndpointType 設定
           │      ├─ Owner 設定
           │      └─ TCP 設定 (IP, Port, Role, Encryption)
           │
           ├─ [Certificate] Script() + Query()
           │      └─ AUTHENTICATION = CERTIFICATE 追加
           │
           ├─ [通常] endpoint.Create()
           │
           ├─ Endpoints.Refresh()
           │
           └─ Get-DbaEndpoint
                  └─ 作成されたエンドポイント出力
```

### データフロー図

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

SqlInstance ────────┐
                    │
Name ───────────────┼──▶ Name 検証/デフォルト設定
                    │           │
Type ───────────────┤           ▼
                    │    Connect-DbaInstance
Protocol ───────────┤           │
                    │           ▼
Role ───────────────┤    [Owner未指定] Get-SaLoginName
                    │           │
IPAddress ──────────┤           ▼
                    │    [Certificate] Get-DbaDbCertificate
Port ───────────────┤           │
                    │           ▼
Certificate ────────┤    [Port未指定] ポート自動生成
                    │           │
Encryption ─────────┤           ▼
                    │    SMO Endpoint 構成
Owner ──────────────┘           │
                                ▼
                         Create() / Script()+Query()
                                │
                                ▼
                         Get-DbaEndpoint ──▶ パイプライン出力
                         (SMO Endpoint オブジェクト)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaEndpoint.ps1 | `public/New-DbaEndpoint.ps1` | ソース | メイン関数実装 |
| New-DbaEndpoint.Tests.ps1 | `tests/New-DbaEndpoint.Tests.ps1` | テスト | ユニット・統合テスト |
| Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | ソース | エンドポイント取得（依存・出力） |
| Get-DbaDbCertificate.ps1 | `public/Get-DbaDbCertificate.ps1` | ソース | 証明書確認（依存） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続（依存） |
| Start-DbaEndpoint.ps1 | `public/Start-DbaEndpoint.ps1` | ソース | エンドポイント開始（関連） |
