# 画面設計書 75-リンクサーバー管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける「リンクサーバー管理」機能の設計書です。SQL Server のリンクサーバーの作成・取得・削除・コピー・エクスポート・接続テストを行うコマンド群について記述します。

### 本画面の処理概要

本機能は、SQL Server のリンクサーバー構成を包括的に管理する機能を提供します。リンクサーバーは、SQL Server から他のOLE DBデータソースへの分散クエリを可能にする重要な機能です。

**業務上の目的・背景**：分散データベース環境において、SQL Server間での分散クエリ、異種データベース（Oracle、MySQL等）へのアクセス、レプリケーション構成など、多くのシナリオでリンクサーバーが使用されます。本機能により、リンクサーバー構成の監査、コンプライアンスレポート作成、接続問題のトラブルシューティング、環境間での構成移行が効率化されます。特にセキュリティ監査では、どのリンクサーバーがどの認証方式を使用しているかを把握することが重要です。

**画面へのアクセス方法**：PowerShellコンソールから `Get-DbaLinkedServer`、`New-DbaLinkedServer`、`Remove-DbaLinkedServer`、`Copy-DbaLinkedServer`、`Export-DbaLinkedServer`、`Test-DbaLinkedServerConnection` コマンドを直接実行します。

**主要な操作・処理内容**：
1. `Get-DbaLinkedServer`: リンクサーバーの一覧取得、リモートサーバー・製品名・認証設定の取得
2. `New-DbaLinkedServer`: リンクサーバーの新規作成
3. `Remove-DbaLinkedServer`: リンクサーバーの削除
4. `Copy-DbaLinkedServer`: インスタンス間でのリンクサーバーのコピー
5. `Export-DbaLinkedServer`: リンクサーバー定義のエクスポート
6. `Test-DbaLinkedServerConnection`: リンクサーバー接続のテスト

**画面遷移**：本機能はCLIコマンドのため画面遷移は存在しません。`Get-DbaLinkedServer` の出力を `Get-DbaLinkedServerLogin` にパイプラインで渡すことで、リンクサーバーのログインマッピングを取得できます。

**権限による表示制御**：リンクサーバー情報の取得には ALTER ANY LINKED SERVER または sysadmin 権限が必要です。リンクサーバーの作成・削除にも同様の権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 348 | Get-DbaLinkedServer | 主機能 | リンクサーバーの取得 |
| 349 | New-DbaLinkedServer | 主機能 | リンクサーバーの作成 |
| 350 | Remove-DbaLinkedServer | 主機能 | リンクサーバーの削除 |
| 346 | Copy-DbaLinkedServer | 補助機能 | リンクサーバーのコピー |
| 347 | Export-DbaLinkedServer | 補助機能 | リンクサーバーのエクスポート |
| 351 | Test-DbaLinkedServerConnection | 補助機能 | リンクサーバー接続のテスト |

## 画面種別

