接口名称

工作城市查询API -（IFeishuUserV3WorkCity）

功能描述

飞书工作城市查询接口，用于查询工作城市信息。工作城市是用户属性之一，通过工作城市API仅支持查询工作城市信息。当前接口使用用户令牌访问，适用于用户应用场景，为用户提供便捷的工作城市信息查询服务，支持用户查看可用的工作城市选项。

参考文档

函数列表

函数名称	功能描述	认证方式	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": 401,
  "msg": "用户令牌已过期，请重新登录"
}

说明：

用户令牌版本仅提供查询权限，不能修改工作城市信息
返回的结果会自动过滤掉用户无权访问的工作城市
建议缓存查询结果以提升用户体验

代码示例：

javascript

// 为用户提供工作城市选择器（用户端应用）
async function loadWorkCitySelector() {
  let allWorkCities = [];
  let pageToken = null;
  const userLanguage = navigator.language || 'zh_cn';

  try {
    // 显示加载状态
    showLoadingIndicator('正在加载工作城市...');

    do {
      const response = await feishuUserV3WorkCity.getWorkCitesListAsync(
        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 {
        throw new Error(response.msg);
      }
    } while (pageToken);

    // 渲染城市选择器
    renderWorkCitySelector(allWorkCities, userLanguage);
    
  } catch (error) {
    console.error('加载工作城市失败:', error);
    showErrorMessage('加载工作城市失败，请稍后重试');
  } finally {
    hideLoadingIndicator();
  }
}

// 渲染工作城市选择器
function renderWorkCitySelector(cities, userLanguage) {
  const selector = document.getElementById('work-city-selector');
  const localizedCities = cities.map(city => ({
    id: city.work_city_id,
    name: getLocalizedCityNameForUser(city.i18n_name, userLanguage),
    originalName: city.name,
    status: city.status
  }));

  // 按名称排序
  localizedCities.sort((a, b) => a.name.localeCompare(b.name));

  // 生成选项HTML
  const optionsHTML = localizedCities.map(city => 
    `<option value="${city.id}">${city.name}</option>`
  ).join('');

  selector.innerHTML = `
    <option value="">请选择工作城市</option>
    ${optionsHTML}
  `;

  // 缓存数据供后续使用
  sessionStorage.setItem('userWorkCities', JSON.stringify(localizedCities));
  
  console.log(`已为用户加载 ${localizedCities.length} 个可用工作城市`);
}

// 获取用户本地化的城市名称
function getLocalizedCityNameForUser(i18nNames, userLanguage) {
  // 获取用户浏览器语言偏好
  const browserLanguage = userLanguage.toLowerCase();
  
  // 尝试匹配用户语言
  let preferredName = i18nNames.find(item => 
    item.locale.toLowerCase() === browserLanguage ||
    item.locale.toLowerCase().startsWith(browserLanguage.split('-')[0])
  );

  // 如果没有找到匹配的语言，使用中文作为默认
  if (!preferredName) {
    preferredName = i18nNames.find(item => item.locale === 'zh_cn');
  }

  // 最后使用英文作为备选
  if (!preferredName) {
    preferredName = i18nNames.find(item => item.locale === 'en');
  }

  return preferredName ? preferredName.text : i18nNames[0]?.text || '未知城市';
}

// 显示加载指示器
function showLoadingIndicator(message) {
  const indicator = document.getElementById('loading-indicator');
  if (indicator) {
    indicator.textContent = message;
    indicator.style.display = 'block';
  }
}

// 隐藏加载指示器
function hideLoadingIndicator() {
  const indicator = document.getElementById('loading-indicator');
  if (indicator) {
    indicator.style.display = 'none';
  }
}

// 显示错误消息
function showErrorMessage(message) {
  const errorDiv = document.getElementById('error-message');
  if (errorDiv) {
    errorDiv.textContent = message;
    errorDiv.style.display = 'block';
  }
}

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

函数签名：

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": "用户无权限访问该工作城市信息"
}

说明：

用户只能访问有权限的工作城市信息
建议在用户选择城市前验证访问权限
提供友好的错误提示以提升用户体验

代码示例：

javascript

// 用户选择工作城市时的验证和显示
async function handleWorkCitySelection(cityId) {
  const userLanguage = navigator.language || 'zh_cn';

  try {
    // 显示选择中状态
    showCitySelectionInProgress(cityId);

    // 获取工作城市详细信息
    const response = await feishuUserV3WorkCity.getWorkCityByIdAsync(cityId);

    if (response.code === 0) {
      const workCity = response.data.work_city;
      
      // 验证城市是否可用
      if (!workCity.status) {
        showCitySelectionError(cityId, '该工作城市暂时不可用，请选择其他城市');
        return;
      }

      // 获取本地化城市名称
      const localizedName = getLocalizedCityNameForUser(workCity.i18n_name, userLanguage);
      
      // 显示城市详情
      displayWorkCityDetails({
        id: workCity.work_city_id,
        name: localizedName,
        status: workCity.status,
        isAvailable: true
      });

      // 记录用户选择（用于个性化推荐）
      recordUserCitySelection(cityId, workCity.name);
      
    } else {
      // 处理API错误
      handleApiError(response, cityId);
    }
  } catch (error) {
    console.error('获取工作城市信息时发生错误:', error);
    showCitySelectionError(cityId, '网络错误，请检查网络连接后重试');
  }
}

