# 画面設計書 190-ポリシー管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるPolicy-Based Management（PBM）ポリシー管理機能の設計を定義する。

### 本画面の処理概要

SQL ServerのPolicy-Based Management機能を使用して、ポリシー、条件、カテゴリの取得と複製を行う。コンプライアンス監査、構成レビュー、環境間での標準化を支援する。

**業務上の目的・背景**：データベース管理者は、SQL Server環境全体でコンプライアンスポリシーの監査、設定の文書化、複数サーバー間でのポリシー標準化が必要である。この機能により、既存のポリシー設定を確認し、サーバー間でポリシーを複製することで、一貫したセキュリティおよび構成基準を維持できる。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行する：
- `Get-DbaPbmPolicy` - ポリシー情報の取得
- `Copy-DbaPolicyManagement` - ポリシー、条件、カテゴリの複製

**主要な操作・処理内容**：
1. Get-DbaPbmStore経由でPBMストアに接続
2. ポリシー、条件、カテゴリ情報を照会
3. フィルタリング（Category、Policy、IsSystemObject）を適用
4. ソースからデスティネーションへのスクリプト転送（Copy時）
5. 結果オブジェクトを出力

**画面遷移**：単独のCLIコマンド群として動作。Get-DbaPbmStoreを内部で使用。

**権限による表示制御**：sysadmin権限が必要（Copy-DbaPolicyManagementの場合）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 281 | Get-DbaPbmPolicy | 主機能 | PBMポリシーの取得 |
| 143 | Copy-DbaPolicyManagement | 補助機能 | PBMオブジェクトの複製 |

## 画面種別

