Mud Tools

接口名称

用户管理API（用户令牌）- IFeishuUserV3User

功能描述

飞书用户是飞书通讯录中的基础资源，对应企业组织架构中的成员实体。当前接口使用用户令牌访问，适用于用户应用场景，提供用户信息查询和搜索等基础功能。

参考文档

https://open.feishu.cn/document/server-docs/contact-v3/user/field-overview

函数列表

函数名称	功能描述	认证方式	HTTP 方法
GetUsersByKeywordAsync	通过关键词搜索用户信息	用户令牌	GET
GetUserInfoAsync	获取当前用户信息	用户令牌	GET
UpdateUserAsync	更新用户信息	用户令牌	PATCH
GetUserInfoByIdAsync	获取指定用户信息	用户令牌	GET
GetUserByIdsAsync	批量获取用户信息	用户令牌	GET
GetUserByDepartmentIdAsync	获取指定部门直属用户列表	用户令牌	GET

函数详细内容

函数名称：关键词搜索用户

函数签名：

csharp

Task<FeishuApiResult<UserSearchListResult>?> GetUsersByKeywordAsync(
    [Query("query")] string query,
    [Query("page_size")] int? page_size = 10,
    [Query("page_token")] string? page_token = null,
    CancellationToken cancellationToken = default);

认证：用户令牌

参数：

参数名	类型	必填	说明
query	string	✅ 必填	搜索关键词
page_size	int?	⚪ 可选	分页大小，默认10，最大50
page_token	string	⚪ 可选	分页标记，首次请求不填

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "user_list": [
      {
        "user_id": "ou_1234567890",
        "name": "张三",
        "avatar": {
          "avatar_72": "https://example.com/avatar.jpg"
        },
        "department_ids": ["od-1234567890"]
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

说明：

通过用户名关键词进行模糊搜索
使用用户令牌只能搜索有权限查看的用户
返回用户头像、姓名、部门等基本信息
支持分页查询

代码示例：

javascript

// 搜索用户函数
async function searchUsers(keyword, pageSize = 10) {
  let hasMore = true;
  let pageToken = null;
  const allUsers = [];

  while (hasMore) {
    const result = await feishuUserV3User.getUsersByKeywordAsync(
      keyword,
      pageSize,
      pageToken
    );

    if (result.code === 0) {
      allUsers.push(...result.data.user_list);
      hasMore = result.data.has_more;
      pageToken = result.data.page_token;
    } else {
      console.error("搜索失败:", result.msg);
      break;
    }
  }

  return allUsers;
}

// 使用示例：搜索技术部门的用户
const techUsers = await searchUsers("技术");
console.log(`找到 ${techUsers.length} 个相关用户`);

techUsers.forEach(user => {
  console.log(`- ${user.name.zh_cn} (${user.user_id})`);
  console.log(`  头像: ${user.avatar?.avatar_72 || '无头像'}`);
  console.log(`  部门数: ${user.department_ids.length}`);
});

函数名称：获取当前用户信息

函数签名：

csharp

Task<FeishuApiResult<GetUserDataResult>> GetUserInfoAsync(
    CancellationToken cancellationToken = default);

认证：用户令牌

参数：

参数名	类型	必填	说明
无	-	-	该函数无需参数

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "user": {
      "user_id": "ou_1234567890",
      "open_id": "ou_1234567890",
      "union_id": "on_1234567890",
      "name": "张三",
      "email": "zhangsan@example.com",
      "mobile": "13800138000",
      "avatar": {
        "avatar_72": "https://example.com/avatar.jpg",
        "avatar_240": "https://example.com/avatar_240.jpg"
      },
      "status": {
        "is_activated": true,
        "is_exited": false
      },
      "department_ids": ["od-1234567890"],
      "leader_user_id": "ou_1234567891"
    }
  }
}

说明：

使用用户访问令牌获取当前登录用户的信息
无需传入用户ID，系统自动识别当前用户
返回用户的完整信息，包括联系方式和部门信息

代码示例：

javascript

// 获取当前用户信息
const result = await feishuUserV3User.getUserInfoAsync();

