飛書多維表格

Bitable API を通じてデータ、フィールド、ビュー、および権限を操作します。

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

認証とトークン取得

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

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

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

ビジネスインターフェースがトークン無効、期限切れ、または 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 を呼び出して取得

レコード操作

全レコードのページネーション検索（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 桁のミリ秒タイムスタンプである必要があります。

フィールドタイプ形式

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

日付形式変換:

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

フィールド管理

数式フィールドの例:

{
  "type": 20,
  "field_name": "利益",
  "property": {"formula_expression": "[売上]-[コスト]"}
}

関連フィールドの例:

{
  "type": 18,
  "field_name": "関連顧客",
  "property": {"table_id": "tblXXX", "multiple": true}
}

データテーブル管理

⚠️ 権限管理（重要）：

• API で作成されたテーブルは、デフォルトではボットのみに表示されます。
• 作成後、ユーザーを共同作業者として追加する必要があります。

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

• 権限タイプ：view / edit / full_access

ビュー管理

ビュータイプ: grid(テーブル) / kanban(カンバン) / gallery(ギャラリー) / gantt(ガントチャート)

権限管理

ロールタイプ: owner / editor / reader

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

/apps/:app_token/tables/:table_id/statistics このインターフェースは存在しません。飛書公式ドキュメントには統計集計 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