# 機能設計書 90-Get-DbaAvailabilityGroup

## 概要

本ドキュメントは、dbatools PowerShellモジュールのGet-DbaAvailabilityGroup関数の機能設計を定義する。この関数は、SQL Serverインスタンスから可用性グループの構成と状態情報を取得する機能を提供する。

### 本機能の処理概要

Get-DbaAvailabilityGroup は、SQL Server 2012以降のインスタンスから、可用性グループの詳細情報（レプリカロール、クラスター構成、データベースメンバーシップ、リスナー詳細）を取得するコマンドレットである。AGの健全性監視、フェイルオーバー計画のためのプライマリレプリカ識別、コンプライアンスやトラブルシューティング用のインベントリレポート生成に使用される。

**業務上の目的・背景**：可用性グループはSQL Serverの高可用性機能の中核であり、レプリカの状態監視、プライマリレプリカの特定、データベース同期状態の確認など、日常的な運用タスクが必要となる。本機能は、これらの情報を効率的に取得し、自動化されたフェイルオーバースクリプトやヘルスモニタリングシステムへの統合を可能にする。

**機能の利用シーン**：
- 可用性グループの健全性監視とアラート
- フェイルオーバー計画のためのプライマリレプリカ識別
- 可用性グループ構成のドキュメント化
- 複数インスタンスにわたるAGインベントリ作成
- 自動フェイルオーバースクリプトでのレプリカ状態確認
- コンプライアンス監査用のレポート生成

**主要な処理内容**：
1. SQL Serverインスタンスへの接続（最小バージョン11 = SQL Server 2012）
2. HADRが有効かどうかの確認
3. 可用性グループコレクションの取得
4. 可用性グループ名によるフィルタリング（オプション）
5. プライマリレプリカ判定（IsPrimaryオプション使用時）
6. 結果の出力

**関連システム・外部連携**：
- SQL Server Management Objects (SMO) の AvailabilityGroup クラス
- Windows Server Failover Clustering (WSFC)
- SQL Server HADR サブシステム

**権限による制御**：
- 可用性グループ情報の読み取りには sysadmin 権限が必要
- VIEW SERVER STATE 権限でも一部の情報は取得可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | 可用性グループ管理 | 主機能 | 可用性グループの構成と状態情報を取得 |

## 機能種別

情報取得 / 可用性グループ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | SQL Server 2012以上、パイプライン入力対応 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なPSCredentialオブジェクト |
| AvailabilityGroup | string[] | No | 可用性グループ名でフィルター | ワイルドカード対応 |
| IsPrimary | switch | No | プライマリレプリカかどうかを返す | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- パイプライン入力: SqlInstance をパイプラインから受け取り
- SQL Server: SMO経由で可用性グループ情報を取得

## 出力仕様

### 出力データ（IsPrimary未指定時）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| LocalReplicaRole | string | ローカルレプリカのロール（Primary/Secondary） |
| AvailabilityGroup | string | 可用性グループ名 |
| PrimaryReplica | string | プライマリレプリカのサーバー名 |
| ClusterType | string | クラスタータイプ（Wsfc/External/None） |
| DtcSupportEnabled | bool | DTC サポートの有効状態 |
| AutomatedBackupPreference | string | 自動バックアップ優先設定 |
| AvailabilityReplicas | collection | レプリカコレクション |
| AvailabilityDatabases | collection | データベースコレクション |
| AvailabilityGroupListeners | collection | リスナーコレクション |

### 出力データ（IsPrimary指定時）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| AvailabilityGroup | string | 可用性グループ名 |
| IsPrimary | bool | プライマリレプリカかどうか |

### 出力先

- PowerShellパイプライン: Microsoft.SqlServer.Management.Smo.AvailabilityGroup オブジェクト（カスタムプロパティ追加）

## 処理フロー

### 処理シーケンス

