# 機能設計書 559-Get-DbaLinkedServerLogin

## 概要

本ドキュメントは、SQL Serverリンクサーバーのログインマッピング設定を取得する機能について、その処理内容、入出力仕様、および実装詳細を記述した機能設計書である。

### 本機能の処理概要

Get-DbaLinkedServerLoginは、リンクサーバーに設定されているログインマッピング（ローカルログインとリモートユーザーの対応関係）を取得するPowerShellコマンドレットである。リンクサーバー間の認証設定の監査、トラブルシューティング、セキュリティレビューに使用される。

**業務上の目的・背景**：SQL Serverのリンクサーバー機能では、ローカルSQL Serverログインがリモートサーバーにアクセスする際の認証方法を定義する。これらのログインマッピングは、分散クエリやリモートプロシージャ呼び出し時の認証に使用される。セキュリティ監査や認証問題のトラブルシューティングにおいて、これらのマッピング設定を確認することは重要である。

**機能の利用シーン**：
- リンクサーバーセキュリティ監査
- 認証問題のトラブルシューティング
- サーバー間アクセス権限の文書化
- コンプライアンスレポートの作成

**主要な処理内容**：
1. 入力オブジェクト（SqlInstance/Server/LinkedServer）の判定と処理
2. Get-DbaLinkedServerを使用したリンクサーバーオブジェクトの取得
3. LinkedServerLoginsコレクションからログインマッピング取得
4. LocalLogin/ExcludeLocalLoginパラメータによるフィルタリング
5. 各ログインマッピングへのインスタンス情報の付与と出力

**関連システム・外部連携**：
- Get-DbaLinkedServer（リンクサーバー取得）との連携
- Connect-DbaInstance（接続管理）との連携
- SMO LinkedServerLoginオブジェクトの使用

**権限による制御**：リンクサーバー設定の参照には、適切なサーバー権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 76 | リンクサーバーログイン | 主画面 | リンクサーバーログインの取得 |

## 機能種別

データ取得（SELECT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス | 有効なSQL Serverインスタンス名 |
| SqlCredential | PSCredential | No | 接続に使用する代替資格情報 | - |
| LinkedServer | string[] | Conditional | リンクサーバー名（SqlInstance使用時は必須） | - |
| LocalLogin | string[] | No | 取得するローカルログイン名 | - |
| ExcludeLocalLogin | string[] | No | 除外するローカルログイン名 | - |
| InputObject | object[] | No | パイプライン入力（Server/LinkedServer） | SMO Server/LinkedServer型 |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SQL Serverインスタンス
- Get-DbaLinkedServer経由のLinkedServerオブジェクト
- パイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverが稼働するコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | ローカルログイン名 |
| RemoteUser | string | リモートサーバーのユーザー名 |
| Impersonate | bool | 偽装（インパーソネーション）が有効かどうか |

### 出力先

- PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.LinkedServerLogin型）

## 処理フロー

### 処理シーケンス

