# 画面設計書 117-エンドポイント管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverエンドポイント管理機能の設計仕様を記述する。

### 本画面の処理概要

本機能群は、SQL Serverエンドポイントの取得・作成を行う。エンドポイントは、データベースミラーリング、Service Broker、AlwaysOn可用性グループなどの高可用性機能に必要な通信インターフェースを提供する。

**業務上の目的・背景**：可用性グループやデータベースミラーリングの設定において、インスタンス間通信を可能にするエンドポイントの作成と構成を効率化する。ネットワークトラブルシューティングやセキュリティ監査に必要なエンドポイント情報を簡単に取得できる。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドレットを実行する。
- `Get-DbaEndpoint` - エンドポイントの取得
- `New-DbaEndpoint` - エンドポイントの作成

**主要な操作・処理内容**：
1. 既存エンドポイントの一覧取得と構成確認
2. データベースミラーリング用エンドポイントの作成
3. TCP/IPリスナー構成（IPアドレス、ポート）
4. 暗号化設定（アルゴリズム、必須/任意）
5. 認証順序の設定

**画面遷移**：本機能はコマンドラインインターフェースであり、画面遷移は存在しない。

**権限による表示制御**：エンドポイント作成にはCONTROL SERVER権限またはsysadminロールが必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 119 | Get-DbaEndpoint | 主機能 | エンドポイントの取得 |
| 215 | New-DbaEndpoint | 主機能 | エンドポイントの作成 |

## 画面種別

CLIコマンド群（エンドポイント管理）

## URL/ルーティング

```powershell
# エンドポイント取得
Get-DbaEndpoint -SqlInstance <インスタンス名>

# 特定タイプのエンドポイント取得
Get-DbaEndpoint -SqlInstance <インスタンス名> -Type DatabaseMirroring

# エンドポイント作成（データベースミラーリング用）
New-DbaEndpoint -SqlInstance <インスタンス名> -Type DatabaseMirroring [-Port <ポート>]

# エンドポイント作成（詳細設定）
New-DbaEndpoint -SqlInstance <インスタンス名> -Name <名前> -Type DatabaseMirroring -Port 5055 -IPAddress 192.168.0.15 -EndpointEncryption Required -EncryptionAlgorithm Aes
```

## 入出力項目

### Get-DbaEndpoint パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|---|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 認証資格情報 |
| Endpoint | string[] | No | - | 取得するエンドポイント名 |
| Type | string[] | No | - | DatabaseMirroring/ServiceBroker/Soap/TSql |
| EnableException | switch | No | $false | 例外をスローする |

### New-DbaEndpoint パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|---|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 認証資格情報 |
| Name | string | No | hadr_endpoint | エンドポイント名 |
| Type | string | No | DatabaseMirroring | DatabaseMirroring/ServiceBroker/Soap/TSql |
| Protocol | string | No | Tcp | Tcp/NamedPipes/Http/Via/SharedMemory |
| Role | string | No | All | All/None/Partner/Witness |
| IPAddress | IPAddress | No | 0.0.0.0 | リスナーIPアドレス |
| Port | int | No | (自動生成) | TCPポート番号 |
| SslPort | int | No | - | SSL用ポート |
| Certificate | string | No | - | 認証用証明書名 |
| EndpointEncryption | string | No | Required | Disabled/Required/Supported |
| EncryptionAlgorithm | string | No | Aes | Aes/AesRC4/None/RC4/RC4Aes |
| AuthenticationOrder | string | No | Negotiate | 認証順序 |
| Owner | string | No | sa | エンドポイント所有者 |
| WhatIf | switch | No | - | 実行内容をシミュレート |
| Confirm | switch | No | - | 確認プロンプトを表示 |
| EnableException | switch | No | $false | 例外をスローする |

## 表示項目