```
1. SqlInstanceのループ処理
   ├─ インスタンスへの接続（最小バージョン11を指定）
   └─ HADR有効確認

2. 可用性グループの取得とフィルタリング
   ├─ AvailabilityGroupsコレクション取得
   └─ AvailabilityGroup名でフィルター

3. 各可用性グループの処理
   ├─ AvailabilityDatabasesのリフレッシュ
   ├─ カスタムプロパティの追加
   └─ IsPrimary判定（オプション）

4. 結果の出力
   └─ Select-DefaultViewでプロパティ設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[インスタンスループ]
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[エラー出力、次へ]
    D -->|Yes| F{HADR有効?}
    F -->|No| G[警告出力、次へ]
    F -->|Yes| H[AvailabilityGroups取得]
    H --> I{AGフィルター指定?}
    I -->|Yes| J[名前でフィルター]
    I -->|No| K[全AG取得]
    J --> L[AGループ]
    K --> L
    L --> M[AvailabilityDatabases.Refresh]
    M --> N[カスタムプロパティ追加]
    N --> O{IsPrimary指定?}
    O -->|Yes| P[IsPrimaryプロパティ追加]
    O -->|No| Q[標準プロパティ設定]
    P --> R[Select-DefaultView]
    Q --> R
    R --> S{次のAG?}
    S -->|Yes| L
    S -->|No| T{次のInstance?}
    E --> T
    G --> T
    T -->|Yes| B
    T -->|No| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 最小バージョン | SQL Server 2012以上が必要 | 常時 |
| BR-002 | HADR必須 | HADRが有効でないインスタンスはスキップ | 常時 |
| BR-003 | IsPrimary判定 | LocalReplicaRole == "Primary" で判定 | IsPrimary指定時 |
| BR-004 | DBリフレッシュ | #9094対応のためAvailabilityDatabasesをリフレッシュ | 常時 |

### 計算ロジック

IsPrimary判定: `$ag.LocalReplicaRole -eq "Primary"`

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

本機能はSMO経由でSQL Serverメタデータを取得する。直接的なT-SQL実行は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverに接続できない | インスタンス名・認証情報を確認 |
| VersionError | バージョンエラー | SQL Server 2012未満 | SQL Server 2012以上を使用 |
| HADRDisabled | 設定エラー | HADRが有効でない | HADRを有効化 |

### リトライ仕様

自動リトライは実装されていない。エラー発生時はStop-Functionで処理を停止し、次のインスタンスの処理を続行する。

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

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

## パフォーマンス要件

- SMO経由のメタデータ取得のため、インスタンスあたり数秒で完了
- AvailabilityDatabases.Refresh() は追加のネットワークラウンドトリップが発生

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

- SqlCredential パラメータで代替認証資格情報を安全に渡すことが可能
- 可用性グループ情報の取得には sysadmin 権限が推奨

## 備考

- 出力オブジェクトはMicrosoft.SqlServer.Management.Smo.AvailabilityGroup型
- カスタムプロパティ（ComputerName、InstanceName、SqlInstance、IsPrimary）が追加される
- Select-Object * で全SMOプロパティにアクセス可能

---

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

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

### 推奨読解順序

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

出力されるSMOオブジェクトとカスタムプロパティを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | 35-71行目の.OUTPUTS セクション |

**読解のコツ**: 出力はMicrosoft.SqlServer.Management.Smo.AvailabilityGroupオブジェクトにカスタムプロパティを追加したもの。

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

パラメータ定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | 108-116行目のparam()ブロック |

**主要処理フロー**:
1. **110-111行目**: SqlInstanceパラメータ（Mandatory、パイプライン対応）
2. **113行目**: AvailabilityGroupパラメータ（配列）
3. **114行目**: IsPrimaryスイッチ

#### Step 3: 接続とHADR確認を理解する

接続処理とHADR有効確認を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | 118-127行目の接続とHADR確認 |

**主要処理フロー**:
- **119-122行目**: Connect-DbaInstanceで接続（MinimumVersion 11指定）
- **125-127行目**: IsHadrEnabledプロパティの確認

#### Step 4: AGフィルタリングとリフレッシュを理解する

可用性グループの取得とフィルタリングを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | 129-137行目のフィルタリング |

**主要処理フロー**:
- **129行目**: AvailabilityGroupsコレクション取得
- **131-133行目**: AvailabilityGroup名でフィルター
- **137行目**: AvailabilityDatabasesのリフレッシュ（#9094対応）

#### Step 5: カスタムプロパティ追加と出力を理解する

カスタムプロパティの追加とSelect-DefaultViewを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | 139-151行目のプロパティ追加と出力 |

**主要処理フロー**:
- **139-141行目**: ComputerName、InstanceName、SqlInstanceプロパティ追加
- **143-146行目**: IsPrimary判定とプロパティ追加（IsPrimary指定時）
- **144行目**: デフォルト表示プロパティ（IsPrimary時）
- **147-149行目**: 標準のデフォルト表示プロパティ

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

```
Get-DbaAvailabilityGroup
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続の確立（MinimumVersion 11）
    │
    ├─ $server.IsHadrEnabled
    │      └─ HADR有効確認
    │
    ├─ $server.AvailabilityGroups
    │      └─ AGコレクション取得
    │
    ├─ $ag.AvailabilityDatabases.Refresh()
    │      └─ DBリスト更新（#9094対応）
    │
    ├─ Add-Member
    │      └─ カスタムプロパティ追加
    │
    └─ Select-DefaultView
           └─ 表示プロパティ設定
```

### データフロー図

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

SqlInstance ───┬──▶ Connect-DbaInstance
               │    (MinimumVersion 11)
               │           │
AvailabilityGroup ─┤       ▼
               │    HADR有効確認
               │           │
IsPrimary ─────┘           ▼
                    AvailabilityGroups取得
                           │
                           ▼
                    AGフィルタリング
                           │
                           ▼
                    各AGの処理
                    ├─ DB Refresh
                    ├─ カスタムプロパティ追加
                    └─ IsPrimary判定（オプション）
                           │
                           ▼
                    Select-DefaultView
                           │
                           ▼
                    SMO.AvailabilityGroup ──────▶ パイプライン出力
                    (カスタムプロパティ付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続ユーティリティ |
| New-DbaAvailabilityGroup.ps1 | `public/New-DbaAvailabilityGroup.ps1` | ソース | AG作成（関連機能） |
| Remove-DbaAvailabilityGroup.ps1 | `public/Remove-DbaAvailabilityGroup.ps1` | ソース | AG削除（関連機能） |
| Set-DbaAvailabilityGroup.ps1 | `public/Set-DbaAvailabilityGroup.ps1` | ソース | AG設定変更（関連機能） |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | 表示プロパティ制御 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラーハンドリング関数 |