if (result.code === 0) {
  const user = result.data.user;
  
  console.log(`当前用户信息:`);
  console.log(`姓名: ${user.name.zh_cn || user.name.en_us}`);
  console.log(`邮箱: ${user.email}`);
  console.log(`手机: ${user.mobile}`);
  console.log(`用户ID: ${user.user_id}`);
  console.log(`OpenID: ${user.open_id}`);
  console.log(`UnionID: ${user.union_id}`);
  
  // 检查用户状态
  if (user.status.is_activated) {
    console.log('账户状态: 已激活');
  } else {
    console.log('账户状态: 未激活');
  }
  
  // 显示部门信息
  if (user.department_ids && user.department_ids.length > 0) {
    console.log(`所属部门数量: ${user.department_ids.length}`);
    console.log(`部门ID列表: ${user.department_ids.join(', ')}`);
  }
  
  // 显示头像
  if (user.avatar && user.avatar.avatar_240) {
    console.log(`头像地址: ${user.avatar.avatar_240}`);
  }
} else {
  console.error('获取用户信息失败:', result.msg);
  // 可能的错误处理
  switch (result.code) {
    case 401:
      console.log('用户未登录或令牌已过期');
      // 跳转到登录页面
      break;
    case 403:
      console.log('权限不足');
      break;
    default:
      console.log('未知错误');
  }
}

函数名称：更新用户信息

函数签名：

csharp

Task<FeishuApiResult<CreateOrUpdateUserResult>?> UpdateUserAsync(
    [Path] string user_id,
    [Body] UpdateUserRequest userModel,
    [Query("user_id_type")] string? user_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：用户令牌

参数：

参数名	类型	必填	说明
user_id	string	✅ 必填	用户ID
userModel	UpdateUserRequest	✅ 必填	更新用户的请求体
user_id_type	string	⚪ 可选	用户ID类型，默认为"open_id"
department_id_type	string	⚪ 可选	部门ID类型，默认为"open_department_id"

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "user": {
      "user_id": "ou_1234567890",
      "name": "张三",
      "email": "zhangsan@example.com",
      "department_ids": ["od-1234567890"]
    }
  }
}

说明：

使用用户令牌只能更新当前用户的信息
仅更新显式传入的字段
部分敏感信息（如邮箱、手机号）可能需要额外验证

代码示例：

javascript

// 先获取当前用户信息
const userInfoResult = await feishuUserV3User.getUserInfoAsync();
if (userInfoResult.code !== 0) {
  console.error('获取用户信息失败');
  return;
}

const currentUserId = userInfoResult.data.user.user_id;

// 更新用户头像
async function updateProfile() {
  const updateRequest = {
    name: { 
      zh_cn: "张三（已更新）",
      en_us: "Zhang San (Updated)"
    },
    // 更新其他可修改的字段
    city: "北京",
    gender: 1, // 1:男 2:女 0:保密
    mobile_visible: true
  };

  const result = await feishuUserV3User.updateUserAsync(
    currentUserId,
    updateRequest,
    "open_id",
    "open_department_id"
  );

  if (result.code === 0) {
    console.log('用户信息更新成功');
    console.log('新的姓名:', result.data.user.name.zh_cn);
    
    // 重新获取用户信息验证更新结果
    const updatedUserInfo = await feishuUserV3User.getUserInfoAsync();
    if (updatedUserInfo.code === 0) {
      console.log('验证更新结果:');
      console.log('- 姓名:', updatedUserInfo.data.user.name.zh_cn);
      console.log('- 城市:', updatedUserInfo.data.user.city || '未设置');
    }
  } else {
    console.error('更新失败:', result.msg);
    
    // 错误处理
    switch (result.code) {
      case 400:
        console.log('请求参数错误');
        break;
      case 403:
        console.log('权限不足，无法更新此字段');
        break;
      case 404:
        console.log('用户不存在');
        break;
      default:
        console.log('更新失败，请稍后重试');
    }
  }
}

updateProfile();

函数名称：获取指定用户信息

函数签名：

csharp

