# 機能設計書 449-Get-DbaReplSubscription

## 概要

本ドキュメントは、SQL Serverインスタンスのパブリケーションに対するレプリケーションサブスクリプション詳細を取得するdbatools PowerShellコマンドレット `Get-DbaReplSubscription` の機能設計を記述する。

### 本機能の処理概要

Get-DbaReplSubscriptionは、SQL Serverレプリケーションパブリケーションのサブスクリプション情報を取得するコマンドレットである。どのサブスクライバーインスタンスがパブリケーションからデータを受信しているかを示す。

**業務上の目的・背景**：レプリケーション環境において、サブスクリプションの状態とデータ配信先を把握することは、トポロジー監視とトラブルシューティングに不可欠である。この機能により、データベース管理者はサブスクリプションの詳細（サブスクライバー名、サブスクリプションデータベース、タイプ（Push/Pull））を効率的に確認できる。

**機能の利用シーン**：
- レプリケーショントポロジーの監視時にサブスクリプション状態を確認する場面
- 特定のサブスクライバーへのデータ配信状況を確認する場面
- Push/Pullサブスクリプションの区別を行う場面
- サブスクリプション関連の問題のトラブルシューティング

**主要な処理内容**：
1. Connect-DbaInstanceで各SQL Serverインスタンスに接続
2. Get-DbaReplPublicationを呼び出してパブリケーション一覧を取得
3. Database、PublicationNameでパブリケーションをフィルタリング
4. 各パブリケーションのSubscriptionsプロパティからサブスクリプションを取得
5. SubscriberName、SubscriptionDatabase、Typeでフィルタリング
6. 各サブスクリプションにメタデータを追加して出力

**関連システム・外部連携**：
- Get-DbaReplPublicationに依存してパブリケーション情報を取得
- SQL Server Replication Management Objects (RMO) を使用

**権限による制御**：
- SQL Serverインスタンスへのアクセス権限が必要
- レプリケーション構成情報の読み取り権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主画面 | PowerShellコマンドラインから直接実行 |

## 機能種別

データ取得 / 情報参照

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス | 有効なSQL Serverインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | Get-Credentialで取得した有効な認証情報 |
| Database | Object[] | No | フィルタリング対象のパブリケーションデータベース名 | ワイルドカード対応 |
| PublicationName | String[] | No | フィルタリング対象のパブリケーション名 | 複数指定可能 |
| SubscriberName | DbaInstanceParameter[] | No | フィルタリング対象のサブスクライバーインスタンス名 | 有効なSQL Serverインスタンス名 |
| SubscriptionDatabase | Object[] | No | フィルタリング対象のサブスクリプションデータベース名 | 複数指定可能 |
| Type | Object[] | No | サブスクリプションタイプ（Push, Pull） | ValidateSet制約 |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

PowerShellコマンドライン引数、パイプライン入力（SqlInstanceパラメータ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | パブリッシャーのコンピュータ名 |
| InstanceName | string | パブリッシャーのインスタンス名 |
| SqlInstance | string | パブリッシャーの完全なインスタンス名 |
| DatabaseName | string | パブリケーションを含むデータベース名 |
| PublicationName | string | サブスクライブしているパブリケーション名 |
| Name | string | サブスクリプション名 |
| SubscriberName | string | データを受信するサブスクライバーインスタンス名 |
| SubscriptionDBName | string | サブスクライバー上のデータを受信するデータベース名 |
| SubscriptionType | string | サブスクリプション配信タイプ（Push または Pull） |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Replication.Subscriptionオブジェクト）

## 処理フロー

### 処理シーケンス

