# 画面設計書 72-サーバーロール管理

## 概要

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

### 本画面の処理概要

本機能は、SQL Server のサーバーレベルセキュリティロールを包括的に管理する機能を提供します。組み込みの固定サーバーロール（sysadmin、serveradmin等）およびユーザー定義のカスタムサーバーロールの両方を対象とします。

**業務上の目的・背景**：SQL Server環境のセキュリティ管理において、サーバーレベルの権限は最も重要な管理対象です。sysadminやsecurityadminなどの固定ロール、およびカスタムセキュリティ要件に対応するユーザー定義ロールを適切に管理することで、最小権限の原則を実現し、セキュリティコンプライアンスを確保します。本機能により、ロール構成の監査、環境間でのロール複製、セキュリティドキュメント作成が効率化されます。

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

**主要な操作・処理内容**：
1. `Get-DbaServerRole`: サーバーロールの一覧取得、メンバー情報・作成日・所有者情報の取得
2. `New-DbaServerRole`: カスタムサーバーロールの新規作成
3. `Remove-DbaServerRole`: サーバーロールの削除
4. `Copy-DbaServerRole`: インスタンス間でのサーバーロールのコピー
5. `Export-DbaServerRole`: サーバーロール定義のT-SQLスクリプトエクスポート

**画面遷移**：本機能はCLIコマンドのため画面遷移は存在しません。`Connect-DbaInstance` で確立した接続を利用し、`Get-DbaServerRole` の出力を `Get-DbaServerRoleMember` にパイプラインで渡してメンバー詳細を取得できます。

**権限による表示制御**：サーバーロール情報の取得にはサーバーレベルでの適切な権限（VIEW SERVER STATE または securityadmin以上）が必要です。ロールの作成・削除には securityadmin または sysadmin 権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 562 | Get-DbaServerRole | 主機能 | サーバーロールの取得 |
| 571 | New-DbaServerRole | 主機能 | サーバーロールの作成 |
| 579 | Remove-DbaServerRole | 主機能 | サーバーロールの削除 |
| 541 | Copy-DbaServerRole | 補助機能 | サーバーロールのコピー |
| 546 | Export-DbaServerRole | 補助機能 | サーバーロールのエクスポート |

## 画面種別

一覧 / 管理（サーバーロールの一覧取得および管理操作）

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaServerRole`
- `New-DbaServerRole`
- `Remove-DbaServerRole`
- `Copy-DbaServerRole`
- `Export-DbaServerRole`

## 入出力項目

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

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| ServerRole | string[] | No | 取得対象のロール名 |
| ExcludeServerRole | string[] | No | 除外するロール名 |
| ExcludeFixedRole | switch | No | 固定ロールを除外 |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Role | string | サーバーロール名 |
| Login | string[] | ロールメンバーのログイン名配列 |
| Owner | string | ロールの所有者 |
| IsFixedRole | bool | 固定ロールかどうか |
| DateCreated | DateTime | ロール作成日時 |
| DateModified | DateTime | ロール最終更新日時 |

## イベント仕様

### 1-Get-DbaServerRole実行

1. Connect-DbaInstance を使用してSQL Serverに接続（Azure非対応）
2. $server.Roles からサーバーロールコレクションを取得
3. ServerRole パラメータでフィルタリング
4. ExcludeServerRole パラメータで除外
5. ExcludeFixedRole パラメータで固定ロールを除外
6. 各ロールに対して EnumMemberNames() でメンバーを列挙
7. NoteProperty を追加してカスタムオブジェクトとして出力

### 2-New-DbaServerRole実行

1. Connect-DbaInstance を使用してSQL Serverに接続
2. 指定されたロール名でサーバーロールオブジェクトを作成
3. SMO ServerRole オブジェクトの Create() メソッドを実行
4. 作成されたロールオブジェクトを返却

### 3-Remove-DbaServerRole実行

1. 対象ロールの存在確認
2. 固定ロールの削除を防止
3. SMO ServerRole オブジェクトの Drop() メソッドを実行
4. 削除結果を返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaServerRole実行 | sys.server_principals | SELECT | サーバーロール情報の取得 |
| Get-DbaServerRole実行 | sys.server_role_members | SELECT | ロールメンバーシップの取得 |
| New-DbaServerRole実行 | sys.server_principals | INSERT | サーバーロールの作成 |
| Remove-DbaServerRole実行 | sys.server_principals | DELETE | サーバーロールの削除 |

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

#### sys.server_principals

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, type, is_fixed_role, create_date, modify_date | type = 'R'（ロール） | Get-DbaServerRole |
| INSERT | name, type, owning_principal_id | New-DbaServerRole | カスタムロール作成 |
| DELETE | principal_id | Remove-DbaServerRole | カスタムロール削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | エラー | Failure | SQL Server接続失敗時 |
| MSG-002 | 情報 | Getting Server Role Members for $role on $instance | ロールメンバー取得時（Verbose） |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| ConnectionError | SQL Serverへの接続失敗 | Stop-Function で処理を停止 |
| AzureUnsupported | Azure SQL Databaseへの接続 | サポート外のエラーを表示 |
| FixedRoleRemoval | 固定ロールの削除試行 | 削除を拒否しエラーを表示 |

## 備考

- SQL Server 2005 以上をサポート
- Azure SQL Database は非対応
- 固定サーバーロール: sysadmin, serveradmin, securityadmin, processadmin, setupadmin, bulkadmin, diskadmin, dbcreator, public
- ユーザー定義サーバーロールは SQL Server 2012 以上で利用可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaServerRole.ps1 | `public/Get-DbaServerRole.ps1` | 出力オブジェクトの構造（行45-66） |

**読解のコツ**: SMO ServerRole オブジェクトに NoteProperty を追加してカスタマイズしている点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaServerRole.ps1 | `public/Get-DbaServerRole.ps1` | param ブロック（行83-91）とフィルタリング処理（行103-111） |

**主要処理フロー**:
1. **行96**: Connect-DbaInstance による接続（AzureUnsupported）
2. **行101**: $server.Roles でロールコレクション取得
3. **行103-111**: パラメータによるフィルタリング
4. **行114**: EnumMemberNames() でメンバー列挙
5. **行116-124**: NoteProperty の追加

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

```
Get-DbaServerRole
    |
    +-- Connect-DbaInstance (SQL Server 接続)
    |       +-- AzureUnsupported チェック
    |
    +-- $server.Roles (SMO ServerRole コレクション)
    |
    +-- Where-Object (フィルタリング)
    |       +-- ServerRole パラメータ
    |       +-- ExcludeServerRole パラメータ
    |       +-- ExcludeFixedRole パラメータ
    |
    +-- EnumMemberNames() (メンバー列挙)
    |
    +-- Add-Member (NoteProperty 追加)
    |
    +-- Select-DefaultView (出力整形)
```

### データフロー図

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

SqlInstance  ───+
                |
SqlCredential ──+──> Connect-DbaInstance ───> Server Object
                |
ServerRole ─────+──> フィルタリング ──────────> ServerRole[]
                |
                +──> EnumMemberNames() ───────> Login[]

ServerRole[] ───────> Add-Member ────────────> カスタムオブジェクト
                      (NoteProperty追加)

カスタムオブジェクト ─> Select-DefaultView ───> Pipeline Output
```

### 関連ファイル一覧

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