### Get-DbaEndpoint 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| ID | int | エンドポイントID |
| Name | string | エンドポイント名 |
| IPAddress | IPAddress | リスナーIPアドレス |
| Port | int | TCPポート番号 |
| EndpointState | string | 状態（Started/Stopped） |
| EndpointType | string | タイプ |
| Owner | string | 所有者ログイン |
| IsAdminEndpoint | bool | 管理エンドポイントフラグ |
| Fqdn | string | TCP://hostname:port形式の接続文字列 |
| IsSystemObject | bool | システムオブジェクトフラグ |

### New-DbaEndpoint 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| (Get-DbaEndpoint出力) | Endpoint | 作成されたエンドポイント |

## イベント仕様

### 1-Get-DbaEndpoint実行

1. Connect-DbaInstanceでMinimumVersion 9（SQL 2005+）接続
2. $server.Endpointsを取得
3. Endpointパラメータでフィルタ
4. Typeパラメータでフィルタ
5. 各エンドポイントについて:
   - TCP ListenerPortがあればFQDN生成
   - DNSからホスト名解決
   - NotePropertyとしてComputerName、IPAddress、Port、Fqdn追加
6. Select-DefaultViewで出力整形

### 2-New-DbaEndpoint実行

1. Name未指定でDatabaseMirroringの場合は"hadr_endpoint"をデフォルト使用
2. Connect-DbaInstanceで接続
3. Owner未指定の場合はGet-SaLoginNameで取得
4. Certificate指定時はGet-DbaDbCertificateで存在確認
5. Port未指定の場合:
   - 既存エンドポイントのポートを調査
   - 最大ポート+ランダム値（1-500）または5022
6. ShouldProcessで確認後:
   - New-Object Microsoft.SqlServer.Management.Smo.EndPointでSMOオブジェクト作成
   - ProtocolType、EndpointType、Ownerを設定
   - TCP設定（IPAddress、Port、Role、Encryption、Algorithm）
   - Certificate使用時はスクリプトを修正してQuery実行
   - それ以外はCreate()メソッド実行
7. Endpoints.Refresh()後、Get-DbaEndpointで結果出力

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

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

| 操作（イベント） | 対象オブジェクト | 操作種別 | 概要 |
|----------------|-----------------|---------|------|
| New Endpoint | sys.endpoints | INSERT | エンドポイント作成 |

### SQL操作詳細

| 操作 | 実行方法 | 備考 |
|-----|---------|------|
| エンドポイント作成 | SMO: Endpoint.Create() | CREATE ENDPOINT相当 |
| 証明書付きエンドポイント | T-SQL: スクリプト修正して実行 | AUTHENTICATION = CERTIFICATE追加 |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 発生条件 |
|---------------|---------------|---------|
| エラー | Name is required when Type is not DatabaseMirroring | 名前未指定で非ミラーリング |
| エラー | Certificate $Certificate does not exist on $instance | 証明書未存在 |
| Verbose | Getting endpoint $name on $server | エンドポイント取得時 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラー出力、Continue |
| 証明書未存在 | Stop-Functionでエラー出力、Continue |
| エンドポイント作成失敗 | Stop-Functionでエラー出力、Continue |

## 備考

- DatabaseMirroringエンドポイントのデフォルト名は"hadr_endpoint"
- デフォルト暗号化はRequired/Aes（セキュリティ重視）
- ポート5022は一般的なミラーリング用ポート
- IPAddress 0.0.0.0は全インターフェースでリッスン
- Roleは可用性グループではAll（全役割）が一般的
- AuthenticationOrderはデフォルトNegotiate
- 証明書ベース認証は異なるドメイン間で使用

---

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

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

### 推奨読解順序

#### Step 1: 出力プロパティを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | 行43-71: .OUTPUTS |
| 1-2 | Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | 行135-145: プロパティ追加と出力整形 |

**読解のコツ**: SMO EndPointオブジェクトにComputerName、Fqdn等を追加してSelect-DefaultViewで整形。