Task<FeishuApiResult<GetUserInfoResult>> GetUserInfoByIdAsync(
    [Path] string user_id,
    [Query("user_id_type")] string? user_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：用户令牌

参数：

参数名	类型	必填	说明
user_id	string	✅ 必填	用户ID
user_id_type	string	⚪ 可选	用户ID类型，默认为"open_id"
department_id_type	string	⚪ 可选	部门ID类型，默认为"open_department_id"

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "user": {
      "user_id": "ou_1234567890",
      "open_id": "ou_1234567890",
      "union_id": "on_1234567890",
      "name": "张三",
      "email": "zhangsan@example.com",
      "mobile": "13800138000",
      "avatar": {
        "avatar_72": "https://example.com/avatar.jpg",
        "avatar_240": "https://example.com/avatar_240.jpg"
      },
      "status": {
        "is_activated": true,
        "is_exited": false
      },
      "department_ids": ["od-1234567890"]
    }
  }
}

说明：

使用用户令牌只能获取有权限查看的用户信息
对于敏感信息（如手机号、邮箱），可能因为权限限制而不可见
返回用户的详细信息和状态

代码示例：

javascript

// 获取指定用户信息函数
async function getUserInfo(userId, userIdType = "open_id") {
  const result = await feishuUserV3User.getUserInfoByIdAsync(
    userId,
    userIdType,
    "open_department_id"
  );

  if (result.code === 0) {
    const user = result.data.user;
    
    console.log(`用户信息获取成功:`);
    console.log(`姓名: ${user.name.zh_cn || user.name.en_us || '未设置'}`);
    console.log(`用户ID: ${user.user_id}`);
    console.log(`状态: ${user.status.is_activated ? '已激活' : '未激活'}`);
    
    // 显示联系方式（如果有权限）
    if (user.email) {
      console.log(`邮箱: ${user.email}`);
    }
    if (user.mobile) {
      console.log(`手机: ${user.mobile}`);
    }
    
    // 显示部门信息
    if (user.department_ids && user.department_ids.length > 0) {
      console.log(`所属部门数量: ${user.department_ids.length}`);
    }
    
    // 显示头像
    if (user.avatar) {
      console.log(`头像(72px): ${user.avatar.avatar_72}`);
      console.log(`头像(240px): ${user.avatar.avatar_240}`);
    }
    
    return user;
  } else {
    console.error(`获取用户 ${userId} 信息失败:`, result.msg);
    
    // 权限相关错误处理
    if (result.code === 403) {
      console.log('权限不足，无法查看该用户信息');
    } else if (result.code === 404) {
      console.log('用户不存在或已离职');
    }
    
    return null;
  }
}

// 使用示例：从搜索结果中获取详细信息
async function getUserDetailsFromSearch(keyword) {
  // 先搜索用户
  const searchResult = await feishuUserV3User.getUsersByKeywordAsync(keyword, 5);
  
  if (searchResult.code === 0 && searchResult.data.user_list.length > 0) {
    const firstUser = searchResult.data.user_list[0];
    console.log(`找到用户: ${firstUser.name.zh_cn}`);
    
    // 获取详细信息
    const detailedInfo = await getUserInfo(firstUser.user_id);
    if (detailedInfo) {
      console.log('详细用户信息已获取');
    }
  } else {
    console.log('未找到匹配的用户');
  }
}

getUserDetailsFromSearch("张");

函数名称：批量获取用户信息

函数签名：

csharp

Task<FeishuApiResult<GetUserInfosResult>?> GetUserByIdsAsync(
   [Query("user_ids")] string[] user_ids,
   [Query("user_id_type")] string? user_id_type = "open_id",
   [Query("department_id_type")] string? department_id_type = "open_department_id",
   CancellationToken cancellationToken = default);

认证：用户令牌

参数：

参数名	类型	必填	说明
user_ids	string[]	✅ 必填	用户ID数组
user_id_type	string	⚪ 可选	用户ID类型，默认为"open_id"
department_id_type	string	⚪ 可选	部门ID类型，默认为"open_department_id"

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "user_list": [
      {
        "user_id": "ou_1234567890",
        "name": "张三",
        "email": "zhangsan@example.com",
        "department_ids": ["od-1234567890"],
        "status": {
          "is_activated": true
        }
      }
    ]
  }
}

说明：

使用用户令牌只能获取有权限查看的用户信息
支持一次查询多个用户（最多50个）
返回用户的基本信息，敏感信息可能被过滤