コマンドラインインターフェース（CLI）

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaPbmPolicy`
- `Copy-DbaPolicyManagement`

## 入出力項目

### Get-DbaPbmPolicy パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証用資格情報 |
| Policy | string[] | No | 特定ポリシー名でフィルタ |
| Category | string[] | No | 特定カテゴリ名でフィルタ |
| InputObject | psobject[] | No | パイプライン入力（PBMストアオブジェクト） |
| IncludeSystemObject | switch | No | システムポリシーを含める |
| EnableException | switch | No | 例外を有効にするフラグ |

### Copy-DbaPolicyManagement パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Source | DbaInstanceParameter | Yes | ソースSQL Serverインスタンス |
| SourceSqlCredential | PSCredential | No | ソース接続用資格情報 |
| Destination | DbaInstanceParameter[] | Yes | デスティネーションSQL Serverインスタンス |
| DestinationSqlCredential | PSCredential | No | デスティネーション接続用資格情報 |
| Policy | object[] | No | コピーするポリシー名 |
| ExcludePolicy | object[] | No | 除外するポリシー名 |
| Condition | object[] | No | コピーする条件名 |
| ExcludeCondition | object[] | No | 除外する条件名 |
| Force | switch | No | 既存オブジェクトを上書き |
| EnableException | switch | No | 例外を有効にするフラグ |

## 表示項目

### Get-DbaPbmPolicy 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピューター名 |
| InstanceName | string | インスタンス名 |
| 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 | システムポリシーフラグ |
| ObjectSet | string | 対象オブジェクトセット |
| RootCondition | string | ルート条件 |
| ScheduleUid | guid | スケジュール識別子 |

### 追加プロパティ（Select-Object *で取得可能）

| 項目名 | 説明 |
|--------|------|
| HelpText | ヘルプテキスト |
| HelpLink | ヘルプリンクURL |
| Urn | URN |
| Properties | SMOオブジェクトプロパティコレクション |
| Metadata | オブジェクトメタデータ |
| Parent | 親PolicyStoreオブジェクト参照 |
| IdentityKey | IDキー |
| HasScript | スクリプト参照フラグ |

### Copy-DbaPolicyManagement 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 操作実行日時 |
| SourceServer | string | ソースサーバー名 |
| DestinationServer | string | デスティネーションサーバー名 |
| Name | string | オブジェクト名 |
| Type | string | オブジェクト種別（Policy Category/Policy Condition/Policy） |
| Status | string | 操作結果（Successful/Skipped/Failed） |
| Notes | string | 追加情報 |

## イベント仕様

### 1-ポリシー情報取得（Get-DbaPbmPolicy）

1. Add-PbmLibraryでPBMライブラリをロード
2. SqlInstance指定時はGet-DbaPbmStoreでPBMストア取得
3. store.Policiesからポリシーコレクション取得
4. IncludeSystemObjectでシステムポリシーフィルタ適用
5. Category、Policyパラメータでフィルタリング
6. 各ポリシーにComputerName、InstanceName、SqlInstanceを追加
7. Select-DefaultViewで表示プロパティを設定して出力

### 2-PBMオブジェクト複製（Copy-DbaPolicyManagement）

1. Add-PbmLibraryでPBMライブラリをロード
2. ソースサーバーにConnect-DbaInstance（MinimumVersion 10）
3. ソースPolicyStoreからポリシー、条件取得（IsSystemObject除外）
4. Policy、Conditionパラメータでフィルタリング
5. 各デスティネーションに対して：
   - カテゴリをスクリプト化して転送
   - 条件をスクリプト化して転送（Force時は既存削除）
   - ポリシーをスクリプト化して転送（Force時は既存削除）
6. 各操作結果をPSCustomObjectで出力

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

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

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| ポリシー情報取得 | msdb.dbo.syspolicy_* | SELECT（読み取り） | ポリシー情報の取得 |
| カテゴリ複製 | msdb.dbo.syspolicy_policy_categories | INSERT | カテゴリの作成 |
| 条件複製 | msdb.dbo.syspolicy_conditions | INSERT/DELETE | 条件の作成/削除 |
| ポリシー複製 | msdb.dbo.syspolicy_policies | INSERT/DELETE | ポリシーの作成/削除 |

## メッセージ仕様

| 種別 | メッセージ | 発生条件 |
|------|----------|---------|
| Verbose | Processing $currentpolicy | 各ポリシー処理時 |
| Verbose | Policy '$policyName' was skipped... | 既存ポリシーをスキップ時 |
| Verbose | Copying policy $policyName | ポリシーコピー時 |
| Error | Copy-DbaPolicyManagement does not support Linux | Linuxで実行時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| Linux環境 | Stop-Functionでエラー終了 |
| ソース接続失敗 | Stop-Functionでエラー終了 |
| デスティネーション接続失敗 | Stop-Functionで該当インスタンスをスキップして継続 |
| カテゴリ作成失敗 | ステータスFailedで出力し継続 |
| 条件作成失敗 | ステータスFailedで出力し継続 |
| ポリシー作成失敗 | ステータスFailedで出力し継続 |

## 備考

- SQL Server 2008（バージョン10）以上が必要（Copy-DbaPolicyManagement）
- Copy-DbaPolicyManagementはLinux非対応
- システムポリシー/条件はデフォルトで除外される
- ScriptCreate()メソッドでT-SQLスクリプトを生成して転送
- Forceスイッチで既存オブジェクトを削除して再作成

---

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

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

### 推奨読解順序

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

PBMポリシーオブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaPbmPolicy.ps1 | `public/Get-DbaPbmPolicy.ps1` | .OUTPUTSセクション（行51-93）でプロパティ定義 |
| 1-2 | Copy-DbaPolicyManagement.ps1 | `public/Copy-DbaPolicyManagement.ps1` | .OUTPUTSセクション（行71-84）で出力定義 |

**読解のコツ**: Get-DbaPbmPolicyはMicrosoft.SqlServer.Management.Dmf.Policyオブジェクトを返す。Copy-DbaPolicyManagementはPSCustomObjectを返す。

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

各関数の処理フローを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPbmPolicy.ps1 | `public/Get-DbaPbmPolicy.ps1` | Get-DbaPbmStore呼び出しとフィルタリング処理 |
| 2-2 | Copy-DbaPolicyManagement.ps1 | `public/Copy-DbaPolicyManagement.ps1` | カテゴリ→条件→ポリシーの順序でコピー |

**主要処理フロー（Get-DbaPbmPolicy）**:
1. **行122-124**: beginブロックでAdd-PbmLibrary呼び出し
2. **行126-129**: SqlInstanceからGet-DbaPbmStoreでInputObject取得
3. **行130-131**: store.Policiesからポリシー取得
4. **行133-143**: フィルタリング（SystemObject、Category、Policy）
5. **行145-152**: NoteProperty追加とSelect-DefaultView出力

**主要処理フロー（Copy-DbaPolicyManagement）**:
1. **行124-144**: beginブロックでソース接続とストア取得
2. **行145-173**: processブロックでデスティネーションループ開始
3. **行175-222**: カテゴリの複製処理
4. **行224-291**: 条件の複製処理（Force時は削除後再作成）
5. **行293-361**: ポリシーの複製処理（Force時は削除後再作成）

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

```
Get-DbaPbmPolicy (public/Get-DbaPbmPolicy.ps1)
    │
    ├─ Add-PbmLibrary (内部関数)
    │      └─ PBMライブラリロード
    │
    ├─ Get-DbaPbmStore
    │      └─ PolicyStore取得
    │
    ├─ フィルタリング
    │      ├─ Where-Object IsSystemObject
    │      ├─ Where-Object PolicyCategory
    │      └─ Where-Object Name
    │
    └─ Select-DefaultView
           └─ デフォルト表示プロパティ設定