#### Step 2: エンドポイント取得処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | 行92-108: 取得とフィルタ |
| 2-2 | Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | 行109-133: FQDN生成 |

**主要処理フロー**:
1. **行95**: MinimumVersion 9（SQL 2005+）で接続
2. **行100-107**: EndpointおよびTypeでフィルタ
3. **行111-133**: TCPリスナーからFQDN生成（DNS解決含む）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaEndpoint.ps1 | `public/New-DbaEndpoint.ps1` | 行157-164: デフォルト名設定 |
| 3-2 | New-DbaEndpoint.ps1 | `public/New-DbaEndpoint.ps1` | 行185-202: ポート自動生成 |
| 3-3 | New-DbaEndpoint.ps1 | `public/New-DbaEndpoint.ps1` | 行204-232: エンドポイント作成 |

**主要処理フロー**:
1. **行157-163**: DatabaseMirroringならhadr_endpoint
2. **行173-175**: Owner未指定ならsaを使用
3. **行185-202**: ポート未指定なら既存最大+ランダムまたは5022
4. **行206-222**: SMOオブジェクト作成とプロパティ設定
5. **行223-229**: Certificate使用時はスクリプト修正

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

```
Get-DbaEndpoint
    │
    +-- Connect-DbaInstance (MinimumVersion 9)
    │
    +-- $server.Endpoints
    │       └─ Where-Object Name -In $Endpoint
    │       └─ Where-Object EndpointType -In $Type
    │
    +-- foreach ($end in $endpoints)
    │       │
    │       +-- FQDN生成
    │       │       ├─ IPAddress != 0.0.0.0 → IP使用
    │       │       ├─ Linux + NetName → NetName使用
    │       │       ├─ ComputerName.含む → そのまま
    │       │       └─ DNS解決 → FQDN
    │       │
    │       +-- Add-Member (ComputerName, Fqdn, IPAddress, Port)
    │       │
    │       └── Select-DefaultView
    │
    └── 出力

New-DbaEndpoint
    │
    +-- Name設定
    │       └─ DatabaseMirroringならhadr_endpoint
    │
    +-- Connect-DbaInstance
    │
    +-- Owner設定
    │       └─ Get-SaLoginName
    │
    +-- Certificate確認
    │       └─ Get-DbaDbCertificate
    │
    +-- Port決定
    │       ├─ 指定あり → そのまま
    │       └─ 指定なし → 既存最大+ランダム or 5022
    │
    +-- New-Object Endpoint
    │       ├─ ProtocolType設定
    │       ├─ EndpointType設定
    │       ├─ Owner設定
    │       └─ TCP設定 (IP, Port, Role, Encryption)
    │
    +-- Create() or Query(スクリプト)
    │
    +-- Endpoints.Refresh()
    │
    └── Get-DbaEndpoint -Endpoint $name
```

### データフロー図

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

SqlInstance ─────────────> Connect-DbaInstance ─────────────────>
                           $server.Endpoints ──────────────────> Endpoint[]
Endpoint/Type ───────────> Where-Object フィルタ ──────────────>
                           Add-Member (Fqdn, etc) ─────────────>

Name ────────────────────> デフォルト名決定 ───────────────────>
Type ────────────────────>     (hadr_endpoint)
Port ────────────────────> ポート決定 ─────────────────────────>
IPAddress ───────────────>     (5022 or 既存最大+ランダム)
EndpointEncryption ──────> New-Object Endpoint ────────────────>
EncryptionAlgorithm ─────> Create() ───────────────────────────> Endpoint
Certificate ─────────────> Query(スクリプト) ──────────────────>
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | ソース | エンドポイント取得 |
| New-DbaEndpoint.ps1 | `public/New-DbaEndpoint.ps1` | ソース | エンドポイント作成 |
| Get-DbaDbCertificate.ps1 | `public/Get-DbaDbCertificate.ps1` | ソース | 証明書確認（依存） |