```
1. processブロック
   └─ Test-FunctionInterruptで中断チェック
   └─ 各SqlInstanceに対してループ
       └─ Connect-DbaInstanceで接続
       └─ Get-DbaReplPublicationでパブリケーション取得
       └─ Databaseパラメータでフィルタリング
       └─ PublicationNameパラメータでフィルタリング
       └─ 各パブリケーションのSubscriptionsを取得
           └─ SubscriberNameでフィルタリング
           └─ SubscriptionDatabaseでフィルタリング
           └─ Typeでフィルタリング
           └─ メタデータを追加
           └─ Select-DefaultViewで9プロパティを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Test-FunctionInterrupt?}
    B -->|Yes| C[終了]
    B -->|No| D[SqlInstanceループ]
    D --> E[Connect-DbaInstance]
    E --> F{接続成功?}
    F -->|No| G[Stop-Function]
    F -->|Yes| H[Get-DbaReplPublication]
    H --> I{Databaseフィルタ?}
    I -->|Yes| J[Databaseフィルタリング]
    I -->|No| K{PublicationNameフィルタ?}
    J --> K
    K -->|Yes| L[PublicationNameフィルタリング]
    K -->|No| M[Subscriptionsループ]
    L --> M
    M --> N{SubscriberNameフィルタ?}
    N -->|Yes| O[SubscriberNameフィルタリング]
    N -->|No| P{SubscriptionDatabaseフィルタ?}
    O --> P
    P -->|Yes| Q[SubscriptionDatabaseフィルタリング]
    P -->|No| R{Typeフィルタ?}
    Q --> R
    R -->|Yes| S[Typeフィルタリング]
    R -->|No| T[メタデータ追加]
    S --> T
    T --> U[Select-DefaultView]
    U --> V{次のSub?}
    V -->|Yes| M
    V -->|No| W{次のInstance?}
    G --> W
    W -->|Yes| D
    W -->|No| C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パブリケーション経由取得 | サブスクリプションはGet-DbaReplPublicationを経由して取得 | 常時 |
| BR-002 | Push/Pullタイプフィルタ | TypeパラメータでPushまたはPullをフィルタリング | Typeパラメータ指定時 |
| BR-003 | サブスクライバー完全一致 | SubscriberNameは完全一致でフィルタリング | SubscriberNameパラメータ指定時 |

### 計算ロジック

特になし（フィルタリングのみ）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| サブスクリプション情報取得 | レプリケーションシステムテーブル | SELECT | RMO経由で読み取り専用アクセス |

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

本機能は読み取り専用操作のため、データベースへの書き込みは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverインスタンスへの接続失敗 | 接続情報を確認し再試行 |
| - | PublicationError | パブリケーション取得失敗 | レプリケーション構成を確認 |
| - | SubscriptionError | サブスクリプション取得失敗 | サブスクリプション構成を確認 |

### リトライ仕様

自動リトライは行わない。Stop-Functionで処理を停止し、-Continueで次のインスタンスの処理を継続する。

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

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

## パフォーマンス要件

パブリケーション数とサブスクリプション数に依存するが、通常は数秒以内に完了する。

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

- 認証情報はPSCredentialとして安全に処理される
- レプリケーション構成情報の読み取りには適切な権限が必要

## 備考

- AgentJobId, AgentSchedule, SynchronizationAgentName, Status, SyncType, SubscriberSecurity, SynchronizationAgentProcessSecurityなどの追加プロパティはSelect-Object *で取得可能
- TypeパラメータのエイリアスとしてPublicationTypeが使用可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaReplPublication.ps1 | `public/Get-DbaReplPublication.ps1` | パブリケーションオブジェクトの構造 |

**読解のコツ**: SubscriptionsプロパティはパブリケーションオブジェクトのArticles/Subscriptionsから取得される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaReplSubscription.ps1 | `public/Get-DbaReplSubscription.ps1` | メインのコマンドレット実装 |

**主要処理フロー**:
1. **130-135行目**: Connect-DbaInstanceで接続
2. **138行目**: Get-DbaReplPublicationでパブリケーション取得
3. **140-146行目**: Database, PublicationNameでフィルタリング
4. **153-165行目**: SubscriberName, SubscriptionDatabase, Typeでフィルタリング
5. **168-171行目**: メタデータ追加
6. **173行目**: Select-DefaultViewで出力

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaReplPublication.ps1 | `public/Get-DbaReplPublication.ps1` | パブリケーション取得 |
| 3-2 | Connect-DbaInstance | - | SQL Server接続 |

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

```
Get-DbaReplSubscription
    │
    ├─ Connect-DbaInstance
    │
    └─ Get-DbaReplPublication
           ├─ Add-ReplicationLibrary
           ├─ Connect-DbaInstance
           └─ Connect-ReplicationDB
```

### データフロー図

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

SqlInstance ──────────────────▶ Connect-DbaInstance ──────────────────▶ Server
                                      │
                               Get-DbaReplPublication
                                      │
Database ─────────────────────▶ Databaseフィルタリング
                                      │
PublicationName ──────────────▶ PublicationNameフィルタリング
                                      │
                               publications.Subscriptions取得
                                      │
SubscriberName ───────────────▶ SubscriberNameフィルタリング
                                      │
SubscriptionDatabase ─────────▶ SubscriptionDatabaseフィルタリング
                                      │
Type ─────────────────────────▶ Typeフィルタリング
                                      │
                               メタデータ追加
                                      │
                               Select-DefaultView
                                      │
                                      ▼
                               Subscriptionオブジェクト（9プロパティ）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaReplSubscription.ps1 | `public/Get-DbaReplSubscription.ps1` | ソース | メインコマンドレット実装 |
| Get-DbaReplPublication.ps1 | `public/Get-DbaReplPublication.ps1` | ソース | パブリケーション取得 |
| Add-ReplicationLibrary.ps1 | `private/functions/Add-ReplicationLibrary.ps1` | ソース | レプリケーションライブラリのロード |
| Get-DbaReplSubscription.Tests.ps1 | `tests/Get-DbaReplSubscription.Tests.ps1` | テスト | ユニットテスト |