一覧 / 管理（リンクサーバーの一覧取得および管理操作）

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaLinkedServer`
- `New-DbaLinkedServer`
- `Remove-DbaLinkedServer`
- `Copy-DbaLinkedServer`
- `Export-DbaLinkedServer`
- `Test-DbaLinkedServerConnection`

## 入出力項目

### Get-DbaLinkedServer 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| LinkedServer | object[] | No | 取得対象のリンクサーバー名 |
| ExcludeLinkedServer | object[] | No | 除外するリンクサーバー名 |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Get-DbaLinkedServer 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | リンクサーバーの名前 |
| RemoteServer | string | リモートサーバー名（DataSource） |
| ProductName | string | 製品タイプ |
| Impersonate | bool/collection | 偽装が有効かどうか |
| RemoteUser | string | リモートユーザー |
| Publisher | string | ディストリビューションパブリッシャー |
| Distributor | string | ディストリビューター |
| DateLastModified | DateTime | 最終更新日時 |

## イベント仕様

### 1-Get-DbaLinkedServer実行

1. Connect-DbaInstance を使用してSQL Serverに接続
2. $server.LinkedServers からリンクサーバーコレクションを取得
3. LinkedServer パラメータで名前フィルタリング
4. ExcludeLinkedServer パラメータで除外
5. 各リンクサーバーに対して LinkedServerLogins から Impersonate と RemoteUser を取得
6. NoteProperty を追加して出力

### 2-New-DbaLinkedServer実行

1. リンクサーバー名とプロバイダーの指定
2. SMO LinkedServer オブジェクトの作成
3. プロパティの設定（DataSource、ProductName等）
4. Create() メソッドを実行
5. 作成されたリンクサーバーオブジェクトを返却

### 3-Test-DbaLinkedServerConnection実行

1. 対象リンクサーバーの取得
2. TestConnection() メソッドを実行
3. 接続結果（成功/失敗）を返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaLinkedServer実行 | sys.servers | SELECT | リンクサーバー情報の取得 |
| Get-DbaLinkedServer実行 | sys.linked_logins | SELECT | ログインマッピングの取得 |
| New-DbaLinkedServer実行 | sys.servers | INSERT | リンクサーバーの作成 |
| Remove-DbaLinkedServer実行 | sys.servers | DELETE | リンクサーバーの削除 |

### テーブル別更新項目詳細

#### sys.servers

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | server_id, name, product, provider, data_source | is_linked = 1 | Get-DbaLinkedServer |
| INSERT | name, product, provider, data_source | New-DbaLinkedServer | リンクサーバー作成 |
| DELETE | server_id | Remove-DbaLinkedServer | リンクサーバー削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | エラー | Failure | SQL Server接続失敗時 |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| ConnectionError | SQL Serverへの接続失敗 | Stop-Function で処理を停止 |
| LinkedServerInUse | 使用中のリンクサーバーの削除試行 | エラーメッセージを表示 |
| RemoteServerUnreachable | リモートサーバーへの接続失敗 | Test-DbaLinkedServerConnection で失敗として報告 |

## 備考

- リンクサーバーの種類: SQL Server、他のOLE DBソース（Oracle、Access、Excel等）
- LinkedServerLogins プロパティにはローカルログインとリモートユーザーのマッピングが含まれる
- Impersonate が True の場合、現在のユーザーの資格情報を使用してリモートサーバーに接続
- ディストリビューションパブリッシャーおよびディストリビューター情報はレプリケーション構成で使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaLinkedServer.ps1 | `public/Get-DbaLinkedServer.ps1` | 出力プロパティの定義（行44-74） |

**読解のコツ**: SMO LinkedServer オブジェクトに NoteProperty を追加し、LinkedServerLogins から Impersonate と RemoteUser を取得している点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaLinkedServer.ps1 | `public/Get-DbaLinkedServer.ps1` | param ブロック（行86-93）とフィルタリング処理（行104-109） |

**主要処理フロー**:
1. **行97**: Connect-DbaInstance による接続
2. **行102**: $server.LinkedServers でリンクサーバーコレクション取得
3. **行104-108**: LinkedServer, ExcludeLinkedServer によるフィルタリング
4. **行112-116**: NoteProperty の追加（Impersonate, RemoteUser）
5. **行118**: Select-DefaultView で出力整形

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

```
Get-DbaLinkedServer
    |
    +-- Connect-DbaInstance (SQL Server 接続)
    |
    +-- $server.LinkedServers (SMO LinkedServer コレクション)
    |
    +-- Where-Object (フィルタリング)
    |       +-- LinkedServer パラメータ
    |       +-- ExcludeLinkedServer パラメータ
    |
    +-- $ls.LinkedServerLogins (ログインマッピング取得)
    |       +-- Impersonate プロパティ
    |       +-- RemoteUser プロパティ
    |
    +-- Add-Member (NoteProperty 追加)
    |
    +-- Select-DefaultView (出力整形)
```

### データフロー図

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

SqlInstance  ───+
                |
SqlCredential ──+──> Connect-DbaInstance ───> Server Object
                |
LinkedServer ───+──> フィルタリング ──────────> LinkedServer[]
                |
                +──> LinkedServerLogins ─────> Impersonate, RemoteUser

LinkedServer[] ────> Add-Member ────────────> 拡張LinkedServer

拡張LinkedServer ──> Select-DefaultView ───> Pipeline Output
                     (Name, RemoteServer,
                      ProductName, Impersonate,
                      RemoteUser, Publisher,
                      Distributor, DateLastModified)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaLinkedServer.ps1 | `public/Get-DbaLinkedServer.ps1` | ソース | リンクサーバー取得 |
| New-DbaLinkedServer.ps1 | `public/New-DbaLinkedServer.ps1` | ソース | リンクサーバー作成 |
| Remove-DbaLinkedServer.ps1 | `public/Remove-DbaLinkedServer.ps1` | ソース | リンクサーバー削除 |
| Copy-DbaLinkedServer.ps1 | `public/Copy-DbaLinkedServer.ps1` | ソース | リンクサーバーコピー |
| Export-DbaLinkedServer.ps1 | `public/Export-DbaLinkedServer.ps1` | ソース | リンクサーバーエクスポート |
| Test-DbaLinkedServerConnection.ps1 | `public/Test-DbaLinkedServerConnection.ps1` | ソース | 接続テスト |
| Get-DbaLinkedServerLogin.ps1 | `public/Get-DbaLinkedServerLogin.ps1` | ソース | ログインマッピング取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
