# 画面設計書 204-SSIS実行履歴

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSSIS実行履歴取得機能の設計仕様を定義するものである。

### 本画面の処理概要

SSIS実行履歴機能は、SSISDBカタログに記録されたパッケージ実行履歴を取得する機能を提供する。パッケージの実行状況監視、失敗原因の調査、パフォーマンス分析に活用される。

**業務上の目的・背景**：SSISパッケージの運用管理では、実行履歴の確認が日常的に必要となる。特に、失敗したパッケージの特定、長時間実行されているジョブの監視、実行パターンの分析などが主要なユースケースである。本機能は、catalog.executionsビューから詳細な実行情報を取得し、フィルタリング機能を通じて必要な情報を効率的に抽出できるようにする。

**画面へのアクセス方法**：PowerShellコンソールから`Get-DbaSsisExecutionHistory`コマンドを実行する。

**主要な操作・処理内容**：
1. 指定されたSQLインスタンスのSSISDBへの接続
2. プロジェクト、フォルダ、環境によるフィルタリング
3. 実行ステータスによるフィルタリング
4. 日時範囲によるフィルタリング
5. 実行履歴の一覧取得と出力

**画面遷移**：
- 入力元：管理者またはスクリプトからのコマンド実行
- 出力先：実行履歴の一覧（PSCustomObject）
- 関連機能：New-DbaSsisCatalog、Get-DbaSsisEnvironmentVariable

**権限による表示制御**：SSISDBへの読み取り権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 298 | Get-DbaSsisExecutionHistory | 主機能 | SSIS実行履歴の取得 |
| 531 | New-DbaSsisCatalog | 関連機能 | SSISカタログの作成 |
| 530 | Get-DbaSsisEnvironmentVariable | 関連機能 | SSIS環境変数の取得 |

## 画面種別

コマンドラインインターフェース（CLI）/ 情報取得

## URL/ルーティング

```powershell
# 基本的な使用法
Get-DbaSsisExecutionHistory -SqlInstance <インスタンス>

# フィルタ付き
Get-DbaSsisExecutionHistory -SqlInstance <インスタンス> -Status Failed -Since (Get-Date).AddDays(-7)
```

## 入出力項目

| パラメータ名 | 型 | 必須 | 既定値 | 説明 |
|-------------|-----|------|--------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | No | - | SQL認証用資格情報 |
| Since | datetime | No | - | この日時以降の実行を取得 |
| Status | string[] | No | 全ステータス | 取得するステータス |
| Project | string[] | No | 全プロジェクト | 取得するプロジェクト名 |
| Folder | string[] | No | 全フォルダ | 取得するフォルダ名 |
| Environment | string[] | No | 全環境 | 取得する環境名 |
| EnableException | switch | No | $false | 例外の有効化 |

### Status パラメータの有効値

| ステータス | 説明 |
|----------|------|
| Created | 作成済み（未実行） |
| Running | 実行中 |
| Cancelled | キャンセル |
| Failed | 失敗 |
| Pending | 保留中 |
| Halted | 停止 |
| Succeeded | 成功 |
| Stopping | 停止処理中 |
| Completed | 完了 |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ExecutionID | int | 実行ID |
| FolderName | string | フォルダ名 |
| ProjectName | string | プロジェクト名 |
| PackageName | string | パッケージ名 |
| ProjectLsn | int | プロジェクトのログシーケンス番号 |
| Environment | string | 使用された環境（フォルダ\環境形式） |
| StatusCode | string | 実行ステータス |
| StartTime | dbadatetime | 開始日時 |
| EndTime | dbadatetime | 終了日時 |
| ElapsedMinutes | int | 経過時間（分） |
| LoggingLevel | int | ロギングレベル（0-5） |

## イベント仕様

### 1-実行履歴取得イベント

1. フィルタパラメータに基づくSQLクエリの動的構築
2. Status、Project、Folder、Environmentの条件追加
3. Since日時によるフィルタリング
4. Invoke-DbaQueryによるクエリ実行
5. 結果のdbadatetime型への変換
6. 結果オブジェクトの返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 実行履歴取得 | catalog.executions | SELECT | 実行履歴の読み取り |
| 実行履歴取得 | catalog.execution_parameter_values | SELECT | ロギングレベルの取得 |

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

本機能はSELECTのみであり、データベース更新は発生しない。

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| デバッグ | SQLステートメントとパラメータの出力 | Debug出力時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Invoke-DbaQueryのエラーハンドリングに委譲 |
| SSISDBが存在しない | クエリ実行時にデータベースエラー |

## 備考

- SQL Server 2012以上が必要（SSISDBカタログ）
- OPTION (RECOMPILE)を使用してクエリプランを最適化
- StartTime/EndTimeはdbadatetime型で返却

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を理解する。

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

**読解のコツ**: StatusCodeはCTEで数値から文字列に変換されている点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaSsisExecutionHistory.ps1 | `public/Get-DbaSsisExecutionHistory.ps1` | パラメータ定義（行99-111） |

**主要処理フロー**:
1. **行112-126**: ステータスマッピングハッシュテーブル
2. **行127-132**: Status条件の構築
3. **行135-146**: Project条件の構築
4. **行149-160**: Folder条件の構築
5. **行163-174**: Environment条件の構築
6. **行177-180**: Since条件の構築

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaSsisExecutionHistory.ps1 | `public/Get-DbaSsisExecutionHistory.ps1` | SQLクエリ定義（行182-230） |

**クエリ構造**:
- **cteLoglevel CTE**: LOGGING_LEVELパラメータ値を取得
- **cteStatus CTE**: ステータスコードを文字列にマッピング
- **メインクエリ**: catalog.executionsとJOIN

#### Step 4: 結果処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaSsisExecutionHistory.ps1 | `public/Get-DbaSsisExecutionHistory.ps1` | 結果処理（行239-247） |

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

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

```
Get-DbaSsisExecutionHistory
    |
    +-- begin{}
    |      +-- ステータスマッピング構築
    |      +-- 各フィルタ条件の構築
    |             +-- Status条件
    |             +-- Project条件
    |             +-- Folder条件
    |             +-- Environment条件
    |             +-- Since条件
    |      +-- SQLクエリ構築
    |
    +-- process{}
           +-- Invoke-DbaQuery (SSISDB)
           +-- 結果処理
                  +-- dbadatetime変換
                  +-- 結果返却
```

### データフロー図

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

SqlInstance --------+
                    |
Status -------------+----> フィルタ条件構築
                    |           |
Project ------------+           v
                    |      SQLクエリ生成
Folder -------------+           |
                    |           v
Environment --------+      Invoke-DbaQuery
                    |           |
Since --------------+           v
                          結果変換
                          (dbadatetime)
                                |
                                v
                          PSCustomObject ----> 実行履歴一覧
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaSsisExecutionHistory.ps1 | `public/Get-DbaSsisExecutionHistory.ps1` | ソース | メインコマンド実装 |
| New-DbaSsisCatalog.ps1 | `public/New-DbaSsisCatalog.ps1` | ソース | カタログ作成（関連機能） |
| Get-DbaSsisEnvironmentVariable.ps1 | `public/Get-DbaSsisEnvironmentVariable.ps1` | ソース | 環境変数取得（関連機能） |
