接口名称

工作城市管理API -（IFeishuTenantV3WorkCity）

功能描述

飞书工作城市管理接口，用于查询租户下的工作城市信息。工作城市是用户属性之一，用于标识员工的主要工作地点，便于企业进行人员管理和区域统计。当前接口使用租户令牌访问，适用于租户应用场景，支持获取租户下所有工作城市信息和指定工作城市的详细信息。

参考文档

函数列表

函数名称	功能描述	认证方式	HTTP 方法
GetWorkCitesListAsync	获取当前租户下所有工作城市信息	租户令牌	GET
GetWorkCityByIdAsync	获取指定工作城市的信息	租户令牌	GET

函数详细内容

函数名称：获取工作城市列表

函数签名：

csharp

Task<FeishuApiPageListResult<WorkCity>?> GetWorkCitesListAsync(
     [Query("page_size")] int? page_size = 10,
     [Query("page_token")] string? page_token = null,
     CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明	示例值
page_size	int?	⚪ 可选	分页大小，即本次请求所返回的用户信息列表内的最大条目数。默认值：10	50
page_token	string	⚪ 可选	分页标记，第一次请求不填，表示从头开始遍历	"xxx"
cancellationToken	CancellationToken	⚪ 可选	取消操作令牌	-

响应：

成功响应示例：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "work_city_id": "beijing",
        "name": "北京",
        "i18n_name": [
          {
            "locale": "zh_cn",
            "text": "北京"
          },
          {
            "locale": "en",
            "text": "Beijing"
          }
        ],
        "status": true
      },
      {
        "work_city_id": "shanghai",
        "name": "上海",
        "i18n_name": [
          {
            "locale": "zh_cn",
            "text": "上海"
          },
          {
            "locale": "en",
            "text": "Shanghai"
          }
        ],
        "status": true
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

常见错误响应：

json

{
  "code": 403,
  "msg": "无权限访问工作城市信息"
}

json

{
  "code": 400,
  "msg": "分页参数错误"
}

说明：

支持分页查询，可以获取租户下所有工作城市信息
返回结果包含多语言名称和启用状态
只有启用状态的工作城市才能分配给用户作为工作地点

代码示例：

javascript

// 获取所有可用的工作城市用于下拉选择
async function getAllAvailableWorkCities() {
  let allWorkCities = [];
  let pageToken = null;

  try {
    do {
      const response = await feishuTenantV3WorkCity.getWorkCitesListAsync(
        50, // 每页50条记录
        pageToken
      );

      if (response.code === 0) {
        // 过滤出启用的工作城市
        const enabledCities = response.data.items.filter(city => city.status);
        allWorkCities = allWorkCities.concat(enabledCities);
        pageToken = response.data.has_more ? response.data.page_token : null;
      } else {
        console.error('获取工作城市列表失败:', response.msg);
        break;
      }
    } while (pageToken);

    // 处理工作城市数据
    await processWorkCityData(allWorkCities);
    
  } catch (error) {
    console.error('获取工作城市时发生错误:', error);
  }
}

// 处理工作城市数据
async function processWorkCityData(cities) {
  // 按状态分组统计
  const statusGroups = cities.reduce((groups, city) => {
    const status = city.status ? 'enabled' : 'disabled';
    groups[status] = (groups[status] || 0) + 1;
    return groups;
  }, {});

  console.log('工作城市统计:', {
    total: cities.length,
    enabled: statusGroups.enabled || 0,
    disabled: statusGroups.disabled || 0
  });

  // 生成城市选择选项
  const cityOptions = cities
    .filter(city => city.status)
    .map(city => ({
      value: city.work_city_id,
      label: city.name,
      i18n: city.i18n_name.reduce((map, item) => {
        map[item.locale] = item.text;
        return map;
      }, {})
    }));

  // 缓存到本地存储供后续使用
  localStorage.setItem('workCities', JSON.stringify(cityOptions));
  
  console.log(`已缓存 ${cityOptions.length} 个可用工作城市`);
}

函数名称：获取指定工作城市信息

函数签名：

csharp

Task<FeishuApiResult<WorkCityResult>?> GetWorkCityByIdAsync(
   [Path] string work_city_id,
   CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明	示例值
work_city_id	string	✅ 必填	工作城市 ID	"beijing"
cancellationToken	CancellationToken	⚪ 可选	取消操作令牌	-

响应：

成功响应示例：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "work_city": {
      "work_city_id": "beijing",
      "name": "北京",
      "i18n_name": [
        {
          "locale": "zh_cn",
          "text": "北京"
        },
        {
          "locale": "en",
          "text": "Beijing"
        }
      ],
      "status": true
    }
  }
}

