# 機能設計書 283-Get-DbaEndpoint

## 概要

本ドキュメントは、SQL Server エンドポイントの情報を取得する Get-DbaEndpoint コマンドの機能設計書です。

### 本機能の処理概要

Get-DbaEndpoint は、SQL Server インスタンス上の DatabaseMirroring、ServiceBroker、Soap、TSql タイプのエンドポイントとそのネットワーク構成詳細を取得する PowerShell コマンドです。

**業務上の目的・背景**：高可用性環境（Always On AG、Database Mirroring）やメッセージング環境（Service Broker）のトラブルシューティングでは、エンドポイントの構成と状態を迅速に確認する必要があります。本機能は、接続性の問題診断、セキュリティ監査、構成ドキュメンテーション、ファイアウォール設定の検証などに必要なエンドポイント情報を提供します。DNS名を自動解決し、TCP接続用のFQDN形式の接続文字列を生成することで、ネットワーク到達性の検証を容易にします。

**機能の利用シーン**：
- Always On AG のエンドポイント設定確認
- Database Mirroring の接続トラブルシューティング
- Service Broker のネットワーク構成確認
- セキュリティ監査でのエンドポイントインベントリ作成
- ファイアウォールルール設定前のポート確認
- マイグレーション計画時の現状調査

**主要な処理内容**：
1. 対象 SQL Server インスタンスへの接続確立
2. サーバー上の全エンドポイントの列挙
3. Endpoint パラメータによる名前フィルタリング
4. Type パラメータによるタイプフィルタリング
5. TCP リスナー設定の取得と DNS 解決
6. FQDN 形式の接続文字列生成
7. 拡張プロパティを追加したエンドポイントオブジェクトの出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を介してエンドポイント情報を取得します。System.Net.Dns クラスを使用して DNS 解決を行います。

**権限による制御**：エンドポイント情報の表示には VIEW ANY DEFINITION 権限または sysadmin 権限が必要です。

## 関連画面

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

## 機能種別

データ取得・参照操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象 SQL Server インスタンス | 有効なインスタンス名、SQL Server 2005以降 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Endpoint | string[] | No | 取得するエンドポイント名 | - |
| Type | string[] | No | フィルタするエンドポイントタイプ | DatabaseMirroring, ServiceBroker, Soap, TSql |
| EnableException | switch | No | 例外スロー有効化 | - |

### 入力データソース

- PowerShell コマンドライン引数
- SQL Server インスタンスのエンドポイントメタデータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Server ホスト名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| ID | int | エンドポイント識別子 |
| Name | string | エンドポイント名 |
| IPAddress | IPAddress | リスナーIPアドレス（TCP設定時） |
| Port | int | リスナーポート番号（TCP設定時） |
| EndpointState | EndpointState | エンドポイント状態（Started/Stopped） |
| EndpointType | EndpointType | エンドポイントタイプ |
| Owner | string | 所有者ログイン名 |
| IsAdminEndpoint | bool | 管理エンドポイントフラグ |
| Fqdn | string | TCP接続文字列（TCP://hostname:port形式） |
| IsSystemObject | bool | システムオブジェクトフラグ |

### 出力先

PowerShell パイプライン（Microsoft.SqlServer.Management.Smo.Endpoint オブジェクト、拡張プロパティ付き）

## 処理フロー

### 処理シーケンス

