feishu-bitable

Feishu 多维表格

通过 Bitable API 操作数据、字段、视图和权限。

Base URL: https://open.feishu.cn/open-apis/bitable/v1

認証と Token の取得

feishu_skills のルートディレクトリから共有スクリプトを実行します。

TOKEN="$(./scripts/get_feishu_token.sh)"

リクエストヘッダーでは、常に Authorization: Bearer ${TOKEN} を使用します。

業務 API からトークンが無効、期限切れ、または 401 と返された場合、強制的に更新して、元のリクエストを一度だけ再試行します。

TOKEN="$(./scripts/get_feishu_token.sh --force-refresh)"

環境変数:

• FEISHU_APP_ID
• FEISHU_APP_SECRET

ローカルキャッシュ: ./.feishu_token_cache.json（期限内であれば再利用し、デフォルトでは期限の 5 分前に更新します）

主なパラメーター:

• app_token: 多次元テーブルの URL の /base/ に続く文字列
• table_id: リスト API の呼び出しで取得します

---

レコード操作

API	エンドポイント	説明
1 件追加	POST /apps/{app_token}/tables/{table_id}/records	-
一括追加	POST .../records/batch_create	最大 500 件、Upsert に対応
更新	PUT .../records/{record_id}	-
一括更新	POST .../records/batch_update	最大 500 件
一括削除	POST .../records/batch_delete	最大 500 件
検索	POST .../records/search	filter/sort/ページネーションに対応

すべてのレコードをページネーションで取得（1 回あたり最大 500 件。has_more: false になるまで繰り返します）：

page_token = None
all_records = []
while True:
    body = {"page_size": 500}
    if page_token:
        body["page_token"] = page_token
    resp = post(".../records/search", json=body)
    all_records.extend(resp["data"]["items"])
    if not resp["data"].get("has_more"):
        break
    page_token = resp["data"]["page_token"]

リクエスト例:

{
  "fields": {
    "名称": "测试",
    "金额": 100,
    "进度": 0.75,
    "评分": 4,
    "日期": 1770508800000,
    "状态": "进行中",
    "标签": ["重要", "紧急"],
    "完成": true,
    "负责人": [{"id": "ou_xxx"}],
    "电话": "13800138000",
    "链接": {"text": "官网", "link": "https://example.com"}
  }
}

⚠️ 数値を文字列として渡さないでください。日付には 13 桁のミリ秒タイムスタンプを指定する必要があります。

---

フィールド型の形式

type	ui_type	日本語名	書き込み形式	例
1	Text	複数行テキスト	文字列	"办公用品"
1	Email	メールアドレス	文字列	"[email protected]"
2	Number	数値	数値	100
2	Currency	通貨	数値	1280.50
2	Progress	進捗	数値（0～1）	0.25（25%）
2	Rating	評価	数値（1～5）	3
3	SingleSelect	単一選択	文字列	"支出"（選択肢を自動作成）
4	MultiSelect	複数選択	文字列配列	["餐饮","交通"]
5	DateTime	日付	ミリ秒タイムスタンプ	1770508800000
7	Checkbox	チェックボックス	ブール値	true
11	User	ユーザー	オブジェクト配列	[{"id":"ou_xxx"}]
13	Phone	電話番号	文字列	"13800138000"
15	Url	ハイパーリンク	オブジェクト	{"text":"名称","link":"https://..."}
17	Attachment	添付ファイル	オブジェクト配列	[{"file_token":"xxx"}]
18	SingleLink	一方向リンク	文字列配列	["recuxxx"]
21	DuplexLink	双方向リンク	文字列配列	["recuxxx"]
22	Location	位置情報	文字列	"116.397,39.903"

API による書き込みに非対応: 数式、ルックアップ、作成日時、更新者、自動採番

日付形式の変換:

import datetime
ts = int(datetime.datetime(2026, 2, 9).timestamp() * 1000)
# → 1770508800000

---

フィールド管理

API	エンドポイント	説明
フィールド一覧を取得	GET .../fields	type と ui_name を返します
フィールドを追加	POST .../fields	{"field_name":"新字段","type":1}
フィールドを更新	PUT .../fields/{field_id}	単一選択を変更する場合は、property 全体を指定する必要があります
フィールドを削除	DELETE .../fields/{field_id}	-

数式フィールドの例:

{
  "type": 20,
  "field_name": "利润",
  "property": {"formula_expression": "[营收]-[成本]"}
}

リンクフィールドの例:

{
  "type": 18,
  "field_name": "关联客户",
  "property": {"table_id": "tblXXX", "multiple": true}
}

---

データテーブル管理

API	エンドポイント	説明
多次元テーブルを作成	POST /apps	{"name":"数据库名称"}
データテーブル一覧を取得	GET /apps/{app_token}/tables	-
データテーブルを追加	POST /apps/{app_token}/tables	{"table":{"name":"表名"}}
テーブルを一括追加	POST .../tables/batch_create	最大 10 テーブル
データテーブルを削除	DELETE .../tables/{table_id}	-
データテーブルを複製	POST .../tables/{table_id}/copy	-

⚠️ 権限管理（重要）：

• API で作成したテーブルは、デフォルトではボットからのみ表示できます
• 作成後、ユーザーを共同編集者として追加する必要があります：

POST /permissions/{app_token}/members
{
  "member_type": "user",
  "member_id": "ou_xxx",
  "perm": "full_access"
}

• 権限の種類：view / edit / full_access

---

ビュー管理

API	エンドポイント	説明
ビュー一覧を取得	GET .../tables/{table_id}/views	-
ビューを作成	POST .../tables/{table_id}/views	{"view_name":"新视图","view_type":"grid"}
ビューを削除	DELETE .../views/{view_id}	-

ビューの種類: grid（テーブル） / kanban（カンバン） / gallery（ギャラリー） / gantt（ガントチャート）

---

権限管理

API	エンドポイント	説明
共同編集者を作成	POST /apps/{app_token}/roles/{role_id}/members/batch_create	-
共同編集者を削除	POST .../members/batch_delete	-
権限を更新	PUT /apps/{app_token}/roles/{role_id}	-

ロールの種類: owner / editor / reader

---

⚠️ 存在しないインターフェース

/apps/:app_token/tables/:table_id/statistics このインターフェースは存在しません。Feishu の公式ドキュメントには、統計集計 API がありません。

統計データ（合計や件数など）が必要な場合は、次の方法をおすすめします。

1. POST .../records/search で全レコードを取得し、クライアント側で計算する
2. 多次元テーブルに数式フィールド（SUM、COUNT など）を作成し、API でフィールド値を読み取る

---

ベストプラクティス

1. 一括操作を優先する（API 呼び出しを削減できます）
2. フィールド型を厳密に合わせる（書き込みエラーを防げます）
3. 日付にはミリ秒タイムスタンプを使用する（Python: int(datetime.timestamp() * 1000)）
4. リンクフィールドでリレーショナル機能を実現する
5. テーブルの作成後、すぐにユーザーを共同編集者として追加する（表示されない状態を防げます）
6. 単一選択フィールドの選択肢は自動作成される（選択肢のテキストをそのまま書き込めます）

---

テスト検証

実機テストで検証済みの 15 種類のフィールド型：

• テキスト、進捗、複数選択、単一選択、日付、チェックボックス、電話番号、ユーザー、ハイパーリンク
• メールアドレス、通貨、評価、位置情報、一方向リンク、双方向リンク

テスト用テーブル：https://jvbmlo28x0.feishu.cn/base/YdOpb47PvalSbQsHPyXc7LrNnUh