feishu-calendar

Feishu カレンダー

Calendar API を使用して予定を管理します。

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

認証とトークンの取得

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

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

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

業務 API からトークンが無効、期限切れ、または 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. メインカレンダー：ユーザー個人のカレンダーには primary を calendar_id として使用