# 画面設計書 203-SSIS環境変数

## 概要

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

### 本画面の処理概要

SSIS環境変数機能は、SSISDBカタログに格納されている環境変数を取得し、センシティブ（暗号化）値を復号して平文で返す機能を提供する。SSISパッケージのパラメータ設定やデプロイメント監査に不可欠な機能である。

**業務上の目的・背景**：SSISプロジェクトデプロイメントモデルでは、環境変数を使用して接続文字列やパラメータ値を環境ごとに設定する。しかし、センシティブな値（パスワードなど）はSSISDBに暗号化されて格納されるため、通常のSMOでは復号されない。本機能は、対称キーと証明書を使用して内部テーブル（internal.environment_variables）から直接データを取得し、センシティブ値を復号することで、構成管理やトラブルシューティングを支援する。

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

**主要な操作・処理内容**：
1. 指定されたSQLインスタンスのSSISDBカタログへの接続
2. フォルダおよび環境のフィルタリング
3. 対称キーと証明書を使用した暗号化値の復号
4. 環境変数の一覧取得と出力

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

**権限による表示制御**：SSISDBへの読み取り権限が必要。センシティブ値の復号には対称キーへのアクセス権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 530 | Get-DbaSsisEnvironmentVariable | 主機能 | SSIS環境変数の取得 |
| 531 | New-DbaSsisCatalog | 関連機能 | SSISカタログの作成 |
| 529 | Copy-DbaSsisCatalog | 関連機能 | SSISカタログのコピー |

## 画面種別

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

## URL/ルーティング

```powershell
# 基本的な使用法
Get-DbaSsisEnvironmentVariable -SqlInstance <インスタンス> [-Environment <環境名>] [-Folder <フォルダ名>]

# パイプライン使用法
'Server1', 'Server2' | Get-DbaSsisEnvironmentVariable
```

## 入出力項目

| パラメータ名 | 型 | 必須 | 既定値 | 説明 |
|-------------|-----|------|--------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | No | - | SQL認証用資格情報 |
| Environment | object[] | No | 全環境 | 取得する環境名 |
| EnvironmentExclude | object[] | No | - | 除外する環境名 |
| Folder | object[] | No | 全フォルダ | 取得するフォルダ名 |
| FolderExclude | object[] | No | - | 除外するフォルダ名 |
| EnableException | switch | No | $false | 例外の有効化 |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Folder | string | フォルダ名 |
| Environment | string | 環境名 |
| Id | int | 変数ID |
| Name | string | 変数名 |
| Description | string | 変数の説明 |
| Type | string | データ型 |
| IsSensitive | bool | センシティブフラグ |
| BaseDataType | string | 基本データ型 |
| Value | string | 変数値（センシティブ値は復号済み） |

## イベント仕様

### 1-環境変数取得イベント

1. PowerShell Coreでの実行チェック（Linuxでは非サポート）
2. SQLインスタンスへの接続（最小バージョン11＝SQL 2012以上）
3. IntegrationServicesオブジェクトの作成
4. SSISDBカタログの取得
5. フォルダフィルタリング（Folder/FolderExcludeパラメータ）
6. 環境フィルタリング（Environment/EnvironmentExcludeパラメータ）
7. 各環境に対する暗号化キーの特定
8. 対称キーを使用したSQLクエリ実行
9. センシティブ値の復号と結果返却

### 2-暗号化復号イベント

各環境の変数取得時に以下の処理を実行：