Copy-DbaPolicyManagement (public/Copy-DbaPolicyManagement.ps1)
    │
    ├─ Add-PbmLibrary
    │
    ├─ Connect-DbaInstance (Source)
    │      └─ MinimumVersion 10
    │
    ├─ New-Object PolicyStore (Source)
    │
    ├─ Connect-DbaInstance (Destination) ループ
    │      │
    │      ├─ New-Object PolicyStore (Destination)
    │      │
    │      ├─ カテゴリ移行
    │      │      └─ ScriptCreate().GetScript()
    │      │
    │      ├─ 条件移行
    │      │      ├─ Drop() (Force時)
    │      │      └─ ScriptCreate().GetScript()
    │      │
    │      └─ ポリシー移行
    │             ├─ Drop() (Force時)
    │             └─ ScriptCreate().GetScript()
    │
    └─ Select-DefaultView
           └─ 結果出力
```

### データフロー図

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

SqlInstance ─────────────▶ Add-PbmLibrary
                                    │
                                    ▼
                           Get-DbaPbmStore
                                    │
                                    ▼
                           PolicyStore.Policies
                                    │
                                    ▼
                           フィルタリング
                           ├─ IsSystemObject
                           ├─ PolicyCategory
                           └─ Policy Name
                                    │
                                    ▼
                           Add-Member
                           (ComputerName, InstanceName, SqlInstance)
                                    │
                                    ▼
                           [Policy Object]
                           ├─ ComputerName
                           ├─ InstanceName
                           ├─ SqlInstance
                           ├─ ID
                           ├─ Name
                           ├─ Enabled
                           ├─ PolicyCategory
                           └─ (その他プロパティ)

Source/Destination ──────▶ カテゴリ/条件/ポリシー複製
                                    │
                                    ▼
                           [PSCustomObject]
                           ├─ DateTime
                           ├─ SourceServer
                           ├─ DestinationServer
                           ├─ Name
                           ├─ Type
                           ├─ Status
                           └─ Notes
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPbmPolicy.ps1 | `public/Get-DbaPbmPolicy.ps1` | ソース | PBMポリシー取得 |
| Copy-DbaPolicyManagement.ps1 | `public/Copy-DbaPolicyManagement.ps1` | ソース | PBMオブジェクト複製 |
| Get-DbaPbmStore.ps1 | `public/Get-DbaPbmStore.ps1` | ソース | PBMストア取得 |
| Get-DbaPbmCategory.ps1 | `public/Get-DbaPbmCategory.ps1` | ソース | PBMカテゴリ取得 |
| Get-DbaPbmCondition.ps1 | `public/Get-DbaPbmCondition.ps1` | ソース | PBM条件取得 |
