> ## 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.

# Jinba フロー

> Jinba フローを実行する

## 概要

Jinba Flow ツールを使うことで、Jinba 上で公開されたフローを別のフロー内から実行できます。また、Jinba ツールを使って Jinba ストレージのファイル管理や Jinba テーブルのレコードの読み書きも行えます。

## 主な機能

* `JINBA_FLOW_RUN`
  * フロー ID と必要な引数を指定して、Jinba フローを実行
* `JINBA_FILE_UPLOAD` / `JINBA_FILE_GET` / `JINBA_FILE_SEARCH` / `JINBA_FILE_DELETE`
  * Jinba ストレージ上のファイルのアップロード、取得、検索、削除
* `JINBA_TABLE_ADD_RECORD` / `JINBA_TABLE_GET_RECORDS` / `JINBA_TABLE_UPDATE_RECORD`
  * Jinba テーブルのレコードの追加、取得、更新

## 認証

`JINBA_FLOW_RUN` に config の設定は不要です。同じワークスペース内の公開済みフローを実行するツールで、認証にはワークスペース API キー（`secrets.JINBAFLOW_WS_API_KEY`）がサーバー側で自動的に使用され、API のベース URL もサーバー環境から解決されます。実行対象のフローは事前に公開しておいてください。

**注意**：API キーは機密情報として扱い、公開リポジトリにコミットしないでください。

### 例：他の Jinba フローを実行する

```yaml theme={null}
- name: Run flow
  id: run_flow
  tool: JINBA_FLOW_RUN
  input:
    - name: id
      value: ecd528ac-fc53-44ad-8535-7051507e4958
- name: Run flow with args
  id: run_flow_with_args
  tool: JINBA_FLOW_RUN
  input:
    - name: id
      value: ecd528ac-fc53-44ad-8535-7051507e4958
    - name: args
      value: '[{"name":"input_1","value":"Hello, world!"}]'
```

## ファイルツール

ファイルツールは config の `token` に Jinba Flow ワークスペース API トークンを指定して認証します。デフォルトで `{{ secrets.JINBAFLOW_WS_API_KEY }}` が使用されるため、通常は明示的に設定する必要はありません。

### JINBA\_FILE\_UPLOAD

Jinba ストレージにファイルをアップロードします。

**入力**:

| パラメータ         | 型      | 必須 | 説明                                                                 |
| ------------- | ------ | -- | ------------------------------------------------------------------ |
| `file`        | string | はい | Base64 エンコードされたファイル内容、または `https://` か `jinbaflow://` で始まるファイル URL |
| `filename`    | string | はい | ファイル名（拡張子はファイルから自動判定）                                              |
| `workspaceId` | string | はい | アップロード先のワークスペース ID                                                 |

**出力**: `id`、`name`、`size`、`extension`、`mimeType`、`createdAt`、`updatedAt`、`workspaceId`、`userId`、`signedUrl` を含むファイルメタデータ。

### JINBA\_FILE\_GET

ファイル ID を指定して、ファイルのメタデータと署名付き URL を取得します。

**入力**:

* `fileId`（string、必須）: 取得するファイルの ID

**出力**: `JINBA_FILE_UPLOAD` と同じファイルメタデータ（`signedUrl` を含む）。

### JINBA\_FILE\_SEARCH

Jinba ストレージ内のファイルを検索します。

**入力**:

| パラメータ         | 型      | 必須  | 説明                      |
| ------------- | ------ | --- | ----------------------- |
| `workspaceId` | string | いいえ | ファイルを絞り込むワークスペース ID     |
| `query`       | string | いいえ | 検索クエリ                   |
| `limit`       | number | いいえ | 返却するファイルの最大数（デフォルト: 50） |
| `cursor`      | string | いいえ | ページネーション用カーソル           |

**出力**: `items`（ファイルメタデータの配列）とページネーション用の `nextCursor`。

### JINBA\_FILE\_DELETE

Jinba ストレージからファイルを削除します。

**入力**:

* `fileId`（string、必須）: 削除するファイルの ID