// 显示工作城市详情
function displayWorkCityDetails(cityInfo) {
  const detailsContainer = document.getElementById('city-details');
  
  detailsContainer.innerHTML = `
    <div class="city-info-card">
      <h3>您选择的工作城市</h3>
      <div class="city-name">${cityInfo.name}</div>
      <div class="city-status ${cityInfo.status ? 'available' : 'unavailable'}">
        ${cityInfo.status ? '✅ 可用' : '❌ 不可用'}
      </div>
      <div class="city-id">城市ID: ${cityInfo.id}</div>
      
      <div class="city-actions">
        <button onclick="confirmCitySelection('${cityInfo.id}', '${cityInfo.name}')" 
                class="confirm-btn ${cityInfo.isAvailable ? '' : 'disabled'}"
                ${!cityInfo.isAvailable ? 'disabled' : ''}>
          确认选择
        </button>
        <button onclick="resetCitySelection()" class="reset-btn">
          重新选择
        </button>
      </div>
    </div>
  `;

  detailsContainer.style.display = 'block';
}

// 处理API错误
function handleApiError(response, cityId) {
  let errorMessage = '';
  
  switch (response.code) {
    case 404:
      errorMessage = '工作城市不存在，请重新选择';
      break;
    case 403:
      errorMessage = '您无权限访问该工作城市';
      break;
    case 401:
      errorMessage = '登录已过期，请重新登录';
      // 可以触发重新登录流程
      setTimeout(() => {
        if (confirm('登录已过期，是否重新登录？')) {
          redirectToLogin();
        }
      }, 1000);
      break;
    default:
      errorMessage = response.msg || '未知错误，请稍后重试';
  }

  showCitySelectionError(cityId, errorMessage);
}

// 记录用户选择（用于个性化）
function recordUserCitySelection(cityId, cityName) {
  // 获取用户历史选择记录
  let selectionHistory = JSON.parse(localStorage.getItem('userCitySelectionHistory') || '[]');
  
  // 添加新的选择记录
  selectionHistory.unshift({
    cityId,
    cityName,
    selectedAt: new Date().toISOString()
  });

  // 只保留最近10次选择
  selectionHistory = selectionHistory.slice(0, 10);
  
  localStorage.setItem('userCitySelectionHistory', JSON.stringify(selectionHistory));
  
  console.log('用户工作城市选择已记录:', cityName);
}

// 显示城市选择进行中状态
function showCitySelectionInProgress(cityId) {
  const detailsContainer = document.getElementById('city-details');
  detailsContainer.innerHTML = `
    <div class="loading-card">
      <div class="spinner"></div>
      <p>正在获取城市信息...</p>
    </div>
  `;
  detailsContainer.style.display = 'block';
}

// 显示城市选择错误
function showCitySelectionError(cityId, errorMessage) {
  const detailsContainer = document.getElementById('city-details');
  detailsContainer.innerHTML = `
    <div class="error-card">
      <div class="error-icon">⚠️</div>
      <p class="error-message">${errorMessage}</p>
      <button onclick="resetCitySelection()" class="retry-btn">
        重新选择
      </button>
    </div>
  `;
  detailsContainer.style.display = 'block';
}

// 确认城市选择
function confirmCitySelection(cityId, cityName) {
  // 保存用户选择到用户配置
  localStorage.setItem('selectedWorkCity', JSON.stringify({
    cityId,
    cityName,
    selectedAt: new Date().toISOString()
  }));

  // 显示成功消息
  showSuccessMessage(`工作城市已设置为: ${cityName}`);
  
  // 可以触发后续流程，如表单提交等
  onWorkCityConfirmed(cityId, cityName);
}

// 重置城市选择
function resetCitySelection() {
  const detailsContainer = document.getElementById('city-details');
  detailsContainer.style.display = 'none';
  
  // 清除选择器
  const selector = document.getElementById('work-city-selector');
  if (selector) {
    selector.value = '';
  }
}

// 显示成功消息
function showSuccessMessage(message) {
  const successDiv = document.createElement('div');
  successDiv.className = 'success-message';
  successDiv.textContent = message;
  
  document.body.appendChild(successDiv);
  
  setTimeout(() => {
    successDiv.remove();
  }, 3000);
}

// 城市选择确认后的回调
function onWorkCityConfirmed(cityId, cityName) {
  console.log(`用户已确认工作城市选择: ${cityName} (${cityId})`);
  // 这里可以触发后续的业务逻辑
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193

部门管理

员工管理

用户管理

用户组管理

职位管理

角色管理

工作城市管理

接口名称

功能描述

参考文档

函数列表

函数详细内容

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

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

接口名称 ​

功能描述 ​

参考文档 ​

函数列表 ​

函数详细内容 ​

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

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

接口名称

功能描述

参考文档

函数列表

函数详细内容

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

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