# 機能設計書 127-Get-DbaKbUpdate

## 概要

本ドキュメントは、Microsoft Update Catalogから KB更新プログラムの詳細情報とダウンロードリンクを取得するGet-DbaKbUpdate機能の設計仕様を記載する。

### 本機能の処理概要

Get-DbaKbUpdateは、MicrosoftのUpdate CatalogウェブサイトをスクレイピングしてKB更新プログラムの包括的な情報（サポート対象製品、アーキテクチャ、言語、ファイルサイズ、置換情報、ダウンロードリンク）を取得する機能である。

**業務上の目的・背景**：SQL Serverのパッチ管理では、特定のKBアーティクルに関する詳細情報（サービスパック、修正プログラム、累積更新プログラム）が必要になる。MicrosoftはUpdate CatalogのAPIを提供していないため、手動でWebページを確認する必要があった。本機能によりプログラム的に複数KBの情報を一括取得でき、パッチ管理ワークフローを効率化できる。

**機能の利用シーン**：
- SQL Serverパッチの調査と更新計画
- セキュリティ修正プログラムの影響範囲確認
- KB更新プログラムのダウンロードURLの一括取得
- 置換関係（Supersedes/SupersededBy）の確認

**主要な処理内容**：
1. Microsoft Update CatalogのWebページを取得
2. KBに対応する更新プログラムのGUIDを抽出
3. 各更新プログラムのダウンロードダイアログから詳細情報を取得
4. 詳細ページからメタデータ（分類、サポート製品、置換情報等）をスクレイピング
5. Get-DbaBuildと連携してSQL Serverビルド情報を付加
6. 結果をPSCustomObjectとして出力

**関連システム・外部連携**：Microsoft Update Catalog (catalog.update.microsoft.com)、Get-DbaBuild（ビルド情報取得）

**権限による制御**：特別な権限は不要。インターネット接続が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コンソール/ターミナル | 主画面 | コマンド実行と結果表示 |

## 機能種別

データ取得(SELECT) / 外部API連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Name | string[] | Yes | KBアーティクル番号（"KB"プレフィックスの有無は問わない） | Mandatory |
| Simple | switch | No | 基本情報のみ取得（パフォーマンス向上） | - |
| Language | string | No | 言語フィルタ（例: "en", "ja"） | - |
| EnableException | switch | No | 例外を直接スローするか | - |

### 入力データソース

- Microsoft Update Catalog (Webスクレイピング)
- Get-DbaBuild (SQL Serverビルド情報)

## 出力仕様

### 出力データ（フル出力）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Title | string | KB更新プログラムのタイトル |
| NameLevel | string | SQL Serverリリース名（Get-DbaBuildから） |
| SPLevel | string | サービスパックレベル |
| KBLevel | string | KBアーティクル番号 |
| CULevel | string | 累積更新番号 |
| BuildLevel | string | ビルド番号 |
| SupportedUntil | datetime | サポート終了日 |
| Architecture | string | CPUアーキテクチャ（x64, x86, ARM64） |
| Language | string | 言語識別子 |
| Hotfix | bool/string | ホットフィックスかどうか |
| Description | string | 更新プログラムの詳細説明 |
| LastModified | datetime | 最終更新日 |
| Size | string | ダウンロードサイズ |
| Classification | string | 分類（Critical, Important等） |
| SupportedProducts | string[] | サポート対象製品 |
| MSRCNumber | string | MSRCセキュリティ情報番号 |
| MSRCSeverity | string | MSRC重大度 |
| RebootBehavior | string | 再起動要否 |
| RequestsUserInput | string | ユーザー入力要否 |
| ExclusiveInstall | string | 排他インストール要否 |
| NetworkRequired | string | ネットワーク接続要否 |
| UninstallNotes | string | アンインストールに関する注意 |
| UninstallSteps | string | アンインストール手順 |
| UpdateId | string | 更新プログラムGUID |
| Supersedes | string[] | 本更新で置換されるKB |
| SupersededBy | string[] | 本更新を置換するKB |
| Link | string | ダウンロードURL |

### 出力先

- PowerShellパイプライン（PSCustomObject）
- コンソール出力（Select-DefaultViewで主要プロパティを表示）

## 処理フロー

### 処理シーケンス