**出力**: `id` と `success`。

### 例：ファイルのアップロードと取得

```yaml theme={null}
- id: upload_file
  tool: JINBA_FILE_UPLOAD
  input:
    - name: file
      value: "{{steps.generate_report.result.url}}"
    - name: filename
      value: "monthly_report.pdf"
    - name: workspaceId
      value: "{{secrets.WORKSPACE_ID}}"

- id: get_file
  tool: JINBA_FILE_GET
  input:
    - name: fileId
      value: "{{steps.upload_file.id}}"
```

## テーブルツール

テーブルツールはワークスペースに紐づいたツールです。ワークスペースの API キーが自動的に注入されるため、config の設定は不要です。

### JINBA\_TABLE\_ADD\_RECORD

Jinba テーブルにレコードを追加します。

**入力**:

| パラメータ     | 型      | 必須 | 説明                                                                                                |
| --------- | ------ | -- | ------------------------------------------------------------------------------------------------- |
| `tableId` | string | はい | レコードを追加するテーブル                                                                                     |
| `fields`  | object | はい | 新規レコードの「列名 → 値」のマップ（例: `{ "Status": "done", "Score": 42 }`）。省略した列は列のデフォルト値、デフォルト値がなければ NULL になります |

**出力**: `result.recordId` — 新規追加されたレコードの ID。

### JINBA\_TABLE\_GET\_RECORDS

Jinba テーブルからレコードを取得します。

**入力**:

| パラメータ           | 型      | 必須  | 説明                                            |
| --------------- | ------ | --- | --------------------------------------------- |
| `tableId`       | string | はい  | レコードを取得するテーブル                                 |
| `filter`        | object | いいえ | 等価フィルタ: `{ <列名>: <期待値> }`。複数キーは AND 条件で結合されます |
| `sortColumn`    | string | いいえ | ソートに使う列の表示名（デフォルト: `__updated_at`）            |
| `sortDirection` | string | いいえ | `asc` または `desc`（デフォルト: `desc`）               |
| `limit`         | number | いいえ | 返却するレコード数（1〜500、デフォルト: 100）                   |
| `offset`        | number | いいえ | スキップするレコード数（デフォルト: 0）                         |

**出力**: `result` に `items`（`{ __id, __created_at, __updated_at, __version, <列名>: <値>, ... }` 形式のレコード）、`total`、`limit`、`offset` を含みます。NUMBER 型の列は精度を保持するために文字列としてシリアライズされます。数値演算が必要な場合は後続ステップで `Number(value)` などで変換してください。

### JINBA\_TABLE\_UPDATE\_RECORD

Jinba テーブルのレコードを更新します。

**入力**:

| パラメータ      | 型      | 必須 | 説明                                                                           |
| ---------- | ------ | -- | ---------------------------------------------------------------------------- |
| `tableId`  | string | はい | レコードが含まれるテーブル                                                                |
| `recordId` | string | はい | 更新するレコードの ID                                                                 |
| `fields`   | object | はい | 「列名 → 新しい値」のマップ（例: `{ "Status": "done" }`）。省略した列は変更されません。null を渡すと列の値をクリアします |

**出力**: `result.recordId`。

### 例：テーブルレコードの追加と更新

```yaml theme={null}
- id: add_record
  tool: JINBA_TABLE_ADD_RECORD
  input:
    - name: tableId
      value: "{{secrets.TABLE_ID}}"
    - name: fields
      value: '{ "Status": "pending", "Title": "新しいタスク" }'

- id: get_records
  tool: JINBA_TABLE_GET_RECORDS
  input:
    - name: tableId
      value: "{{secrets.TABLE_ID}}"
    - name: filter
      value: '{ "Status": "pending" }'
    - name: limit
      value: 100

- id: update_record
  tool: JINBA_TABLE_UPDATE_RECORD
  input:
    - name: tableId
      value: "{{secrets.TABLE_ID}}"
    - name: recordId
      value: "{{steps.add_record.result.recordId}}"
    - name: fields
      value: '{ "Status": "done" }'
```