# 通知設計書 7-Get-DbaDbMailHistory

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbaDbMailHistory` コマンドの設計仕様を記述したものである。このコマンドはSQL ServerのDatabase Mailの送信履歴を取得するための機能を提供する。

### 本通知の処理概要

`Get-DbaDbMailHistory` は、SQL ServerのmsdbデータベースからDatabase Mailの送信履歴を取得するPowerShellコマンドである。配信ステータス、受信者、件名、タイムスタンプなど、メール送信に関する包括的な情報を取得できる。

**業務上の目的・背景**：Database Mailの送信履歴は、メール配信の監査、トラブルシューティング、コンプライアンスレポートに不可欠である。このコマンドは、メール配信問題の診断、配信アクティビティの監視、特定期間や特定ステータスのメールの確認に使用される。Sent、Failed、Unsent、Retryingの各ステータスでフィルタリングでき、問題のあるメールの特定を支援する。

**通知の送信タイミング**：このコマンド自体は通知を送信しない。Database Mailの送信履歴を「取得」するための読み取り専用コマンドである。ユーザーが明示的にコマンドを実行したときにのみ動作する。

**通知の受信者**：該当なし（情報取得コマンド）。出力結果はコマンド実行者（通常はDBA）がPowerShellコンソールまたはスクリプト内で受け取る。

**通知内容の概要**：SQL ServerインスタンスごとにPSCustomObjectを返す。このオブジェクトには、ComputerName、InstanceName、SqlInstance、Profile、Recipients、CopyRecipients、BlindCopyRecipients、Subject、Importance、Sensitivity、FileAttachments、AttachmentEncoding、SendRequestDate、SendRequestUser、SentStatus、SentDateが含まれる。

**期待されるアクション**：取得した情報をもとに、DBAは配信状況の確認、失敗メールの診断、配信レポートの作成、監査対応などを行う。

## 通知種別

該当なし - 本コマンドはDatabase Mail送信履歴を取得するための情報取得コマンドであり、通知送信機能は持たない。

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 該当なし（情報取得コマンド） |
| 優先度 | 該当なし |
| リトライ | 該当なし |

### 送信先決定ロジック

該当なし - このコマンドは情報取得専用であり、通知送信は行わない。

## 通知テンプレート

該当なし - 通知送信機能なし。

### メール通知の場合

該当なし

### 本文テンプレート

該当なし

### 添付ファイル

該当なし

## テンプレート変数

該当なし

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 手動実行 | ユーザーがコマンドを実行 | なし | 明示的なコマンド実行でのみ動作 |
| パイプライン入力 | SqlInstanceパラメータへの値 | なし | 複数インスタンスをパイプで処理可能 |

### 送信抑止条件

該当なし（情報取得コマンド）

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[foreach: 各SqlInstanceを処理]
    B --> C[Connect-DbaInstance接続]
    C -->|成功| D[SQLクエリ構築]
    C -->|失敗| E[Stop-Function: ConnectionError]
    D --> F{フィルタパラメータ?}
    F -->|Since指定| G[WHERE句: send_request_date条件追加]
    F -->|Status指定| H[WHERE句: sent_status条件追加]
    G --> H
    H --> I[SQL実行]
    F -->|なし| I
    I --> J[Select-DefaultView: 既定プロパティ選択]
    J --> K[パイプラインに出力]
    K --> L{次のinstance?}
    L -->|Yes| B
    L -->|No| M[終了]
    E --> L
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| msdb.dbo.sysmail_allitems | Database Mail送信履歴 | T-SQLで直接参照 |
| msdb.dbo.sysmail_profile | プロファイル名の解決 | JOINで参照 |

### テーブル別参照項目詳細

#### msdb.dbo.sysmail_allitems

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| mailitem_id | メールアイテムID（MailItemId） | 常に取得 |
| profile_id | プロファイルID | 常に取得 |
| recipients | 宛先（Recipients） | 常に取得 |
| copy_recipients | CC受信者（CopyRecipients） | 常に取得 |
| blind_copy_recipients | BCC受信者（BlindCopyRecipients） | 常に取得 |
| subject | 件名（Subject） | 常に取得 |
| body | 本文（Body） | 常に取得 |
| body_format | 本文形式（BodyFormat: HTML/TEXT） | 常に取得 |
| importance | 重要度（Importance） | 常に取得 |
| sensitivity | 機密性（Sensitivity） | 常に取得 |
| file_attachments | 添付ファイル（FileAttachments） | 常に取得 |
| attachment_encoding | 添付ファイルエンコーディング | 常に取得 |
| query | 添付クエリ（Query） | 常に取得 |
| execute_query_database | クエリ実行DB | 常に取得 |
| attach_query_result_as_file | クエリ結果をファイルとして添付 | 常に取得 |
| query_result_header | クエリ結果ヘッダー | 常に取得 |
| query_result_width | クエリ結果幅 | 常に取得 |
| query_result_separator | クエリ結果セパレータ | 常に取得 |
| exclude_query_output | クエリ出力除外 | 常に取得 |
| append_query_error | クエリエラー追記 | 常に取得 |
| send_request_date | 送信要求日時（SendRequestDate） | 常に取得 |
| send_request_user | 送信要求ユーザー（SendRequestUser） | 常に取得 |
| sent_account_id | 送信アカウントID（SentAccountId） | 常に取得 |
| sent_status | 送信ステータス（SentStatus: Unsent/Sent/Failed/Retrying） | 常に取得 |
| sent_date | 送信日時（SentDate） | 常に取得 |
| last_mod_date | 最終更新日時（LastModDate） | 常に取得 |
| last_mod_user | 最終更新ユーザー（LastModUser） | 常に取得 |

#### msdb.dbo.sysmail_profile

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| profile_id | プロファイルID（JOIN用） | 常に取得 |
| name | プロファイル名（Profile） | 常に取得 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | 読み取り専用コマンド |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ConnectionError | SQL Serverへの接続失敗 | Stop-Functionで警告出力後、次のインスタンスへ継続 |
| Query failure | SQL実行時のエラー | Stop-Functionでメッセージ出力後、次へ継続 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

該当なし（情報取得コマンド）

### 配信時間帯

該当なし

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

- SQL Server への接続には Windows認証、SQL Server認証、Active Directory認証がサポートされる
- SqlCredentialパラメータで代替資格情報を指定可能
- MFAが必要な場合は事前にConnect-DbaInstanceを使用する
- msdbデータベースへの読み取り権限が必要
- 出力にはメール本文、受信者アドレスなどの機密情報が含まれる可能性がある

## 備考

- T-SQLでmsdb.dbo.sysmail_allitemsとsysmail_profileテーブルをJOINしてクエリ
- 出力オブジェクトはPSCustomObject型
- Sinceパラメータで特定日時以降の履歴に限定可能
- Statusパラメータで配信ステータス（Unsent, Sent, Failed, Retrying）にフィルタ可能
- Select-Object *で本文（Body）やクエリ関連の追加プロパティにアクセス可能

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbMailHistory.ps1 | `public/Get-DbaDbMailHistory.ps1` | 行34-73: .OUTPUTSセクションで返却されるオブジェクト型と既定表示プロパティを確認 |

**読解のコツ**: PSCustomObjectを返す。Profile、Recipients、Subject、SentStatus、SentDateなどが既定表示プロパティ。Select-Object *でBody、Query、クエリ関連設定などの追加プロパティにアクセス可能。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbMailHistory.ps1 | `public/Get-DbaDbMailHistory.ps1` | 行102-112: パラメータ定義。SqlInstance、SqlCredential、Since、Status、EnableException |

**主要処理フロー**:
1. **行114**: foreachで各SqlInstanceを処理
2. **行116-120**: Connect-DbaInstanceで接続、失敗時はStop-Functionで継続
3. **行122-160**: SQLクエリを構築（SERVERPROPERTY、sysmail_allitems、sysmail_profileからSELECT）
4. **行162-177**: SinceまたはStatusパラメータ指定時にWHERE句を動的構築
5. **行179**: Write-Messageでデバッグログ出力
6. **行181-185**: $server.Query()でSQL実行、Select-DefaultViewで既定プロパティ選択

#### Step 3: SQLクエリ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbMailHistory.ps1 | `public/Get-DbaDbMailHistory.ps1` | 行122-160: SELECT文の構造とカラムマッピング |

**主要処理フロー**:
- **行122-124**: SERVERPROPERTY関数でComputerName、InstanceName、SqlInstance取得
- **行125-157**: sysmail_allitemsテーブルからメール詳細情報取得
- **行149-154**: CASEステートメントでsent_statusを正規化（小文字→PascalCase）
- **行158-160**: sysmail_profileテーブルとJOINしてプロファイル名を取得

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

```
Get-DbaDbMailHistory
    │
    ├─ Connect-DbaInstance
    │      └─ SMO Server接続確立
    │
    ├─ SQLクエリ動的構築
    │      ├─ 基本SELECT文（JOINあり）
    │      └─ WHERE句（オプション）
    │             ├─ Since条件（send_request_date >=）
    │             └─ Status条件（sent_status IN）
    │
    ├─ $server.Query() (T-SQL実行)
    │
    └─ Select-DefaultView (既定表示プロパティ設定)
```

### データフロー図

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

SqlInstance[]        ───▶  Connect-DbaInstance    ───▶  Server オブジェクト
                                  │
                                  ▼
Since (DateTime)     ───▶  WHERE句構築            ───▶  SQLクエリ文字列
Status (string)      ───▶       │
                                 │
                                 ▼
                          sysmail_allitems        ───▶  メールアイテム情報
                                 │
                                 ├── JOIN ──▶ sysmail_profile ───▶ プロファイル名
                                 │
                                 ▼
                          $server.Query()          ───▶  DataRow コレクション
                                  │
                                  ▼
                          Select-DefaultView       ───▶  PSCustomObject出力
                                                         (パイプライン)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbMailHistory.ps1 | `public/Get-DbaDbMailHistory.ps1` | ソース | メインコマンド実装 |
| Get-DbaDbMailHistory.Tests.ps1 | `tests/Get-DbaDbMailHistory.Tests.ps1` | テスト | Pesterユニットテスト |
| Get-DbaDbMailLog.ps1 | `public/Get-DbaDbMailLog.ps1` | ソース | 関連: イベントログ取得 |
