> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Excel操作

> 包括的なExcelファイル操作ツール

## 概要

Excelツールは、Excelファイル（.xlsx）を操作するための包括的な機能を提供します。配列データからの新規ファイル作成、データの読み取り、セルの更新、特定の行の取得、埋め込み画像の抽出、URLからのExcelファイルの操作が可能です。

## 主な機能

* `EXCEL_CREATE`
  * 2次元配列から新しいExcelファイルを作成し、ダウンロード用URLを返す
* `EXCEL_GET_ROWS`
  * Excelシートから複数の行を2次元配列として取得（`range` で範囲指定も可能。例: "A1:C10"）
* `EXCEL_GET_ROW`
  * `range`（例: "A5:C5"）で指定した1行を取得
* `EXCEL_GET_CELL_WITH_COORDINATE`
  * 開始セルと終了セルで指定した範囲から、座標付きでセルの値を取得
* `EXCEL_GET_IMAGES`
  * Excelファイルに埋め込まれた画像を、シート名やセル範囲の情報付きで抽出
* `EXCEL_UPDATE`
  * 範囲選択を使用してExcelファイルを新しいデータで更新
* `EXCEL_UPDATE_BY_COORDINATE`
  * 座標ベースの配置を使用して特定のセルを更新

## 認証

認証は不要です。ExcelツールはファイルURLで直接動作します。

### 例: Excelファイルの作成

```yaml theme={null}
- id: create_excel
  name: create_excel
  tool: EXCEL_CREATE
  input:
    - name: data
      value: [
        ["氏名", "役職", "給与"],
        ["田中太郎", "マネージャー", "50000"],
        ["佐藤花子", "開発者", "60000"]
      ]
    - name: sheetName
      value: "Members"
    - name: outputFilename
      value: "members.xlsx"
    - name: startCell
      value: "A1"
```

結果として、作成されたExcelファイルのダウンロード用URLが返されます。

### 例: Excelデータの読み取り

```yaml theme={null}
- id: get_excel_rows
  name: get_excel_rows
  tool: EXCEL_GET_ROWS
  input:
    - name: url
      value: "https://example.com/data.xlsx"
    - name: sheetName
      value: "Sheet1"
    # 任意: range を省略するとシート全体を読み取ります
    - name: range
      value: "A2:C10"

- id: get_specific_row
  name: get_specific_row
  tool: EXCEL_GET_ROW
  input:
    - name: url
      value: "https://example.com/data.xlsx"
    - name: sheetName
      value: "Sheet1"
    - name: range
      value: "A5:C5"

- id: get_cell_value
  name: get_cell_value
  tool: EXCEL_GET_CELL_WITH_COORDINATE
  input:
    - name: url
      value: "https://example.com/data.xlsx"
    - name: sheetName
      value: "Sheet1"
    - name: startCell
      value: "B5"
    - name: endCell
      value: "B5"

- id: get_images
  name: get_images
  tool: EXCEL_GET_IMAGES
  input:
    - name: url
      value: "https://example.com/data.xlsx"
    # sheetName を省略すると全シートから画像を抽出します
    - name: sheetName
      value: "Sheet1"
```

`EXCEL_GET_ROWS` はセルの値を2次元配列として `result` に返し、`EXCEL_GET_ROW` は1行分を配列として返します。`EXCEL_GET_CELL_WITH_COORDINATE` は、`startCell` から `endCell` までの範囲内の各セルについて `{coordinate, content}` オブジェクトの配列を返します。

`EXCEL_GET_IMAGES` は、抽出した各画像の URL、拡張子、MIME タイプ、シート名、画像が配置されているセル範囲と、抽出した画像の総数を返します。

### 例: Excelデータの更新

```yaml theme={null}
- id: update_excel_range
  name: update_excel_range
  tool: EXCEL_UPDATE
  input:
    - name: url
      value: "https://example.com/template.xlsx"
    - name: sheetName
      value: "Data"
    - name: startCell
      value: "A2"
    - name: endCell
      value: "C4"
    - name: data
      value: [
        ["田中太郎", "マネージャー", "50000"],
        ["佐藤花子", "開発者", "60000"],
        ["鈴木一郎", "デザイナー", "45000"]
      ]

- id: update_specific_cell
  name: update_specific_cell
  tool: EXCEL_UPDATE_BY_COORDINATE
  input:
    - name: url
      value: "https://example.com/report.xlsx"
    - name: sheetName
      value: "Summary"
    - name: updateData
      value: [
        {"coordinate": "E10", "content": "{{steps.calculate_total.result.sum}}"}
      ]
```

### 例: Excelデータ処理ワークフロー

```yaml theme={null}
- id: read_source_data
  name: read_source_data
  tool: EXCEL_GET_ROWS
  input:
    - name: url
      value: "{{secrets.EXCEL_SOURCE_URL}}"
    - name: sheetName
      value: "RawData"
    - name: range
      value: "A2:C100"

- id: process_data
  name: process_data
  tool: PYTHON_SANDBOX_RUN
  input:
    - name: code
      value: |
        import json
        
        # 前のステップからデータを取得（セル値の2次元配列）
        raw_data = {{steps.read_source_data.result}}
        
        # データを処理・変換
        processed_data = []
        for row in raw_data:
            if row[0] and row[1]:  # 名前と値が存在するかチェック
                processed_data.append([
                    row[0].upper(),  # 名前を大文字に
                    float(row[1]) * 1.1,  # 値を10%増加
                    "処理済み"
                ])
        
        print(json.dumps({"processed_data": processed_data}))

- id: update_target_excel
  name: update_target_excel
  tool: EXCEL_UPDATE
  input:
    - name: url
      value: "{{secrets.EXCEL_TARGET_URL}}"
    - name: sheetName
      value: "ProcessedData"
    - name: startCell
      value: "A2"
    - name: data
      value: "{{steps.process_data.result.processed_data}}"
```

## ヒントとベストプラクティス

* 間違ったシートで作業しないよう、常にシート名を指定する
* 正確なセル参照にはA1、B2などの座標記法を使用する
* 範囲を更新する際は、データ配列の次元が指定された範囲と一致することを確認する
* 大きなデータセットの場合、タイムアウトを避けるためにデータをチャンクで処理することを検討する
* エラーを防ぐため、Excelファイルを更新する前にデータ形式を検証する