飞書カレンダー

Calendar API を通じて日程を管理します。

Base URL: https://open.feishu.cn/open-apis/calendar/v4

認証とトークン取得

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分前に更新）

---

日程操作

API	エンドポイント	メソッド	リクエストボディ例	説明
日程作成	/calendars/{calendar_id}/events	POST	{"summary":"会議標題","start_time":{"timestamp":"1770508800"},"end_time":{"timestamp":"1770512400"}}	新しい日程を作成
日程取得	/calendars/{calendar_id}/events/{event_id}	GET	-	日程の詳細を検索
日程更新	/calendars/{calendar_id}/events/{event_id}	PATCH	{"summary":"新しいタイトル"}	日程を変更
日程削除	/calendars/{calendar_id}/events/{event_id}	DELETE	-	日程を削除
日程検索	/calendars/{calendar_id}/events/search	POST	{"query":"キーワード","start_time":{"timestamp":"1770508800"}}	条件で検索
日程リスト取得	/calendars/{calendar_id}/events	GET	-	カレンダー下の全日程を検索

日程作成:

{
  "summary": "会議標題",
  "start_time": {"timestamp": "1770508800"},
  "end_time": {"timestamp": "1770512400"},
  "attendees": [{"type": "user", "attendee_id": "ou_xxx"}]
}

attendees type: user / chat / resource(会議室)

---

日程参加者

API	エンドポイント	メソッド	リクエストボディ例	説明
参加者取得	/calendars/{calendar_id}/events/{event_id}/attendees	GET	-	参加者リストを検索
参加者追加	/calendars/{calendar_id}/events/{event_id}/attendees	POST	{"attendees":[{"type":"user","attendee_id":"ou_xxx"}]}	参加者を招待
参加者削除	/calendars/{calendar_id}/events/{event_id}/attendees/{attendee_id}	DELETE	-	参加者を削除
グループ参加メンバー取得	/calendars/{calendar_id}/events/{event_id}/attendees/chat_members	GET	-	グループ参加メンバーを検索

---

カレンダー管理

API	エンドポイント	メソッド	リクエストボディ例	説明
カレンダーリスト取得	/calendars	GET	クエリパラメータ：page_size=50&page_token=xxx	全カレンダーを検索（ページング）
メインカレンダー取得	/calendars/primary	GET	-	ユーザーのメインカレンダーを検索
カレンダー作成	/calendars	POST	{"summary":"カレンダー名","description":"説明","permissions":"public"}	共有カレンダーを作成
カレンダー取得	/calendars/{calendar_id}	GET	-	カレンダーの詳細を検索
カレンダー更新	/calendars/{calendar_id}	PATCH	{"summary":"新しい名前"}	カレンダーを変更
カレンダー削除	/calendars/{calendar_id}	DELETE	-	カレンダーを削除
カレンダー検索	/calendars/search	POST	{"query":"キーワード"}	カレンダーを検索

---

カレンダー購読と ACL

API	エンドポイント	メソッド	リクエストボディ例	説明
ACL リスト取得	/calendars/{calendar_id}/acls	GET	-	カレンダーの権限を検索
ACL 作成	/calendars/{calendar_id}/acls	POST	{"role":"reader","scope":{"type":"user","user_id":"ou_xxx"}}	権限を追加
ACL 削除	/calendars/{calendar_id}/acls/{acl_id}	DELETE	-	権限を削除
カレンダー購読	/calendars/{calendar_id}/subscribe	POST	-	カレンダー変更を購読
購読キャンセル	/calendars/{calendar_id}/unsubscribe	POST	-	カレンダー購読をキャンセル
日程イベント購読	/calendars/{calendar_id}/events/subscribe	POST	-	日程変更を購読
日程購読キャンセル	/calendars/{calendar_id}/events/unsubscribe	POST	-	日程購読をキャンセル

ACL role: none / free_busy_reader / reader / writer / owner

---

会議室管理

API	エンドポイント	メソッド	リクエストボディ例	説明
会議室リスト取得	/rooms	GET	-	全会議室を検索
会議室取得	/rooms/{room_id}	GET	-	会議室の詳細を検索
会議室の空き時間確認	/rooms/{room_id}/freebusy	GET	-	会議室の利用可能時間を検索

日程を作成して会議室を予約

会議室を予約する重要ポイント：attendees に type: "resource" の参加者を追加し、attendee_id に会議室の room_id を入力します。

完全な流れ：

# 1. 会議室リストを取得し、room_id を取得
curl -X GET "https://open.feishu.cn/open-apis/calendar/v4/rooms?page_size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 2. （オプション）対象時間帯の会議室が空いているかどうかを確認
curl -X GET "https://open.feishu.cn/open-apis/calendar/v4/rooms/{room_id}/freebusy?start_time=1770508800&end_time=1770512400" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 3. 日程を作成し、attendees に会議室を追加
curl -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars/primary/events" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "チームミーティング",
    "start_time": {"timestamp": "1770508800"},
    "end_time": {"timestamp": "1770512400"},
    "attendees": [
      {"type": "user", "attendee_id": "ou_xxx"},
      {"type": "resource", "attendee_id": "omcxxxxxxxxxxxxx"}
    ]
  }'

⚠️ 会議室がその時間帯に既に予約されている場合、作成リクエストは競合エラーを返します。予約前に空き時間を確認してください。

---

一般的なパラメータ説明

時間形式:

• timestamp: 秒単位のタイムスタンプ（例："1770508800"）
• date: 日付文字列（例："2026-03-07"）

ページングパラメータ:

• page_size: 1ページあたりの数量（デフォルト 50、最大 500）
• page_token: ページングマーク（前回のレスポンスから取得）

user_id_type: ユーザー ID タイプ

• open_id（デフォルト）
• user_id
• union_id

---

テスト例

カレンダーリスト取得:

curl -X GET "https://open.feishu.cn/open-apis/calendar/v4/calendars?page_size=10" \
  -H "Authorization: Bearer ${TOKEN}"

日程作成:

curl -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars/primary/events" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "チームミーティング",
    "start_time": {"timestamp": "1709798400"},
    "end_time": {"timestamp": "1709802000"}
  }'

---

ベストプラクティス

1. 時間は秒単位のタイムスタンプを使用
2. attendees にタイプを指定（user/chat/resource）
3. ページング検索：大量データの場合は page_token でページング
4. メインカレンダー：ユーザー個人カレンダーは calendar_id として primary を使用