# 通知設計書 6-Get-DbaDbMailLog

## 概要

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

### 本通知の処理概要

`Get-DbaDbMailLog` は、SQL ServerのmsdbデータベースからDatabase Mailイベントログを取得するPowerShellコマンドである。メール送信の試行、失敗、システムイベントに関する詳細情報を取得できる。

**業務上の目的・背景**：Database Mailのイベントログは、メール配信の成功・失敗・警告などの履歴を記録している。このコマンドは、メール配信問題の診断、設定エラーの特定、配信ステータスの監視に不可欠である。Error、Warning、Success、Information、Internalの各イベントタイプを取得でき、問題の根本原因の特定を支援する。

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

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

**通知内容の概要**：SQL ServerインスタンスごとにPSCustomObjectを返す。このオブジェクトには、ComputerName、InstanceName、SqlInstance、LogDate、EventType、Description、Loginが含まれる。

**期待されるアクション**：取得した情報をもとに、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句: log_date条件追加]
    F -->|Type指定| H[WHERE句: event_type条件追加]
    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_event_log | Database Mailイベントログ | T-SQLで直接参照 |

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

#### msdb.dbo.sysmail_event_log

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| log_id | ログエントリ識別子（LogId） | 常に取得 |
| event_type | イベント種別（Error, Warning, Success, Information, Internal） | 常に取得 |
| log_date | ログ記録日時（LogDate） | 常に取得 |
| description | イベント詳細説明 | 常に取得 |
| process_id | プロセスID（ProcessId） | 常に取得 |
| mailitem_id | メールアイテムID（MailItemId） | 常に取得 |
| account_id | アカウントID（AccountId） | 常に取得 |
| last_mod_date | 最終更新日時（LastModDate） | 常に取得 |
| last_mod_user | 最終更新ユーザー（LastModUser, Login） | 常に取得 |

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

該当なし

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

- SQL Server への接続には Windows認証、SQL Server認証、Active Directory認証がサポートされる
- SqlCredentialパラメータで代替資格情報を指定可能
- MFAが必要な場合は事前にConnect-DbaInstanceを使用する
- msdbデータベースへの読み取り権限が必要

## 備考

- T-SQLでmsdb.dbo.sysmail_event_logテーブルを直接クエリ
- 出力オブジェクトはPSCustomObject型
- Sinceパラメータで特定日時以降のログに限定可能
- Typeパラメータでイベント種別（Error, Warning, Success, Information, Internal）にフィルタ可能
- 複数のTypeを同時に指定可能

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: PSCustomObjectを返す。LogDate、EventType、Description、Loginが既定表示プロパティ。Select-Object *で追加プロパティ（LogId、ProcessId、MailItemId、AccountId、LastModDate、LastModUser）にアクセス可能。

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

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

**主要処理フロー**:
1. **行96**: foreachで各SqlInstanceを処理
2. **行98-102**: Connect-DbaInstanceで接続、失敗時はStop-Functionで継続
3. **行104-124**: SQLクエリを構築（SERVERPROPERTY、sysmail_event_logからSELECT）
4. **行126-140**: SinceまたはTypeパラメータ指定時にWHERE句を動的構築
5. **行143**: Write-Messageでデバッグログ出力
6. **行145-148**: $server.Query()でSQL実行、Select-DefaultViewで既定プロパティ選択

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

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

**主要処理フロー**:
- **行104-106**: SERVERPROPERTY関数でComputerName、InstanceName、SqlInstance取得
- **行107-123**: sysmail_event_logテーブルからイベント情報取得
- **行108-115**: CASEステートメントでevent_typeを正規化（小文字→PascalCase）
- **行117**: descriptionから改行+閉じ括弧を削除

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

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

### データフロー図

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

SqlInstance[]        ───▶  Connect-DbaInstance    ───▶  Server オブジェクト
                                  │
                                  ▼
Since (DateTime)     ───▶  WHERE句構築            ───▶  SQLクエリ文字列
Type (string[])      ───▶
                                  │
                                  ▼
                          $server.Query()          ───▶  DataRow コレクション
                                  │
                                  ▼
                          Select-DefaultView       ───▶  PSCustomObject出力
                                                         (パイプライン)
```

### 関連ファイル一覧

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