在企业微信开发中,cgi-bin/user/getuserinfo
是一个重要的 API 接口,用于 根据 OAuth2 授权码 (code
) 获取用户的基本信息。这个接口通常用于在企业微信的网页中,通过 OAuth2 授权流程获取当前访问用户的身份信息。
接口说明
-
接口地址:
复制
GET https://qyapi.weixin.qq.com/cgi-bin/user/getuserinfo?access_token=ACCESS_TOKEN&code=CODE
-
参数:
-
access_token
: 企业的access_token
,通过corpid
和corpsecret
获取。 -
code
: OAuth2 授权流程中获取的授权码。
-
-
返回值:
-
如果用户是企业成员,返回
UserId
(用户在企业微信中的唯一标识)。 -
如果用户是非企业成员(如外部联系人),返回
OpenId
(用户在微信中的唯一标识)。 -
示例返回值:
json
复制
{ "errcode": 0, "errmsg": "ok", "UserId": "USERID", "OpenId": "OPENID", "DeviceId": "DEVICEID" }
-
使用场景
-
获取当前用户身份:
-
在企业微信的网页中,通过 OAuth2 授权流程获取当前访问用户的身份信息。
-
例如,用户访问一个网页时,可以通过该接口判断用户是否是企业成员。
-
-
个性化展示:
-
根据用户的身份信息,展示不同的内容或功能。
-
例如,企业成员可以看到内部数据,而非企业成员只能看到公开信息。
-
-
用户绑定:
- 根据
UserId
或OpenId
,将用户与企业内部系统进行绑定。
- 根据
调用流程
-
引导用户授权:
-
构造授权 URL,引导用户访问并授权。
-
授权 URL 格式:
复制
https://open.weixin.qq.com/connect/oauth2/authorize?appid=YOUR_CORPID&redirect_uri=REDIRECT_URI&response_type=code&scope=snsapi_base&state=STATE#wechat_redirect
-
REDIRECT_URI
是授权后重定向的 URL。 -
scope
可以是snsapi_base
(静默授权)或snsapi_userinfo
(需要用户确认)。
-
-
-
获取授权码 (
code
):- 用户授权后,企业微信会跳转到
REDIRECT_URI
,并附带一个code
参数。
- 用户授权后,企业微信会跳转到
-
调用
cgi-bin/user/getuserinfo
接口:- 使用
code
和企业的access_token
调用cgi-bin/user/getuserinfo
接口,获取用户信息。
- 使用
Java 示例代码
以下是使用 Java 调用 cgi-bin/user/getuserinfo
接口的示例代码:
java
复制
import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import com.alibaba.fastjson.JSONObject;
public class WeChatUserInfo {
// 获取用户信息的接口地址
private static final String USER_INFO_URL = "https://qyapi.weixin.qq.com/cgi-bin/user/getuserinfo?access_token=%s&code=%s";
/**
* 发送 HTTP GET 请求
*/
private static String httpGet(String url) throws IOException {
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
HttpGet httpGet = new HttpGet(url);
try (CloseableHttpResponse response = httpClient.execute(httpGet)) {
HttpEntity entity = response.getEntity();
return EntityUtils.toString(entity);
}
}
}
/**
* 获取用户信息
*/
public static JSONObject getUserInfo(String accessToken, String code) throws IOException {
String url = String.format(USER_INFO_URL, accessToken, code);
String response = httpGet(url);
return JSONObject.parseObject(response);
}
public static void main(String[] args) throws IOException {
// 企业的 access_token
String accessToken = "YOUR_ACCESS_TOKEN";
// OAuth2 授权码
String code = "USER_AUTHORIZATION_CODE";
// 获取用户信息
JSONObject userInfo = getUserInfo(accessToken, code);
System.out.println("用户信息: " + userInfo);
// 判断用户身份
if (userInfo.containsKey("UserId")) {
String userId = userInfo.getString("UserId");
System.out.println("用户是企业成员,UserId: " + userId);
} else if (userInfo.containsKey("OpenId")) {
String openId = userInfo.getString("OpenId");
System.out.println("用户是非企业成员,OpenId: " + openId);
} else {
System.out.println("获取用户信息失败: " + userInfo);
}
}
}
返回值解析
-
UserId
:-
如果用户是企业成员,返回
UserId
,表示用户在企业微信中的唯一标识。 -
可以通过
cgi-bin/user/get
接口获取用户的详细信息。
-
-
OpenId
:- 如果用户是非企业成员(如外部联系人),返回
OpenId
,表示用户在微信中的唯一标识。
- 如果用户是非企业成员(如外部联系人),返回
-
DeviceId
:- 如果用户是通过硬件扫码登录的,返回
DeviceId
,表示设备的唯一标识。
- 如果用户是通过硬件扫码登录的,返回
注意事项
-
code
的有效性:-
code
只能使用一次,且有效期为 5 分钟。 -
如果
code
失效,需要重新引导用户授权。
-
-
access_token
的有效性:access_token
的有效期为 2 小时,需要定时刷新。
-
安全性:
access_token
和code
是敏感信息,不要泄露给客户端或第三方。
总结
-
cgi-bin/user/getuserinfo
接口用于根据 OAuth2 授权码 (code
) 获取用户的基本信息。 -
通过该接口可以判断用户是否是企业成员,并获取用户的唯一标识(
UserId
或OpenId
)。 -
在企业微信开发中,该接口常用于用户身份验证和个性化展示。