```
1. beginブロックでヘルパー関数を定義
   └─ Invoke-KbTlsWebRequest、Get-Info、Get-SuperInfo

2. 各KB番号をループ処理
   └─ "KB"プレフィックスを正規化

3. Microsoft Update Catalogで検索
   └─ Search.aspx?q=KB{number}

4. 検索結果からGUIDを抽出
   └─ InputFieldsとLinksから抽出

5. 各GUIDに対してダウンロードダイアログ取得
   └─ DownloadDialog.aspx（POST）

6. -Simpleでない場合は詳細ページ取得
   └─ ScopedViewInline.aspx

7. ダウンロードリンクを抽出
   └─ download.windowsupdate.comパターン

8. Get-DbaBuildでビルド情報を付加
   └─ NameLevel, SPLevel, CULevel等

9. PSCustomObjectとして出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{KB番号ループ}
    B -->|各KB| C[KB番号正規化]
    C --> D[Update Catalog検索]
    D --> E{結果あり?}
    E -->|No| F[Warning出力]
    F --> B
    E -->|Yes| G{GUIDループ}
    G -->|各GUID| H[DownloadDialog取得]
    H --> I{-Simple?}
    I -->|Yes| J[基本情報のみ]
    I -->|No| K[詳細ページ取得]
    K --> L[メタデータ抽出]
    J --> M[ダウンロードURL抽出]
    L --> M
    M --> N[Get-DbaBuildでビルド情報]
    N --> O[PSCustomObject出力]
    O --> G
    G -->|終了| B
    B -->|全KB完了| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | KB番号正規化 | "KB"、"kb"、"Kb"プレフィックスを削除して処理 | 入力時 |
| BR-002 | アーキテクチャ判定 | AMD64→x64、64-Bit→x64、32-Bit→x86に変換 | 抽出時 |
| BR-003 | ビルド情報付加 | Get-DbaBuildでSQL Serverビルド情報を取得可能な場合のみ追加 | 出力時 |
| BR-004 | 言語フィルタ | Languageパラメータ指定時はHTTPヘッダーaccept-languageを設定 | 検索時 |

### 計算ロジック

特になし（Webスクレイピングによるデータ抽出）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | データベースアクセスなし（Web APIのみ） |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 検索結果なし | KBに対応する更新がない | Warning出力して次のKBへ |
| - | 詳細取得失敗 | ScopedViewInlineの応答不正 | Warningを出力して-Simple相当で継続 |
| - | TLS/接続エラー | インターネット接続問題 | Stop-Function |

### リトライ仕様

- 詳細ページ取得失敗時は1回リトライ
- セッションキャッシュを使用して再接続を最小化

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

外部WebサービスへのHTTPリクエストのため、トランザクション管理は不要。

## パフォーマンス要件

- 複数のWebページをスクレイピングするため、1KBあたり数秒〜十数秒かかる可能性
- -Simpleスイッチで詳細取得をスキップしてパフォーマンス向上
- 15分間のキャッシュで同一URLへの再アクセスを高速化

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

- インターネット接続が必要
- TLS（HTTPS）による暗号化通信
- プロキシ設定を自動検出（Windowsレジストリから）

## 備考

- MicrosoftがAPIを提供していないためWebスクレイピングを使用
- Webページの構造変更により動作しなくなる可能性あり
- Save-DbaKbUpdateと組み合わせてKBファイルをダウンロード可能

---

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

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

### 推奨読解順序

#### Step 1: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaKbUpdate.ps1 | `public/Get-DbaKbUpdate.ps1` | beginブロックのヘルパー関数 |

**主要処理フロー**:
1. **121-156行目**: Invoke-KbTlsWebRequest - TLS対応Webリクエスト
2. **164-179行目**: Get-Info - HTMLテキストからパターン抽出
3. **181-197行目**: Get-SuperInfo - 置換情報（Supersedes/SupersededBy）抽出
4. **199-225行目**: 基本プロパティ定義

**読解のコツ**:
- Invoke-KbTlsWebRequestはTLSバージョンを自動アップグレードしてHTTPS接続
- Get-InfoとGet-SuperInfoは正規表現ではなく文字列Splitでパース
- $script:websessionでセッションをキャッシュ

#### Step 2: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaKbUpdate.ps1 | `public/Get-DbaKbUpdate.ps1` | processブロックの処理フロー |

**主要処理フロー**:
- **231行目**: KB番号の正規化（プレフィックス削除）
- **233行目**: Update Catalog検索リクエスト
- **235-249行目**: GUID抽出
- **253-255行目**: DownloadDialog取得（POST）
- **274-301行目**: 詳細ページ取得とパース
- **313行目**: ダウンロードURL抽出
- **316行目**: Get-DbaBuildでビルド情報取得

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

```
Get-DbaKbUpdate
    │
    ├─ Invoke-KbTlsWebRequest (初期化)
    │      └─ catalog.update.microsoft.com
    │
    ├─ Invoke-KbTlsWebRequest (検索)
    │      └─ Search.aspx?q=KB{number}
    │
    ├─ Invoke-KbTlsWebRequest (ダウンロードダイアログ)
    │      └─ DownloadDialog.aspx (POST)
    │
    ├─ Invoke-KbTlsWebRequest (詳細ページ) ※-Simple未指定時
    │      └─ ScopedViewInline.aspx
    │
    ├─ Get-Info / Get-SuperInfo (HTMLパース)
    │
    ├─ Get-DbaBuild -Kb (ビルド情報)
    │
    └─ Select-DefaultView (出力フォーマット)
```

### データフロー図

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

Name (KB番号)  ───▶  KB正規化                 ───▶
                           │
                     Update Catalog検索       ───▶  GUIDリスト
                           │
                     DownloadDialog取得       ───▶  Title, Architecture,
                           │                        Language, Hotfix
                     ScopedViewInline取得     ───▶  Description, Size,
                           │                        Classification,
                     Get-Info / Get-SuperInfo ───▶  Supersedes, ...
                           │
                     ダウンロードURL抽出      ───▶  Link
                           │
                     Get-DbaBuild             ───▶  NameLevel, SPLevel,
                                                     CULevel, BuildLevel

                                              ───▶  PSCustomObject出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaKbUpdate.ps1 | `public/Get-DbaKbUpdate.ps1` | ソース | メイン関数定義 |
| Get-DbaKbUpdate.Tests.ps1 | `tests/Get-DbaKbUpdate.Tests.ps1` | テスト | 単体・統合テスト |
| Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | ソース | SQL Serverビルド情報取得 |
| Save-DbaKbUpdate.ps1 | `public/Save-DbaKbUpdate.ps1` | ソース | KBファイルダウンロード |