```
1. パラメータバインディング
   └─ SqlInstance、InputObject、フィルタ条件の受け取り

2. SqlInstance指定時の処理
   └─ LinkedServer必須チェック
   └─ Connect-DbaInstance + Get-DbaLinkedServerでInputObjectに追加

3. InputObjectのループ処理
   ├─ SMO Server型: LinkedServer必須チェック、Get-DbaLinkedServer呼び出し
   └─ SMO LinkedServer型: 直接使用

4. ログインマッピング取得
   └─ $ls.LinkedServerLoginsコレクション参照

5. フィルタリング
   └─ LocalLoginパラメータによる絞り込み
   └─ ExcludeLocalLoginによる除外

6. 結果の出力
   └─ Add-Memberでインスタンス情報追加
   └─ Select-DefaultViewで既定プロパティ選択
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C{LinkedServer指定?}
    C -->|No| D[Stop-Function: LinkedServer必須]
    C -->|Yes| E[Connect + Get-DbaLinkedServer]
    E --> F[InputObjectに追加]
    B -->|No| F
    F --> G{各InputObjectをループ}
    G --> H{オブジェクトタイプ判定}
    H -->|SMO Server| I{LinkedServer指定?}
    I -->|No| J[Stop-Function: LinkedServer必須]
    I -->|Yes| K[Get-DbaLinkedServer]
    K --> L[$ls設定]
    H -->|SMO LinkedServer| L
    L --> M[$ls.LinkedServerLogins取得]
    M --> N{LocalLoginフィルタ?}
    N -->|Yes| O[Name絞り込み]
    N -->|No| P{ExcludeLocalLogin?}
    O --> P
    P -->|Yes| Q[Name除外]
    P -->|No| R{各lsLoginをループ}
    Q --> R
    R --> S[Add-Member: インスタンス情報]
    S --> T[Select-DefaultView]
    T --> R
    R -->|完了| G
    G -->|完了| U[終了]
    D --> U
    J --> U
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | LinkedServer必須 | SqlInstanceまたはSMO Server使用時はLinkedServerパラメータが必須 | SqlInstance/SMO Server指定時 |
| BR-002 | LocalLoginフィルタ | LocalLoginパラメータで名前が一致するもののみ返却 | LocalLogin指定時 |
| BR-003 | ExcludeLocalLoginフィルタ | ExcludeLocalLoginで名前が一致するものを除外 | ExcludeLocalLogin指定時 |
| BR-004 | 複数入力型対応 | SMO Server/LinkedServerの両方を受け付ける | InputObject処理時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ログインマッピング取得 | sys.linked_logins | SELECT | SMO経由でリンクサーバーログイン取得 |

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

#### sys.linked_logins（SMO経由アクセス）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | server_id, local_principal_id, remote_name等 | リンクサーバーごと | SMOのLinkedServerLoginsコレクション経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | SqlInstance/Server指定時にLinkedServerなし | Stop-Functionでメッセージ出力、Continue |

### リトライ仕様

リトライは実装されていない。

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

読み取り専用操作のため、トランザクション制御は不要。

## パフォーマンス要件

- Get-DbaLinkedServerを経由するため、リンクサーバー数に応じた処理時間
- ログインマッピングは通常少数のため、処理は高速

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

- リンクサーバー設定の参照権限が必要
- リモートユーザーの資格情報（パスワード）は取得できない

## 備考

- SupportsShouldProcess、ConfirmImpactが設定されているが、読み取り専用操作
- Get-DbaLinkedServerからパイプライン入力可能

---

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

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

### 推奨読解順序

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

SMO LinkedServerLoginオブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaLinkedServerLogin.ps1 | `public/Get-DbaLinkedServerLogin.ps1` | 出力型（.OUTPUTS）セクション（55-74行目） |

**読解のコツ**: LinkedServerLoginはName（ローカルログイン）、RemoteUser（リモートユーザー）、Impersonate（偽装フラグ）が主要プロパティ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaLinkedServerLogin.ps1 | `public/Get-DbaLinkedServerLogin.ps1` | function宣言とparamブロック（99-109行目） |

**主要処理フロー**:
1. **99-109行目**: パラメータ定義（SupportsShouldProcessあり）
2. **110行目**: processブロック開始
3. **112-118行目**: SqlInstance指定時の処理

#### Step 3: 入力オブジェクト処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaLinkedServerLogin.ps1 | `public/Get-DbaLinkedServerLogin.ps1` | InputObjectループ（120-133行目） |

**主要処理フロー**:
- **121-122行目**: SMO Server型の判定と処理
- **123-128行目**: LinkedServer必須チェック
- **129-130行目**: Get-DbaLinkedServer呼び出し
- **131-133行目**: SMO LinkedServer型の処理

#### Step 4: フィルタリングと出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaLinkedServerLogin.ps1 | `public/Get-DbaLinkedServerLogin.ps1` | フィルタと出力（135-151行目） |

**主要処理フロー**:
- **135行目**: $ls.LinkedServerLoginsで全ログイン取得
- **137-139行目**: LocalLoginフィルタ
- **141-143行目**: ExcludeLocalLoginフィルタ
- **145-150行目**: Add-MemberとSelect-DefaultView

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

```
Get-DbaLinkedServerLogin
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server SMO接続
    │
    ├─ Get-DbaLinkedServer
    │      └─ LinkedServerオブジェクト取得
    │
    ├─ $ls.LinkedServerLogins
    │      └─ ログインマッピングコレクション
    │
    ├─ Where-Object（フィルタリング）
    │
    ├─ Add-Member（プロパティ追加）
    │
    └─ Select-DefaultView（出力整形）
```

### データフロー図

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

SqlInstance ───┐
     +         ├───▶ Get-DbaLinkedServer ───▶ LinkedServer
LinkedServer ──┘            │
      or                    ▼
InputObject ───────▶ $ls.LinkedServerLogins
                            │
                            ▼
              LocalLogin/ExcludeLocalLoginフィルタ
                            │
                            ▼
              Add-Member ───▶ インスタンス情報付与
                            │
                            ▼
              Select-DefaultView ───▶ パイプライン出力
                                             │
                                             ▼
                               LinkedServerLogin Objects
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaLinkedServerLogin.ps1 | `public/Get-DbaLinkedServerLogin.ps1` | ソース | メイン実装 |
| Get-DbaLinkedServer.ps1 | `public/Get-DbaLinkedServer.ps1` | ソース | リンクサーバー取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
