# 機能設計書 215-Save-DbaKbUpdate

## 概要

本ドキュメントは、Microsoft Knowledge Base更新プログラムをダウンロードするSave-DbaKbUpdate関数の機能設計書です。

### 本機能の処理概要

Save-DbaKbUpdateは、MicrosoftサーバーからKB更新プログラム、累積的な更新プログラム、およびサービスパックをローカルファイルシステムにダウンロードします。この関数はSQL Serverパッチだけでなく、他のMicrosoft KB更新プログラムも処理でき、複数サーバーへのインストール用にパッチをステージングすることを容易にします。

**業務上の目的・背景**：SQL Server環境の更新管理では、パッチを事前にダウンロードしてローカルリポジトリに保存しておくことで、複数サーバーへの展開を効率化できます。また、オフライン環境やネットワーク制限のある環境では、事前にパッチをダウンロードしておく必要があります。本機能は、KBアーティクル番号を指定するだけで適切なファイルをダウンロードでき、アーキテクチャや言語によるフィルタリングもサポートします。

**機能の利用シーン**：
- SQL Serverの累積的な更新プログラム（CU）をダウンロードする場合
- サービスパックをダウンロードする場合
- 複数サーバーへの展開用にローカルパッチリポジトリを構築する場合
- オフラインインストール用にパッチを準備する場合

**主要な処理内容**：
1. KB番号からダウンロード情報を取得（Get-DbaKbUpdate使用）
2. アーキテクチャ・言語によるフィルタリング
3. BITS転送またはWebリクエストによるファイルダウンロード
4. ダウンロードしたファイル情報の出力

**関連システム・外部連携**：
- Microsoft Update Catalog（KB情報取得）
- Microsoft Download Center（ファイルダウンロード）

**権限による制御**：指定されたパスへの書き込み権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIインターフェース | 主画面 | コマンドライン実行 |

## 機能種別

ファイルダウンロード / パッチ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Name | string[] | No | ダウンロードするKB番号 | "KB"プレフィックス有無どちらも可 |
| Path | string | No | ダウンロード先ディレクトリ | デフォルト: カレントディレクトリ "." |
| FilePath | string | No | 保存ファイルのフルパス | 単一KB/単一アーキテクチャ時のみ使用可 |
| Architecture | string | No | CPUアーキテクチャ | x64, x86, ia64, All（デフォルト: x64） |
| Language | string | No | 言語コード | 3文字言語コード（例: enu, deu） |
| InputObject | object[] | No | Get-DbaKbUpdateからのパイプライン入力 | KB更新オブジェクト |
| EnableException | switch | No | 例外を有効化 | スイッチ型 |

### 入力データソース

- コマンドライン引数（KB番号指定）
- Get-DbaKbUpdateからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FileInfo | System.IO.FileInfo | ダウンロードした各ファイルの情報 |

### 出力先

- 指定されたPathディレクトリ
- または指定されたFilePath

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   ├─ FilePath使用時の単一KB/アーキテクチャ制約確認
   └─ Name/InputObjectのいずれかが指定されていることを確認

2. KB情報取得
   └─ Nameが指定されている場合、Get-DbaKbUpdateで情報取得

3. ダウンロードリンクのフィルタリング
   ├─ アーキテクチャによるフィルタリング
   └─ 言語によるフィルタリング

4. ファイルダウンロード
   ├─ BITS転送（利用可能な場合）
   └─ Invoke-TlsWebRequest（BITSが利用不可の場合）

5. ファイル情報出力
   └─ 存在確認後、FileInfo出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{複数KB & FilePath?}
    B -->|Yes| C[エラー終了]
    B -->|No| D{All架構 & FilePath?}

    D -->|Yes| C
    D -->|No| E{Name/InputObject指定?}

    E -->|No| F[エラー終了]
    E -->|Yes| G{Nameあり?}

    G -->|Yes| H[Get-DbaKbUpdate実行]
    G -->|No| I[InputObjectを使用]
    H --> I

    I --> J[各リンクをループ]
    J --> K{Architecture一致?}
    K -->|No| L[スキップ]
    K -->|Yes| M{Language一致?}

    M -->|No| L
    M -->|Yes| N[ファイル名決定]

    N --> O{BITS利用可?}
    O -->|Yes| P[Start-BitsTransfer]
    O -->|No| Q[Invoke-TlsWebRequest]

    P --> R{ファイル存在?}
    Q --> R
    R -->|Yes| S[FileInfo出力]
    R -->|No| L

    S --> T{次のリンク?}
    L --> T
    T -->|Yes| J
    T -->|No| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトアーキテクチャ | x64がデフォルト | Architecture未指定時 |
