# 機能設計書 298-Get-DbaSsisExecutionHistory

## 概要

本ドキュメントは、SSISカタログデータベース（SSISDB）からSSISパッケージの実行履歴を取得するGet-DbaSsisExecutionHistory機能について記述する。

### 本機能の処理概要

Get-DbaSsisExecutionHistoryは、SQL Server Integration Services（SSIS）カタログデータベースのcatalog.executionsビューをクエリし、パッケージ実行履歴の詳細情報を取得するコマンドレットである。実行ステータス、タイミング、環境情報などの包括的な実行情報を提供する。

**業務上の目的・背景**：SSISパッケージは企業のデータ統合処理において重要な役割を担っている。パッケージの失敗、長時間実行、実行パターンの変化などを監視することは運用上不可欠である。SSISDBを直接クエリするには専門知識が必要であり、結果の解釈も複雑である。本機能はSSISDB へのアクセスを簡素化し、失敗したパッケージの特定、パフォーマンス監視、SSISワークロードの分析を容易にする。

**機能の利用シーン**：
- 失敗したSSISパッケージの調査
- 長時間実行パッケージの特定
- 実行パターンの時系列分析
- SSISデプロイメント後の監視
- 定期的なSSIS健全性チェック
- コンプライアンス監査のための実行ログ取得

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. SSISDBデータベースのcatalog.executionsビューをクエリ
3. フィルタ条件（Project、Folder、Environment、Status、Since）の適用
4. 実行ステータスコードの文字列変換
5. 構造化されたPSCustomObjectの出力

**関連システム・外部連携**：SQL Server Integration Services（SSIS）カタログ。SSISDBデータベースが必要。

**権限による制御**：SSISDBデータベースへの読み取り権限が必要。catalog.executionsビューへのアクセス権が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 204 | SSIS実行履歴 | 主機能 | SSIS実行履歴の取得 |

## 機能種別

データ取得 / 監視・分析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | SSISDBが存在すること |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| Project | string[] | No | フィルタ対象プロジェクト名 | - |
| Folder | string[] | No | フィルタ対象フォルダ名 | - |
| Environment | string[] | No | フィルタ対象環境名 | - |
| Status | string[] | No | フィルタ対象ステータス | Created/Running/Cancelled/Failed/Pending/Halted/Succeeded/Stopping/Completed |
| Since | datetime | No | 開始日時フィルタ（以降） | - |
| EnableException | switch | No | 例外を有効にする | - |

### 入力データソース

- SSISDB.catalog.executions（実行履歴）
- SSISDB.catalog.execution_parameter_values（ログレベル）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ExecutionID | long | 実行ID |
| FolderName | string | SSISDBカタログフォルダ名 |
| ProjectName | string | SSISプロジェクト名 |
| PackageName | string | SSISパッケージ名 |
| ProjectLsn | long | プロジェクトLSN（デプロイバージョン） |
| Environment | string | 環境名（folder\environment形式） |
| StatusCode | string | ステータス文字列 |
| StartTime | dbadatetime | 開始日時 |
| EndTime | dbadatetime | 終了日時 |
| ElapsedMinutes | int | 経過時間（分） |
| LoggingLevel | int | ログレベル |

### 出力先

パイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメータからSQLパラメータのハッシュテーブル構築（begin）
   └─ Status → ステータスコード変換
   └─ Project/Folder/Environment → パラメータ化クエリ構築
   └─ Since → 日時フィルタ追加
2. SQLクエリの構築
   └─ CTE（ログレベル、ステータスコード）
   └─ メインクエリ（catalog.executions）
   └─ 動的WHERE句
3. クエリ実行（process）
4. 結果のdbaDateTime変換
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータハッシュテーブル構築]
    B --> C{Status指定?}
    C -->|Yes| D[ステータスコード変換]
    C -->|No| E{Project指定?}
    D --> E
    E -->|Yes| F[Project WHERE句追加]
    E -->|No| G{Folder指定?}
    F --> G
    G -->|Yes| H[Folder WHERE句追加]
    G -->|No| I{Environment指定?}
    H --> I
    I -->|Yes| J[Environment WHERE句追加]
    I -->|No| K{Since指定?}
    J --> K
    K -->|Yes| L[日時フィルタ追加]
    K -->|No| M[SQLクエリ組み立て]
    L --> M
    M --> N{各インスタンスループ}
    N --> O[Invoke-DbaQuery実行]
    O --> P[StartTime/EndTime変換]
    P --> Q[出力]
    Q --> N
    N -->|完了| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ステータスコード変換 | 1:Created, 2:Running, 3:Cancelled, 4:Failed, 5:Pending, 6:Halted, 7:Succeeded, 8:Stopping, 9:Completed | 常時 |
