Feishu Bitable

Bitable API を使用してデータ、フィールド、ビュー、権限を管理します。

ベース URL: https://open.feishu.cn/open-apis/bitable/v1

認証とトークン取得

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

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

リクエストヘッダーは統一して Authorization: Bearer ${TOKEN} を使用します。

ビジネスインターフェースがトークン無効、期限切れ、または 401 を返す場合、強制更新後に元のリクエストを 1 回だけ再試行します：

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	エンドポイント	説明
単一追加	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	メール	文字列	"test@example.com"
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