# 機能設計書 423-Get-DbaPbmPolicy

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Get-DbaPbmPolicy`コマンドレットに関する機能設計書である。このコマンドレットは、SQL ServerのPolicy-Based Management（PBM）のポリシーを取得する機能を提供する。

### 本機能の処理概要

`Get-DbaPbmPolicy`は、SQL ServerインスタンスからPolicy-Based Managementのポリシーを取得するコマンドレットである。ポリシーは、条件（Condition）とオブジェクトセットを組み合わせて、データベースオブジェクトのコンプライアンスを評価するためのルールセットを定義する。

**業務上の目的・背景**：Policy-Based Managementは、SQL Server環境全体で一貫した構成標準を維持するための重要な機能である。ポリシーにより、DBAはセキュリティ設定、パフォーマンス構成、命名規則などの企業標準を自動的に監視・強制できる。本機能により、DBAはSQL Server Management Studioを手動で操作することなく、コンプライアンス構成の監査とポリシー設定のレビューを効率的に行うことができる。

**機能の利用シーン**：
- 既存のポリシーをドキュメント化する場合
- ポリシー評価のトラブルシューティングを行う場合
- コンプライアンス構成を検証する場合
- 複数インスタンス間でポリシー構成を比較する場合
- 特定のカテゴリに属するポリシーを監査する場合

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続し、PBMストアを取得する
2. PBMストアからポリシーのコレクションを取得する
3. システムオブジェクトのフィルタリングを適用する（オプション）
4. カテゴリによるフィルタリングを適用する（オプション）
5. ポリシー名によるフィルタリングを適用する（オプション）
6. インスタンス識別情報を付加して結果を出力する

**関連システム・外部連携**：SQL Server Declarative Management Framework（DMF）と連携し、Microsoft.SqlServer.Management.Dmf名前空間のオブジェクトを使用する。

**権限による制御**：PBMストアへのアクセスには、対象SQL Serverインスタンスへの適切な接続権限が必要である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio - Policy Management | 参照画面 | SSMS上でのPolicy-Based Managementポリシーの表示に相当 |

## 機能種別

データ取得（SELECT相当）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス。パイプライン入力可能。 | 有効なSQL Server接続文字列 |
| SqlCredential | PSCredential | No | 代替資格情報。Windows認証、SQL Server認証、AD認証をサポート。 | 有効なPSCredentialオブジェクト |
| Policy | string[] | No | 取得するポリシー名のフィルター。完全一致。 | なし |
| Category | string[] | No | 取得するポリシーカテゴリのフィルター。 | なし |
| InputObject | psobject[] | No | Get-DbaPbmStoreからのパイプライン入力。 | PolicyStoreオブジェクト |
| IncludeSystemObject | switch | No | システムポリシーを結果に含める。 | なし |
| EnableException | switch | No | 例外をスローするモードを有効化。 | なし |

### 入力データソース

- SQL Serverインスタンス直接指定（SqlInstanceパラメータ）
- Get-DbaPbmStoreコマンドからのパイプライン入力（InputObjectパラメータ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（コンピュータ\インスタンス形式） |
| ID | int | ポリシーの一意識別子 |
| Name | string | ポリシー名 |
| Enabled | bool | ポリシーが有効かどうか |
| Description | string | ポリシーの説明 |
| PolicyCategory | string | ポリシーが属するカテゴリ |
| AutomatedPolicyEvaluationMode | string | 自動評価モード（On Demand, On Schedule, On Change, None） |
| Condition | string | ポリシーが強制する条件 |
| CreateDate | DateTime | ポリシーの作成日時 |
| CreatedBy | string | ポリシーを作成したユーザー |
| DateModified | DateTime | ポリシーの最終更新日時 |
| ModifiedBy | string | ポリシーを最後に変更したユーザー |
| IsSystemObject | bool | Microsoftシステムポリシーかどうかを示す |
| ObjectSet | string | ポリシーの対象オブジェクトセット |
| RootCondition | string | ポリシーが評価するルート条件 |
| ScheduleUid | Guid | スケジュール評価を使用する場合のスケジュール識別子 |

### 出力先

- PowerShellパイプライン（標準出力）
- Microsoft.SqlServer.Management.Dmf.Policyオブジェクトとして出力

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   └─ Add-PbmLibrary関数を呼び出し、PBM関連ライブラリをロード
2. processブロック
   ├─ Test-FunctionInterruptでの中断チェック
   ├─ SqlInstanceパラメータの処理
   │   └─ 各インスタンスに対してGet-DbaPbmStoreを呼び出し
   └─ InputObject（PBMストア）の処理
       ├─ ストアから全ポリシーを取得
       ├─ IncludeSystemObjectフィルターの適用
       ├─ Categoryフィルターの適用
       ├─ Policyフィルターの適用
       └─ 各ポリシーにインスタンス情報を追加して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Add-PbmLibrary]
    B --> C{Test-FunctionInterrupt?}
    C -->|Yes| Z[終了]
    C -->|No| D{SqlInstance指定?}
    D -->|Yes| E[Get-DbaPbmStore呼び出し]
    E --> F[InputObjectに追加]
    D -->|No| F
    F --> G[各storeを処理]
    G --> H[全ポリシーを取得]
    H --> I{IncludeSystemObject?}
    I -->|No| J[システムオブジェクト除外]
    I -->|Yes| K{Category指定?}
    J --> K
    K -->|Yes| L[カテゴリでフィルター]
    K -->|No| M{Policy指定?}
    L --> M
    M -->|Yes| N[名前でフィルター]
    M -->|No| O[各ポリシーを処理]
    N --> O
    O --> P[インスタンス情報を追加]
    P --> Q[Select-DefaultViewで出力]
    Q --> R{次のstore?}
    R -->|Yes| G
    R -->|No| Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | システムオブジェクト除外 | デフォルトでシステムポリシーは結果から除外される | IncludeSystemObjectスイッチが指定されていない場合 |
| BR-002 | カテゴリフィルター | PolicyCategoryプロパティで完全一致フィルタリング | Categoryパラメータが指定された場合 |
| BR-003 | ポリシー名フィルター | Nameプロパティで完全一致フィルタリング | Policyパラメータが指定された場合 |

### 計算ロジック

特になし（データ取得機能のため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| PBMポリシー取得 | msdb.dbo.syspolicy_policies | SELECT | PBMポリシーの取得（SMO経由） |

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

#### msdb.dbo.syspolicy_policies（SMO経由）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | policy_id | 全ポリシーを取得 | SMO経由でアクセス |
| SELECT | name | ポリシー名でフィルター可能 | Policyパラメータで指定 |
| SELECT | policy_category | カテゴリでフィルター可能 | Categoryパラメータで指定 |
| SELECT | is_system | システムオブジェクトフィルター | IncludeSystemObjectで制御 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | 接続情報を確認する |

### リトライ仕様

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

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

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

## パフォーマンス要件

特に規定なし。PBMポリシーは通常少数であり、パフォーマンス影響は軽微。

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

- SQL Server認証、Windows認証、Azure AD認証をサポート
- 接続資格情報はPSCredentialオブジェクトで安全に管理
- MFAサポートが必要な場合はConnect-DbaInstanceの事前使用を推奨

## 備考

- SQL Server 2008以降（Version 10以上）が必要
- Policy-Based ManagementはSQL Server Enterprise機能の一部
- 著者はStephen Bennett

---

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

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

### 推奨読解順序

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

PBMポリシーオブジェクトの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaPbmPolicy.ps1 | `public/Get-DbaPbmPolicy.ps1` | .OUTPUTSセクション（51-93行目）で出力オブジェクトの構造を理解 |

**読解のコツ**: Microsoft.SqlServer.Management.Dmf.PolicyはSMOのPBM名前空間に属するオブジェクトである。多くのプロパティはデフォルト表示から除外されているが、Select-Object *でアクセス可能。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPbmPolicy.ps1 | `public/Get-DbaPbmPolicy.ps1` | パラメータ定義（111-121行目）で入力の受け取り方を確認 |

**主要処理フロー**:
1. **122-124行目**: beginブロックでAdd-PbmLibraryを呼び出し
2. **125-126行目**: Test-FunctionInterruptで中断チェック
3. **127-129行目**: SqlInstanceからPBMストアを取得
4. **130-154行目**: ポリシーのフィルタリングと出力処理

#### Step 3: フィルタリングロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaPbmPolicy.ps1 | `public/Get-DbaPbmPolicy.ps1` | 3段階のフィルタリング（133-143行目） |

**主要処理フロー**:
- **133-135行目**: IncludeSystemObjectによるフィルター
- **137-139行目**: Categoryによるフィルター
- **141-143行目**: Policyによるフィルター

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

```
Get-DbaPbmPolicy
    │
    ├─ Add-PbmLibrary
    │      └─ PBMライブラリのロード
    │
    ├─ Test-FunctionInterrupt
    │      └─ 中断チェック
    │
    ├─ Get-DbaPbmStore
    │      ├─ Connect-DbaInstance
    │      │      └─ SQL Server接続
    │      └─ New-Object PolicyStore
    │
    └─ Select-DefaultView
           └─ 出力プロパティの制限
```

### データフロー図

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

SqlInstance ───────▶ Get-DbaPbmStore ───────▶ PolicyStore
                            │
                            ▼
                      store.Policies
                            │
                            ▼
                   IncludeSystemObject
                      フィルター
                            │
                            ▼
                      Category
                      フィルター
                            │
                            ▼
                       Policy名
                      フィルター
                            │
                            ▼
                  Add-Member（インスタンス情報）
                            │
                            ▼
                    Select-DefaultView ───────▶ Policy[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPbmPolicy.ps1 | `public/Get-DbaPbmPolicy.ps1` | ソース | メイン機能の実装 |
| Get-DbaPbmStore.ps1 | `public/Get-DbaPbmStore.ps1` | ソース | PBMストアの取得 |
| Add-PbmLibrary.ps1 | `private/Add-PbmLibrary.ps1` | ソース | PBMライブラリのロード |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Select-DefaultView.ps1 | `private/Select-DefaultView.ps1` | ソース | 出力プロパティの制限 |