代码示例：

javascript

// 批量获取用户信息
async function getBatchUserInfo(userIds) {
  if (!userIds || userIds.length === 0) {
    console.log('用户ID列表不能为空');
    return [];
  }

  // 限制单次查询数量
  const maxBatchSize = 50;
  const allUsers = [];
  
  for (let i = 0; i < userIds.length; i += maxBatchSize) {
    const batch = userIds.slice(i, i + maxBatchSize);
    
    const result = await feishuUserV3User.getUserByIdsAsync(
      batch,
      "open_id",
      "open_department_id"
    );

    if (result.code === 0) {
      allUsers.push(...result.data.user_list);
      console.log(`批次 ${Math.floor(i / maxBatchSize) + 1}: 获取到 ${result.data.user_list.length} 个用户信息`);
    } else {
      console.error(`批次查询失败:`, result.msg);
    }
  }

  return allUsers;
}

// 使用示例：从搜索结果批量获取详细信息
async function batchGetUserDetails(searchKeyword) {
  // 先搜索用户
  const searchResult = await feishuUserV3User.getUsersByKeywordAsync(searchKeyword, 20);
  
  if (searchResult.code === 0) {
    const userIds = searchResult.data.user_list.map(user => user.user_id);
    console.log(`准备批量获取 ${userIds.length} 个用户的详细信息`);
    
    const detailedUsers = await getBatchUserInfo(userIds);
    
    // 分析用户信息
    console.log('\n用户详细信息统计:');
    console.log(`总用户数: ${detailedUsers.length}`);
    
    const activatedUsers = detailedUsers.filter(user => user.status.is_activated);
    console.log(`已激活用户: ${activatedUsers.length}`);
    
    const usersWithEmail = detailedUsers.filter(user => user.email);
    console.log(`有邮箱信息的用户: ${usersWithEmail.length}`);
    
    // 显示用户列表
    detailedUsers.forEach(user => {
      const status = user.status.is_activated ? '已激活' : '未激活';
      const email = user.email || '未设置';
      const deptCount = user.department_ids ? user.department_ids.length : 0;
      
      console.log(`- ${user.name.zh_cn || user.name.en_us} (${status})`);
      console.log(`  邮箱: ${email}`);
      console.log(`  部门数: ${deptCount}`);
    });
  } else {
    console.error('搜索用户失败:', searchResult.msg);
  }
}

batchGetUserDetails("技术");

函数名称：获取部门用户列表

函数签名：

csharp

