飛書組織構造と ID 変換

Contact v3 API を通じて、メンバー検索、部門管理、ID 変換を実現します。

API の基本

ベース URL: https://open.feishu.cn/open-apis/contact/v3
認証: Authorization: Bearer {tenant_access_token}

認証とトークンの取得

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

メンバー検索

部門管理

⚠️ 部門の作成とメンバーの入社には最高権限が必要です。プレリリース環境でのテストをお勧めします。

ユーザーグループ管理

職位管理

ロール管理

ID 変換（コア）

飛書には 3 種類の ID システムがあります。

Contact v3 ID 変換

ID 変換のベストプラクティス：

GET /users/{user_id} インターフェースを使用すると、ユーザーのすべての ID タイプ（open_id/user_id/union_id）を一度に取得でき、個別に変換する必要はありません。

例：

GET /contact/v3/users/ou_xxx?user_id_type=open_id

応答に含まれるもの：

{
  "data": {
    "user": {
      "open_id": "ou_xxx",
      "user_id": "7c43cd5f",
      "union_id": "on_xxx"
    }
  }
}

その他

イベント購読

連絡先は 17 の変更イベントをサポートしています。

ベストプラクティス

1. ID 変換は Spark API を優先します（より簡潔です）
2. よく使う ID をキャッシュします（API 呼び出しを減らします）
3. 組織構造の変更は必ずプレリリース環境でテストします