常见错误响应：

json

{
  "code": 404,
  "msg": "工作城市不存在"
}

json

{
  "code": 403,
  "msg": "无权限访问该工作城市信息"
}

说明：

根据工作城市ID获取详细的单一工作城市信息
返回结果包含完整的城市信息和多语言支持
可用于验证城市是否可用以及获取本地化名称

代码示例：

javascript

// 验证工作城市并获取本地化名称
async function validateAndLocalizeWorkCity(cityId, userLocale = 'zh_cn') {
  try {
    const response = await feishuTenantV3WorkCity.getWorkCityByIdAsync(cityId);

    if (response.code === 0) {
      const workCity = response.data.work_city;
      
      // 检查城市是否启用
      if (!workCity.status) {
        console.warn(`工作城市 ${cityId} 已被禁用`);
        return {
          isValid: false,
          reason: '城市已禁用'
        };
      }

      // 获取本地化城市名称
      const localizedName = getLocalizedCityName(workCity.i18n_name, userLocale);
      
      console.log(`工作城市验证成功:`, {
        id: workCity.work_city_id,
        name: localizedName,
        status: workCity.status ? '启用' : '禁用'
      });

      return {
        isValid: true,
        city: {
          id: workCity.work_city_id,
          name: localizedName,
          originalName: workCity.name,
          status: workCity.status,
          i18nNames: workCity.i18n_name
        }
      };
    } else {
      console.error('获取工作城市信息失败:', response.msg);
      return {
        isValid: false,
        reason: response.msg
      };
    }
  } catch (error) {
    console.error('验证工作城市时发生错误:', error);
    return {
      isValid: false,
      reason: '网络错误'
    };
  }
}

// 获取本地化城市名称
function getLocalizedCityName(i18nNames, preferredLocale) {
  // 首先尝试获取首选语言的名称
  const preferredName = i18nNames.find(item => item.locale === preferredLocale);
  if (preferredName) {
    return preferredName.text;
  }

  // 如果没有首选语言，尝试获取中文
  const chineseName = i18nNames.find(item => item.locale === 'zh_cn');
  if (chineseName) {
    return chineseName.text;
  }

  // 最后返回英文名称或默认名称
  const englishName = i18nNames.find(item => item.locale === 'en');
  return englishName ? englishName.text : i18nNames[0]?.text || '未知城市';
}

// 批量验证工作城市
async function batchValidateWorkCities(cityIds, userLocale = 'zh_cn') {
  const validationResults = [];
  
  for (const cityId of cityIds) {
    const result = await validateAndLocalizeWorkCity(cityId, userLocale);
    validationResults.push({
      cityId,
      ...result
    });
  }

  // 统计验证结果
  const validCount = validationResults.filter(r => r.isValid).length;
  const invalidCount = validationResults.length - validCount;
  
  console.log(`工作城市批量验证完成:`, {
    total: validationResults.length,
    valid: validCount,
    invalid: invalidCount
  });

  return validationResults;
}

部门管理

员工管理

用户管理

用户组管理

职位管理

角色管理

工作城市管理

接口名称

功能描述

参考文档

函数列表

函数详细内容

函数名称：获取工作城市列表

函数名称：获取指定工作城市信息

接口名称 ​

功能描述 ​

参考文档 ​

函数列表 ​

函数详细内容 ​

函数名称：获取工作城市列表 ​

函数名称：获取指定工作城市信息 ​

接口名称

功能描述

参考文档

函数列表

函数详细内容

函数名称：获取工作城市列表

函数名称：获取指定工作城市信息