1. 環境IDに基づく対称キー名の構築（MS_Enckey_Env_<ID>）
2. 環境IDに基づく証明書名の構築（MS_Cert_Env_<ID>）
3. OPEN SYMMETRIC KEYでキーを開く
4. DECRYPTBYKEY()で各データ型に応じた復号
5. CLOSE SYMMETRIC KEYでキーを閉じる

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 環境変数取得 | internal.environment_variables | SELECT | 環境変数の読み取り |

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

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

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| エラー | "This command is not supported on Linux or macOS" | PowerShell Core環境で実行時 |
| エラー | "Error occurred while establishing connection to $instance" | 接続失敗時 |
| 警告 | "Instance: $instance > -Folder and -FolderExclude filters return an empty collection. Skipping" | フィルタ結果が空の場合 |
| 警告 | "Instance: $instance / Folder: $f > -Environment and -EnvironmentExclude filters return an empty collection. Skipping." | 環境フィルタ結果が空の場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| Linux/macOS環境 | Stop-Functionでメッセージ出力、処理停止 |
| 接続エラー | Stop-Functionでエラー記録、Continue |
| IntegrationServices読み込み失敗 | Stop-Functionでエラー記録、return |
| フィルタ結果が空 | 警告メッセージ出力、次のフォルダ/環境へ |

## 備考

- Windows環境専用の機能（IntegrationServicesアセンブリがWindowsのみ）
- SQL Server 2012以上が必要（バージョン11以上）
- センシティブ値の復号には適切な権限が必要
- SMOの制限を回避するため、直接T-SQLクエリを使用

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: センシティブ値の処理に注目。行252-256でセンシティブフラグに応じて復号済み値または平文値を選択している。

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

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

**主要処理フロー**:
1. **行149-153**: PowerShell Core環境チェック
2. **行154-159**: SQLインスタンス接続
3. **行161-166**: IntegrationServicesオブジェクト作成
4. **行168-169**: SSISDBカタログ取得

#### Step 3: フィルタリングロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaSsisEnvironmentVariable.ps1 | `public/Get-DbaSsisEnvironmentVariable.ps1` | フォルダ・環境フィルタ（行171-202） |

**主要処理フロー**:
- **行172-176**: フォルダフィルタの適用
- **行179-181**: FolderExcludeの適用
- **行187-192**: 環境フィルタの適用
- **行195-197**: EnvironmentExcludeの適用

#### Step 4: 暗号化復号ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaSsisEnvironmentVariable.ps1 | `public/Get-DbaSsisEnvironmentVariable.ps1` | 復号SQLクエリ（行205-247） |

**主要処理フロー**:
- **行206-207**: 対称キー名と証明書名の構築
- **行216**: OPEN SYMMETRIC KEY
- **行232-243**: DECRYPTBYKEY()でデータ型別復号
- **行246**: CLOSE SYMMETRIC KEY

**データ型別復号処理**:
| データ型 | 復号後の変換 |
|---------|------------|
| nvarchar | NVARCHAR(MAX) |
| bit | BIT |
| datetime | DATETIME2(0) |
| single/float/decimal | DECIMAL(38, 18) |
| tinyint/smallint/int/bigint | 各整数型 |

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

```
Get-DbaSsisEnvironmentVariable
    |
    +-- process{}
           +-- PSEdition チェック（Core非サポート）
           +-- Connect-DbaInstance (MinimumVersion 11)
           +-- IntegrationServices オブジェクト作成
           +-- SSISDBカタログ取得
           |
           +-- foreach フォルダ
           |      +-- フォルダフィルタリング
           |      +-- Folder/FolderExclude 適用
           |
           +-- foreach 環境
                  +-- 環境フィルタリング
                  +-- Environment/EnvironmentExclude 適用
                  +-- 暗号化キー名構築
                  +-- T-SQL実行 (DECRYPTBYKEY)
                  +-- 結果処理
                         +-- センシティブ判定
                         +-- PSCustomObject作成
```

### データフロー図

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

SqlInstance --------+
                    |
Folder/Exclude -----+----> カタログ接続 ----> フォルダ取得
                    |           |
Environment/Exclude-+           v
                          環境フィルタリング
                                |
                                v
                          暗号化キー特定
                          (MS_Enckey_Env_<ID>)
                                |
                                v
                          T-SQL実行
                          (DECRYPTBYKEY)
                                |
                                v
                          センシティブ値復号 ----> PSCustomObject
                                                     (環境変数一覧)
```

### 関連ファイル一覧

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