Task<FeishuApiResult<GetUserInfosResult>?> GetUserByDepartmentIdAsync(
    [Query("department_id")] string department_id,
    [Query("page_size")] int page_size = 10,
    [Query("page_token")] string? page_token = null,
    [Query("user_id_type")] string? user_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：用户令牌

参数：

参数名	类型	必填	说明
department_id	string	✅ 必填	部门ID
page_size	int	⚪ 可选	分页大小，默认10，最大50
page_token	string	⚪ 可选	分页标记，首次请求不填
user_id_type	string	⚪ 可选	用户ID类型，默认为"open_id"
department_id_type	string	⚪ 可选	部门ID类型，默认为"open_department_id"

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "user_list": [
      {
        "user_id": "ou_1234567890",
        "name": "张三",
        "email": "zhangsan@example.com",
        "department_ids": ["od-1234567890"],
        "status": {
          "is_activated": true
        }
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

说明：

使用用户令牌只能获取有权限查看的部门用户
获取指定部门直属的用户列表（不包含子部门）
支持分页查询，适合获取大量用户

代码示例：

javascript

// 获取部门所有用户（支持分页）
async function getDepartmentUsers(departmentId, pageSize = 50) {
  let hasMore = true;
  let pageToken = null;
  const allUsers = [];
  let pageCount = 0;

  while (hasMore) {
    pageCount++;
    console.log(`正在获取第 ${pageCount} 页数据...`);
    
    const result = await feishuUserV3User.getUserByDepartmentIdAsync(
      departmentId,
      pageSize,
      pageToken,
      "open_id",
      "open_department_id"
    );

    if (result.code === 0) {
      allUsers.push(...result.data.user_list);
      hasMore = result.data.has_more;
      pageToken = result.data.page_token;
      
      console.log(`第 ${pageCount} 页获取到 ${result.data.user_list.length} 个用户`);
    } else {
      console.error(`第 ${pageCount} 页获取失败:`, result.msg);
      break;
    }
  }

  return allUsers;
}

// 分析部门用户信息
async function analyzeDepartmentUsers(departmentId) {
  console.log(`开始分析部门 ${departmentId} 的用户信息...`);
  
  const users = await getDepartmentUsers(departmentId);
  
  if (users.length === 0) {
    console.log('该部门没有用户或没有权限查看');
    return;
  }

  console.log(`\n=== 部门用户分析报告 ===`);
  console.log(`总用户数: ${users.length}`);
  
  // 用户状态统计
  const activatedCount = users.filter(user => user.status.is_activated).length;
  console.log(`已激活用户: ${activatedCount} (${(activatedCount/users.length*100).toFixed(1)}%)`);
  
  // 联系方式统计
  const usersWithEmail = users.filter(user => user.email).length;
  const usersWithMobile = users.filter(user => user.mobile).length;
  console.log(`有邮箱的用户: ${usersWithEmail} (${(usersWithEmail/users.length*100).toFixed(1)}%)`);
  console.log(`有手机号的用户: ${usersWithMobile} (${(usersWithMobile/users.length*100).toFixed(1)}%)`);
  
  // 部门分布统计
  const deptCounts = {};
  users.forEach(user => {
    const deptCount = user.department_ids ? user.department_ids.length : 0;
    deptCounts[deptCount] = (deptCounts[deptCount] || 0) + 1;
  });
  
  console.log('\n多部门归属情况:');
  Object.keys(deptCounts).sort().forEach(count => {
    console.log(`  归属 ${count} 个部门: ${deptCounts[count]} 人`);
  });
  
  // 用户列表
  console.log('\n=== 用户详情 ===');
  users.forEach((user, index) => {
    const status = user.status.is_activated ? '✓已激活' : '✗未激活';
    const email = user.email || '未设置';
    const mobile = user.mobile || '未设置';
    const deptCount = user.department_ids ? user.department_ids.length : 0;
    
    console.log(`${index + 1}. ${user.name.zh_cn || user.name.en_us} (${status})`);
    console.log(`   邮箱: ${email}`);
    console.log(`   手机: ${mobile}`);
    console.log(`   归属部门数: ${deptCount}`);
  });
}

// 使用示例：获取当前用户所在部门的所有同事
async function getColleagues() {
  // 先获取当前用户信息
  const currentUserResult = await feishuUserV3User.getUserInfoAsync();
  
  if (currentUserResult.code === 0) {
    const currentUser = currentUserResult.data.user;
    console.log(`当前用户: ${currentUser.name.zh_cn || currentUser.name.en_us}`);
    
    if (currentUser.department_ids && currentUser.department_ids.length > 0) {
      // 分析第一个部门的用户
      await analyzeDepartmentUsers(currentUser.department_ids[0]);
    } else {
      console.log('当前用户未归属任何部门');
    }
  } else {
    console.error('获取当前用户信息失败');
  }
}

getColleagues();

部门管理

员工管理

用户管理

用户组管理

职位管理

角色管理

工作城市管理

接口名称

功能描述

参考文档

函数列表

函数详细内容

函数名称：关键词搜索用户

函数名称：获取当前用户信息

函数名称：更新用户信息

函数名称：获取指定用户信息

函数名称：批量获取用户信息

函数名称：获取部门用户列表

接口名称 ​

功能描述 ​

参考文档 ​

函数列表 ​

函数详细内容 ​

函数名称：关键词搜索用户 ​

函数名称：获取当前用户信息 ​

函数名称：更新用户信息 ​

函数名称：获取指定用户信息 ​

函数名称：批量获取用户信息 ​

函数名称：获取部门用户列表 ​

接口名称

功能描述

参考文档

函数列表

函数详细内容

函数名称：关键词搜索用户

函数名称：获取当前用户信息

函数名称：更新用户信息

函数名称：获取指定用户信息

函数名称：批量获取用户信息

函数名称：获取部门用户列表