```
1. 各 SqlInstance に対してループ
   └─ Connect-DbaInstance で接続（MinimumVersion 9）
2. サーバーのエンドポイントコレクションを取得
   └─ $server.Endpoints
3. Endpoint パラメータでフィルタリング
   └─ Name -In $Endpoint
4. Type パラメータでフィルタリング
   └─ EndpointType -In $Type
5. 各エンドポイントに対して
   ├─ TCP リスナーポートの存在確認
   ├─ DNS 解決
   │   ├─ ListenerIPAddress が 0.0.0.0 でない場合 → そのIPを使用
   │   ├─ Linux ホストの場合 → server.NetName を使用
   │   ├─ FQDN 形式のコンピュータ名 → そのまま使用
   │   └─ その他 → Dns.GetHostEntry で解決
   └─ FQDN 文字列生成（TCP://dns:port）
6. NoteProperty として追加プロパティを設定
7. Select-DefaultView で出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SqlInstance ループ開始]
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Continue to next instance]
    D -->|Yes| F[Get server.Endpoints]
    F --> G{Endpoint パラメータ<br/>指定あり?}
    G -->|Yes| H[Name でフィルタ]
    G -->|No| I{Type パラメータ<br/>指定あり?}
    H --> I
    I -->|Yes| J[EndpointType でフィルタ]
    I -->|No| K[Endpoint ループ開始]
    J --> K
    K --> L{TCP ListenerPort<br/>存在?}
    L -->|Yes| M{ListenerIPAddress<br/>!= 0.0.0.0?}
    L -->|No| N[Fqdn = null]
    M -->|Yes| O[dns = IPAddress]
    M -->|No| P{Linux ホスト?}
    P -->|Yes| Q[dns = server.NetName]
    P -->|No| R{ComputerName に<br/>. が含まれる?}
    R -->|Yes| S[dns = ComputerName]
    R -->|No| T[Dns.GetHostEntry で解決]
    O --> U[Fqdn = TCP://dns:port]
    Q --> U
    S --> U
    T --> U
    U --> V[Add-Member で拡張プロパティ追加]
    N --> V
    V --> W[Select-DefaultView で出力]
    W --> K
    K -->|完了| B
    E --> B
    B -->|完了| X[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 最小バージョン要件 | SQL Server 2005（バージョン9）以降が必要 | 接続時 |
| BR-002 | DNS 解決優先順位 | IP指定 > Linux NetName > FQDN形式 > DNS解決 | TCP エンドポイント |
| BR-003 | TCPなしスキップ | ListenerPort がない場合は IPAddress, Port, Fqdn は null | 常時 |
| BR-004 | Type 検証 | 指定可能タイプは DatabaseMirroring, ServiceBroker, Soap, TSql のみ | Type パラメータ使用時 |

### 計算ロジック

FQDN生成: `"TCP://" + $dns + ":" + $end.Protocol.Tcp.ListenerPort`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| エンドポイント取得 | sys.endpoints | SELECT | エンドポイント情報の参照 |

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

#### sys.endpoints

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, endpoint_id, state_desc, type_desc 等 | 全エンドポイント | SMO経由で取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Server に接続できない | インスタンス名と認証情報を確認 |
| - | バージョンエラー | SQL Server 2000 以前 | SQL Server 2005以降を使用 |
| - | DNS解決失敗 | ホスト名を解決できない | DNSとネットワーク設定を確認 |

### リトライ仕様

DNS解決失敗時は GetHostAddresses にフォールバックし、それも失敗した場合は ComputerName をそのまま使用します。

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

参照のみのため、トランザクションは不要です。

## パフォーマンス要件

特に定義されていません。DNS解決がボトルネックになる可能性があります。

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

- VIEW ANY DEFINITION 権限または sysadmin 権限が必要
- SQL Server 認証または Windows 認証を使用
- SqlCredential パラメータで資格情報を安全に受け渡し

## 備考

- SQL Server 2005 以降をサポート
- パイプライン入力をサポート（ValueFromPipeline）
- Linux ホストでの DNS 解決にも対応

---

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

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

### 推奨読解順序

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

出力オブジェクトと拡張プロパティの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | 135-145行目: Add-Member による拡張プロパティ追加 |

**読解のコツ**: SMO Endpoint オブジェクトに NoteProperty として追加されるプロパティ（ComputerName, InstanceName, SqlInstance, Fqdn, IPAddress, Port）を確認します。

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

関数の開始点とパラメータ定義を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | パラメータ定義とバリデーション |

**主要処理フロー**:
1. **83-91行目**: パラメータ定義（SqlInstance, Endpoint, Type 等）
2. **88-89行目**: Type パラメータの ValidateSet

#### Step 3: 取得処理と DNS 解決の実装を理解する

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

**主要処理フロー**:
- **100-107行目**: Endpoint と Type パラメータによるフィルタリング
- **111-128行目**: DNS 解決ロジック（条件分岐）
- **130行目**: FQDN 文字列の生成
- **135-145行目**: 拡張プロパティの追加

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

```
Get-DbaEndpoint
    │
    └─ foreach SqlInstance
           │
           ├─ Connect-DbaInstance
           │      └─ MinimumVersion 9 (SQL 2005+)
           │
           ├─ $server.Endpoints
           │
           ├─ [Endpoint] Filter by Name
           │
           ├─ [Type] Filter by EndpointType
           │
           └─ foreach Endpoint
                  │
                  ├─ Check TCP ListenerPort
                  │
                  ├─ DNS Resolution
                  │      ├─ IPAddress (if != 0.0.0.0)
                  │      ├─ server.NetName (Linux)
                  │      ├─ server.ComputerName (FQDN)
                  │      └─ Dns.GetHostEntry()
                  │
                  ├─ Generate FQDN string
                  │
                  ├─ Add-Member (NoteProperties)
                  │
                  └─ Select-DefaultView
```

### データフロー図

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

SqlInstance ────────┐
                    │
SqlCredential ──────┼──▶ Connect-DbaInstance ──▶ $server
                    │           │
Endpoint ───────────┤           ▼
                    │    $server.Endpoints
Type ───────────────┘           │
                                ├──▶ Filter by Name
                                ├──▶ Filter by Type
                                │
                                ▼
                         foreach Endpoint
                                │
                                ├──▶ TCP ListenerPort?
                                │         │
                                │         ▼
                                ├──▶ DNS Resolution
                                │         │
                                │         ▼
                                ├──▶ FQDN = "TCP://dns:port"
                                │
                                ├──▶ Add-Member (ComputerName,
                                │    InstanceName, SqlInstance,
                                │    Fqdn, IPAddress, Port)
                                │
                                └──▶ Select-DefaultView ──▶ パイプライン出力
                                     (SMO Endpoint + NoteProperties)
```

### 関連ファイル一覧

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