| BR-002 | 環境フォーマット | environment_folder_name\environment_name形式 | 環境使用時 |
| BR-003 | パラメータ化クエリ | SQLインジェクション防止のためパラメータ化 | 常時 |
| BR-004 | 経過時間計算 | DATEDIFF(mi, start_time, end_time) | 常時 |

### 計算ロジック

- ElapsedMinutes = DATEDIFF(mi, start_time, end_time)
- Environment = ISNULL(environment_folder_name, '') + ISNULL('\' + environment_name, '')

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 実行履歴取得 | SSISDB.catalog.executions | SELECT | 実行履歴 |
| ログレベル取得 | SSISDB.catalog.execution_parameter_values | SELECT | ログレベル |

### テーブル別操作詳細

#### catalog.executions

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | execution_id, folder_name, project_name, package_name, project_lsn, environment_folder_name, environment_name, status, start_time, end_time | フィルタ条件による | LEFT OUTER JOINでログレベルと結合 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| SSISDBNotFound | データベースエラー | SSISDBが存在しない | SSISカタログのデプロイ確認 |
| ConnectionError | 接続エラー | インスタンスに接続できない | 接続情報の確認 |

### リトライ仕様

リトライ処理なし。

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

読み取り専用操作。トランザクション制御なし。OPTION (RECOMPILE)ヒント使用。

## パフォーマンス要件

OPTION (RECOMPILE)ヒントにより、フィルタ条件に最適化されたプランを使用。

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

- SSISDBへの読み取り権限が必要
- パラメータ化クエリによりSQLインジェクションを防止
- 出力にはパッケージ名やプロジェクト情報が含まれる

## 備考

- SSISDBが存在しない場合はエラーとなる
- Status値はValidateSetで制限されている
- 日時フィールドはdbadatetime型に変換される

---

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

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

### 推奨読解順序

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

ステータスコードのマッピングとSQLパラメータ構築を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaSsisExecutionHistory.ps1 | `public/Get-DbaSsisExecutionHistory.ps1` | ステータスマッピング（116-126行目） |

**読解のコツ**: $statusesハッシュテーブルでステータス文字列をコードに変換している。

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

beginブロックでのパラメータ構築とSQLクエリ組み立てを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaSsisExecutionHistory.ps1 | `public/Get-DbaSsisExecutionHistory.ps1` | beginブロック（112-236行目） |

**主要処理フロー**:
1. **113行目**: $paramsハッシュテーブルの初期化
2. **116-132行目**: Status パラメータの処理
3. **135-174行目**: Project/Folder/Environment のパラメータ化
4. **177-180行目**: Since 日時フィルタ
5. **182-230行目**: CTEを含むSQLクエリの組み立て

#### Step 3: 実行処理を理解する

processブロックでのクエリ実行と結果変換を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaSsisExecutionHistory.ps1 | `public/Get-DbaSsisExecutionHistory.ps1` | processブロック（239-248行目） |

**主要処理フロー**:
- **241行目**: Invoke-DbaQueryでSSISDBにクエリ実行
- **243-244行目**: StartTime/EndTimeをdbadatetime型に変換

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

```
Get-DbaSsisExecutionHistory
    │
    ├─ begin
    │      │
    │      ├─ $params = @{} 初期化
    │      │
    │      ├─ Status処理
    │      │      └─ $statuses[$Status] → ステータスコード
    │      │
    │      ├─ Project処理
    │      │      └─ パラメータ化WHERE句追加
    │      │
    │      ├─ Folder処理
    │      │      └─ パラメータ化WHERE句追加
    │      │
    │      ├─ Environment処理
    │      │      └─ パラメータ化WHERE句追加
    │      │
    │      ├─ Since処理
    │      │      └─ 日時フィルタ追加
    │      │
    │      └─ SQLクエリ組み立て
    │             ├─ CTE (cteLoglevel)
    │             ├─ CTE (cteStatus)
    │             └─ メインSELECT
    │
    └─ process
           │
           └─ foreach $instance
                  │
                  ├─ Invoke-DbaQuery
                  │      ├─ Database: SSISDB
                  │      └─ SqlParameters: $params
                  │
                  └─ foreach $row
                         └─ dbadatetime変換
```

### データフロー図

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

Parameters ─────────────────▶ パラメータハッシュ構築
(Project/Folder/                     │
 Environment/Status/Since)           ▼
                              CTEを含むSQLクエリ組み立て
                                     │
                                     ▼
SSISDB.catalog.executions ───▶ Invoke-DbaQuery
SSISDB.catalog.                      │
execution_parameter_values           ▼
                              結果変換
                              (dbadatetime)
                                     │
                                     ▼
                              PSCustomObject
                                     │
                                     ▼
                                  Pipeline
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaSsisExecutionHistory.ps1 | `public/Get-DbaSsisExecutionHistory.ps1` | ソース | メイン処理 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | クエリ実行 |