| BR-002 | FilePath制約 | 複数KB/Allアーキテクチャ時は使用不可 | FilePath指定時 |
| BR-003 | BITS優先 | 利用可能ならStart-BitsTransferを使用 | Windows環境 |
| BR-004 | 言語フィルタ | サービスパックで有効、CUは言語中立 | Language指定時 |
| BR-005 | アーキテクチャマッチング | URLに含まれるアーキテクチャパターンで判定 | 常時 |

### 計算ロジック

該当なし

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

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

該当なし（データベース操作なし）

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | FilePath制約違反 | 複数KB指定時にFilePath使用 | エラーメッセージ出力、処理終了 |
| - | FilePath制約違反 | Architecture=All時にFilePath使用 | エラーメッセージ出力、処理終了 |
| - | 入力不足 | Name/InputObjectどちらも未指定 | エラーメッセージ出力、処理終了 |
| - | ダウンロード失敗 | ファイルダウンロードに失敗 | Invoke-TlsWebRequestがエラーをスロー |

### リトライ仕様

リトライは行いません。

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

該当なし（ファイルシステム操作）

## パフォーマンス要件

- ファイルサイズはパッチにより異なる（数MB〜数百MB）
- BITS転送は帯域制御とレジューム機能をサポート
- ネットワーク帯域に依存

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

- HTTPSでMicrosoftサーバーにアクセス
- 正規のMicrosoftダウンロードURLのみを使用
- ファイルの署名検証は本関数では行わない（別途検証推奨）

## 備考

- Get-DbaKbUpdateとの組み合わせ使用を推奨
- Out-GridView -Passthruでインタラクティブな選択が可能
- Linux/macOS環境ではBITS未対応のためInvoke-TlsWebRequestを使用

---

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

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

### 推奨読解順序

#### Step 1: パラメータと検証ロジックを理解する

関数のエントリーポイントと入力検証を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Save-DbaKbUpdate.ps1 | `public/Save-DbaKbUpdate.ps1` 97-123行目 | パラメータ定義、検証ロジック |

**読解のコツ**: Architecture="x64"がデフォルト、Path="."がデフォルトです。

**主要処理フロー**:
1. **110-113行目**: 複数KB + FilePath制約チェック
2. **115-118行目**: All + FilePath制約チェック
3. **120-123行目**: Name/InputObject指定チェック

#### Step 2: KB情報取得処理を理解する

Get-DbaKbUpdateとの連携を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Save-DbaKbUpdate.ps1 | `public/Save-DbaKbUpdate.ps1` 125-127行目 | KB情報取得 |

**主要処理フロー**:
- **125-127行目**: NameパラメータからGet-DbaKbUpdateでInputObjectに追加

#### Step 3: ダウンロードフィルタリングを理解する

アーキテクチャと言語によるフィルタリングを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Save-DbaKbUpdate.ps1 | `public/Save-DbaKbUpdate.ps1` 129-135行目 | フィルタリングロジック |

**主要処理フロー**:
- **130-132行目**: Architecture不一致時にスキップ（パターン: Architecture[-_]）
- **133-135行目**: Language不一致時にスキップ（パターン: -Language_）

#### Step 4: ダウンロード処理を理解する

BITS/WebRequestによるダウンロードを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Save-DbaKbUpdate.ps1 | `public/Save-DbaKbUpdate.ps1` 137-154行目 | ダウンロード実行、ファイル出力 |

**主要処理フロー**:
- **137行目**: Split-Pathでファイル名抽出
- **138-142行目**: FilePathまたはPath+ファイル名でパス決定
- **144-145行目**: BITS転送（利用可能時）
- **146-149行目**: Invoke-TlsWebRequest（BITSが利用不可時）
- **151-153行目**: ファイル存在確認、FileInfo出力

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

```
Save-DbaKbUpdate
    │
    ├─ Get-DbaKbUpdate (KB情報取得)
    │      └─ Microsoft Update Catalog照会
    │
    ├─ Get-Command (BITS利用可否確認)
    │
    ├─ Start-BitsTransfer (BITSダウンロード)
    │
    ├─ Invoke-TlsWebRequest (Webダウンロード)
    │
    ├─ Test-Path (ファイル存在確認)
    │
    └─ Get-ChildItem (ファイル情報出力)
```

### データフロー図

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

Name (KB番号)      ───▶ Get-DbaKbUpdate    ───▶
     or                      │
InputObject                  ▼
               ───▶ リンクフィルタリング  ───▶
                    (Architecture/Language)
                             │
                             ▼
               ───▶ BITS/WebRequest       ───▶ System.IO.FileInfo
                    ダウンロード
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Save-DbaKbUpdate.ps1 | `public/Save-DbaKbUpdate.ps1` | ソース | メイン関数 |
| Get-DbaKbUpdate.ps1 | `public/Get-DbaKbUpdate.ps1` | ソース | KB情報取得 |
| Invoke-TlsWebRequest.ps1 | `private/functions/Invoke-TlsWebRequest.ps1` | ソース | TLS対応Webリクエスト |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理 |
