3.公众号 - 1.ILazyWeChatBasic

一些基础接口

GetAccessTokenAsync

作用

用于获取公众号的全局唯一接口调用凭据 access_token
1. access_token的有效期目前为2个小时，需定时刷新，重复获取将导致上次获取的access_token失效
2. 每日调用量上限(次) : 100000
方法说明
- 请求方式 : Get
- 请求地址 : https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
- 参数
  
  参数是否必须说明
  
  grant_type 是获取access_token填写client_credential
  
  appid 是第三方用户唯一凭证
  
  secret 是第三方用户唯一凭证密钥，即appsecret
- 返回值 : string, 即获取到的access_token
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Get_access_token.html
示例代码
- 调用方式 : 异步
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

参数	是否必须	说明
grant_type	是	获取access_token填写client_credential
appid	是	第三方用户唯一凭证
secret	是	第三方用户唯一凭证密钥，即appsecret

  private readonly ILazyWeChatBasic _lazyWeChatBasic;
  public DemoController(ILazyWeChatBasic lazyWeChatBasic)
  {
  	_lazyWeChatBasic = lazyWeChatBasic;
  }
  
  public async Task GetAccessToken()
  {
  	var access_token = await _lazyWeChatBasic.GetAccessTokenAsync();
  }

备注 : 该接口会缓存请求过的access_token以备复用, 如发现access_token已经过期, 该接口会重新想微信服务器发送请求并获取新的access_token

后续的API接口中都会自动调用该接口来获取access_token, 有一部分LazyWeChat未完成的API接口, 如用户需要,可使用此接口获取access_token

GetWeChatIPAddress

官方文档 : https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Get_the_WeChat_server_IP_address.html
示例代码
- 调用方式 : 异步
- 返回值 : dynamic
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

var ipList1 = await _lazyWeChatBasic.GetWeChatAPIIPListAsync();
var ipList2 = await _lazyWeChatBasic.GetWeChatCallbackIPListAsync();

微信网页开发

GetAuthorizationCode

作用

用于向用户发起请求授权, 并获取授权code
1. 该请求会将页面重定向到微信的服务器地址, 微信服务器验证通过后悔重新重定向到指定地址, 并在URL中携带code
2. 该code用于获取网页授权的access_token(该access_token与上面的不同, 这个access_token用于网页授权来换取用户openid以及相关微信头像等信息)
3. 获取code有两种方式
  1. snsapi_base 不弹出授权页面，直接跳转，只能获取用户openid
  2. snsapi_userinfo 弹出授权页面，可通过openid拿到昵称、性别、所在地。并且，即使在未关注的情况下，只要用户授权，也能获取其信息
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html#0
示例代码
- 调用方式 : 同步
- 参数
  - HttpContext
  - scopt : snsapi_userinfo 或者 snsapi_base
- 返回值 : string
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
public IActionResult GetAuthorizationCode()
{
    var code = _lazyWeChatBasic.GetAuthorizationCode(this.HttpContext, SCOPE.snsapi_userinfo);
    if (!string.IsNullOrEmpty(code))
    {
        return Redirect($"Index?code={code}");
    }
    else
    {
        return View();
    }
}
```
备注 : 在获取GetAuthorizationCode的Action中不要添加额外代码, 因为_lazyWeChatBasic.GetAuthorizationCode中会有页面重定向, 添加额外代码可能导致无法获取到code

GetWebAccessTokenAsync

作用

获取用来换取用户相关微信信息的网页授权access_token
方法说明
- 请求方式 : Get
- 请求地址 : https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code
- 参数
  
  参数是否必须说明
  
  appid 是公众号的唯一标识
  
  secret 是公众号的appsecret
  
  code 是填写第一步获取的code参数
  
  grant_type 是填写为authorization_code
- 返回值
  - 成功的情况
```
{ 
  "access_token":"ACCESS_TOKEN",
  "expires_in":7200,
  "refresh_token":"REFRESH_TOKEN",
  "openid":"OPENID",
  "scope":"SCOPE" 
}
```
  - 失败的情况
```
{"errcode":40029,"errmsg":"invalid code"}
```
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html#1
示例代码 : 参考下面获取用户信息的示例代码

参数	是否必须	说明
appid	是	公众号的唯一标识
secret	是	公众号的appsecret
code	是	填写第一步获取的code参数
grant_type	是	填写为authorization_code

GetUserInfoAsync

作用

用于根据网页授权的access_token获取用户相关信息
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html#3
示例代码
- 调用方式 : 异步
- 参数
  - GetWebAccessTokenAsync
    - code : GetAuthorizationCode中获取的code
  - GetUserInfoAsync
    - access_token
    - openid
    - lang
- 返回值
  - GetWebAccessTokenAsync : dynamic
  - GetUserInfoAsync : dynamic
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
public async Task<IActionResult> Index()
{
    var code = "";
    if (!HttpContext.Request.Query.Keys.Contains("code"))
        return Redirect("Home/GetAuthorizationCode");
    else
        code = HttpContext.Request.Query["code"].ToString();

    var webAccessToken = await _lazyWeChatBasic.GetWebAccessTokenAsync(code);

    var access_token = webAccessToken.access_token;
    var openid = webAccessToken.openid;
    var res = await _lazyWeChatBasic.GetUserInfoAsync(access_token, openid, "zh-CN");
    var userInfo = JsonConvert.SerializeObject(res);

    _logger.LogInformation($"UserInfo :{userInfo}");

    return View();
}
```
备注 : GetWebAccessTokenAsync与GetUserInfoAsync均已经在方法内部进行了返回值的判断, 若请求获得失败返回值, 方法会throw自定义Exception (BadResultException) 具体的errcode与errmsg可在exception中查看;

由于方法的返回值为dynamic类型, 所以Visual Studio不会有相应的智能感知, 请根据文档中json的数据格式自行获取需要的值

后续大部分的API返回值均已上诉形式体现

ValidateWebAccessTokenAsync

作用

检验授权凭证（access_token）是否有效
方法说明
- 请求方式 : Get
- 请求地址 : https://api.weixin.qq.com/sns/auth?access_token=ACCESS_TOKEN&openid=OPENID
- 参数
  
  参数描述
  
  access_token 网页授权接口调用凭证,注意：此access_token与基础支持的access_token不同
  
  openid 用户的唯一标识
- 返回值
  - 成功的情况
```
{ "errcode":0,"errmsg":"ok"}
```
  - 失败的情况
```
{ "errcode":40003,"errmsg":"invalid openid"}
```
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html#4

参数	描述
access_token	网页授权接口调用凭证,注意：此access_token与基础支持的access_token不同
openid	用户的唯一标识

示例代码

调用方式 : 异步
返回值 : bool
前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

public async Task ValidateWebAccessToken()
{
    var access_token = "36_cV3XgPSq5rRa7ECkfysj6eytpDARsR7Obc3ZnqcNPybNGkuIwCl0cUec0OPP-sCWeQcvz7xAEKNuERY8hz2r02Xdt3n5x6MFkZ2h7F97wrU";
    var openid = "oNDiC0d-r7Su5mYCU-mXFSXuhmtQ";
    var res = await _lazyWeChatBasic.ValidateWebAccessTokenAsync(access_token, openid);
}

GetJSTicketAsync

作用

jsapi_ticket是公众号用于调用微信JS接口的临时票据
1. jsapi_ticket的有效期为7200秒，通过access_token来获取
2. 由于获取jsapi_ticket的api调用次数非常有限，频繁刷新jsapi_ticket会导致api调用受限，影响自身业务，开发者必须在自己的服务全局缓存jsapi_ticket
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html#62
示例代码
- 调用方式 : 异步
- 返回值 : string
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
var jsapi = await _lazyWeChatBasic.GetJSTicketAsync();
```

GenerateWXConfigScriptAsync

作用

用于生成wx.config的JS脚本
1. jsapi_ticket的有效期为7200秒，通过access_token来获取
2. 由于获取jsapi_ticket的api调用次数非常有限，频繁刷新jsapi_ticket会导致api调用受限，影响自身业务，开发者必须在自己的服务全局缓存jsapi_ticket
3. 每日调用量上限(次) : 5000000
4. 需要绑定JS安全接口域名, 先登录微信公众平台进入“公众号设置”的“功能设置”里填写“JS接口安全域名”。
5. 页面中添加JSSDK引用, 具体版本请参考 https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html#3
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html

示例代码

调用方式 : 异步
参数
- HttpContext
- debug : 是否为debug模式(如果为true, 则会在js-sdk被触发的同事弹出成功或者失败的提示, 如果失败会提示错误原因)
- jsApiList : 需要使用的JS接口列表

返回值 : string, 将返回如下的JS代码

wx.config({
  debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。
  appId: '', // 必填，公众号的唯一标识
  timestamp: , // 必填，生成签名的时间戳
  nonceStr: '', // 必填，生成签名的随机串
  signature: '',// 必填，签名
  jsApiList: [] // 必填，需要使用的JS接口列表
});

前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置 ;

例如 : 需要在页面显示拍照或从手机相册中选图的接口(wx.chooseImage) 和使用微信内置地图查看位置接口(wx.openLocation)

API代码 :

public async Task<IActionResult> JSSDK()
{
    var context = HttpContext;
    var debug = true;

    ViewBag.js = await _lazyWeChatBasic.GenerateWXConfigScriptAsync(
        context, debug, "chooseImage", "openLocation");

    return View();
}

注意

如果使用了nginx等工具做了反向代理, 则可能出现 "invalid signature"的错误提示, 常规的解决方案腾讯都已经在如下链接中给出(参见附录5-常见错误及解决方法), 但是前面我提到的错误原因并不包含在其中

https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html#62

通过下面的Link, 大家可以测试自己生产的signature是否正确

https://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=jsapisign

GenerateWXConfigScriptAsync需要传递HttpContext作为参数, 该参数用于获取当前页面URL, 方法如下

public static string ToAbsoluteUri(this HttpRequest httpRequest)
{
    var x_http_scheme = httpRequest.Headers["X-Http-Scheme"].ToString();
    var scheme = string.IsNullOrEmpty(x_http_scheme) ? httpRequest.Scheme : x_http_scheme;
    return new StringBuilder()
    .Append(scheme)
    .Append("://")
    .Append(httpRequest.Host)
    .Append(httpRequest.PathBase)
    .Append(httpRequest.Path)
    .Append(httpRequest.QueryString)
    .ToString();
}

博主本人就用了nginx反向代理, 且使用了ssl协议(https), 并将http请求转发到了https上, 在测试环境中博主使用nginx反向代理至http://localhost:5000 这个地址, 具体的nginx配置如下, 如果在nginx中没有设置X-Http-Scheme, 则程序会读取httpRequest.Scheme, 但是该值在此情况下为http, 测试博主读取到的完整URL则为http://test.lazywechat.cn, 但是实际的URL为https://test.lazywechat.cn , 这样导致了签名无效。所以请记住上诉情况需要配置X-Http-Scheme

server {
    listen 80;
    server_name test.lazywechat.cn;   
    rewrite ^(.*)$ https://$host$1 permanent;   #将所有http请求通过rewrite重定向到https。
    location / {
        index index.html index.htm;
    }
}
server {
    listen 443 ssl;
    server_name  test.lazywechat.cn;
    root html;
    index index.html index.htm;
    ssl_certificate cert/4274199_test.lazywechat.cn.pem;   		#.pem证书的路径。
    ssl_certificate_key cert/4274199_test.lazywechat.cn.key;   	#.key证书的路径。
    ssl_session_timeout 5m;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;  
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;  
    ssl_prefer_server_ciphers on; 
    location / {            
        proxy_pass         http://localhost:5000;				#反向代理地址
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_set_header   X-Http-scheme https;					#指定X-Http-Scheme的值为https
    }
}

或者使用GenerateWXConfigScriptAsync的重载方法, 直接传递requestUrl

Task<string> GenerateWXConfigScriptAsync(string requestUrl, bool debug, params string[] jsApiList);

Html代码

<html>
<head>
    <meta name="viewport" content="width=device-width" />
    <title>JSSDK</title>
    <script type="text/javascript" src="https://res2.wx.qq.com/open/js/jweixin-1.6.0.js"></script>
    <script src="~/lib/jquery/dist/jquery.js"></script>
    <script type="text/javascript">
        @Html.Raw(ViewBag.js)
        wx.ready(function () {
            $("#chooseImg").click(function () {
                wx.chooseImage({
                    count: 1, // 默认9
                    sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图，默认二者都有
                    sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机，默认二者都有
                    success: function (res) {
                        var localIds = res.localIds; // 返回选定照片的本地ID列表，localId可以作为img标签的src属性显示图片
                    }
                });
            })
    
            $("#openLocation").click(function () {
                wx.openLocation({
                    latitude: 0, // 纬度，浮点数，范围为90 ~ -90
                    longitude: 0, // 经度，浮点数，范围为180 ~ -180。
                    name: '', // 位置名
                    address: '', // 地址详情说明
                    scale: 1, // 地图缩放级别,整形值,范围从1~28。默认为最大
                    infoUrl: '' // 在查看位置界面底部显示的超链接,可点击跳转
                });
            })
    
        });
    </script>

</head>
<body>
    <button id="chooseImg">choose images</button>
    <button id="openLocation">open location</button>
</body>
</html>

注意 : wx.chooseImage等方法需要包裹在wx.ready之中, 该函数用于判断wx.config函数是否加载完成, 若在未加载完成之时绑定方法事件, 则可能出现错误, 可参考如下官方文档

https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html#5

用户管理

CreateTagAsync

作用

为公众号中的用户创建标签, 一个公众号, 最多可以创建100个标签
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/User_Tag_Management.html
示例代码
- 调用方式 : 异步
- 参数
  - tagName
- 返回值
  - dynamic : 成功时
```
{ "tag":{ "id":134,"name":"广东" } } 
```
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
  - GetWebAccessTokenAsync : dynamic
  - GetUserInfoAsync : dynamic
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
var res = await _lazyWeChatBasic.CreateTagAsync("Test Tags");
```

GetTagsAsync

作用

获取公众号已创建的标签
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/User_Tag_Management.html

示例代码

调用方式 : 异步

返回值

dynamic : 成功时

{   
"tags":[{       
    "id":1,       
    "name":"每天一罐可乐星人",      
    "count":0 //此标签下粉丝数
},
{   
    "id":2,   
    "name":"星标组",   
    "count":0
},
{   
    "id":127,  
    "name":"广东",  
    "count":5 
 }   
] }

前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

var res = await _lazyWeChatBasic.CreateTagAsync("Test Tags");

EditTagAsync

作用

编辑标签
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/User_Tag_Management.html

示例代码

调用方式 : 异步
参数 :
- tagId
- tagName
返回值
- dynamic : 成功时
```
{   "errcode":0,   "errmsg":"ok" } 
```
前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

var res = _lazyWeChatBasic.GetTagsAsync().Result;
var tags = res.tags as List<dynamic>;
foreach (var item in tags)
{
    if (item.name != "星标组")
        res = _lazyWeChatBasic.EditTagAsync(item.id, item.name + "-edit").Result;
}

DeleteTagAsync

作用

删除标签
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/User_Tag_Management.html

示例代码

调用方式 : 异步
参数 :
- tagId
返回值
- dynamic : 成功时
```
{   "errcode":0,   "errmsg":"ok" } 
```
前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

var res = _lazyWeChatBasic.GetTagsAsync().Result;
var tags = res.tags as List<dynamic>;
foreach (var item in tags)
{
    if (item.name != "星标组")
        res = _lazyWeChatBasic.DeleteTagAsync(item.id).Result;
}

SetTagforUsersAsync

作用

批量为用户打标签
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/User_Tag_Management.html
示例代码
- 调用方式 : 异步
- 参数 :
  - tagId
  - openids : 要设置tag的用户openid数组, 该参数为params string[]类型
- 返回值
  - dynamic : 成功时
```
{  
    "errcode":0,   
    "errmsg":"ok"
} 
```
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
var res = await _lazyWeChatBasic.SetTagforUsersAsync(tagId, "oNDiC0d-r7Su5mYCU-mXFSXuhmtQ");
```

GetTagUsersAsync

作用

获取标签下粉丝列表
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/User_Tag_Management.html

示例代码

调用方式 : 异步
参数 :
- tagId
- next_openid : 第一个拉取的OPENID，不填默认从头开始拉取

返回值

dynamic : 成功时

{  
    "count":2,//这次获取的粉丝数量   
    "data":{//粉丝列表
        "openid":[  
        "ocYxcuAEy30bX0NXmGn4ypqx3tI0",    
        "ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"  ]  
    },  
    "next_openid":"ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"//拉取列表最后一个用户的openid 
}

前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

 var res = await _lazyWeChatBasic.GetTagUsersAsync(tagId, "");

RemoveTagforUsersAsync

作用

批量为用户取消标签
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/User_Tag_Management.html
示例代码
- 调用方式 : 异步
- 参数 :
  - tagId
  - openids : 要设置tag的用户openid数组, 该参数为params string[]类型
- 返回值
  - dynamic : 成功时
```
{  
    "errcode":0,   
    "errmsg":"ok"
} 
```
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
res = await _lazyWeChatBasic.RemoveTagforUsersAsync(tagId, openid);
```

GetUserTagsAsync

作用

获取用户身上的标签列表
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/User_Tag_Management.html
示例代码
- 调用方式 : 异步
- 参数 :
  - openid
- 返回值
  - dynamic : 成功时
```
{   
    "tagid_list":
    [  
        134, 2 //被置上的标签列表  
    ] 
} 
```
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
 var res = await _lazyWeChatBasic.GetUserTagsAsync(openid);
```

SetCommentsforUsersAsync

作用

开发者可以通过该接口对指定用户设置备注名
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/Configuring_user_notes.html
示例代码
- 调用方式 : 异步
- 参数 :
  - remark
  - openid
- 返回值
  - dynamic : 成功时
```
{
    "errcode":0,
    "errmsg":"ok" 
}
```
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
 var res = await _lazyWeChatBasic.SetCommentsforUsersAsync(openid);
```

GetUserDetailsAsync

作用

获取用户基本信息(UnionID机制)
1. 在关注者与公众号产生消息交互后，公众号可获得关注者的OpenID（加密后的微信号，每个用户对每个公众号的OpenID是唯一的。对于不同公众号，同一用户的openid不同）。公众号可通过本接口来根据OpenID获取用户基本信息，包括昵称、头像、性别、所在城市、语言和关注时间。
2. 如果开发者有在多个公众号，或在公众号、移动应用之间统一用户帐号的需求，需要前往微信开放平台（open.weixin.qq.com）绑定公众号后，才可利用UnionID机制来满足上述需求
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/Get_users_basic_information_UnionID.html

示例代码

调用方式 : 异步
参数 :
- openid
- lang

返回值

dynamic : 成功时

{
    "subscribe": 1, 
    "openid": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M", 
    "nickname": "Band", 
    "sex": 1, 
    "language": "zh_CN", 
    "city": "广州", 
    "province": "广东", 
    "country": "中国",  
  "headimgurl":"http://thirdwx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/0",
    "subscribe_time": 1382694957,
    "unionid": " o6_bmasdasdsad6_2sgVt7hMZOPfL"
    "remark": "",
    "groupid": 0,
    "tagid_list":[128,2],
    "subscribe_scene": "ADD_SCENE_QR_CODE",
    "qr_scene": 98765,
    "qr_scene_str": ""
}

备注 : 如未在开发平台绑定公众号, 则unionid这一列不会出现

前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

 var userInfo = await _lazyWeChatBasic.GetUserDetailsAsync(openid, "zh_CN");

GetUserListAsync

作用

通过本接口来获取帐号的关注者列表，关注者列表由一串OpenID（加密后的微信号，每个用户对每个公众号的OpenID是唯一的）组成。一次拉取调用最多拉取10000个关注者的OpenID，可以通过多次拉取的方式来满足需求。
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/Getting_a_User_List.html
示例代码
- 调用方式 : 异步
- 参数 :
  - next_openid : 第一个拉取的OPENID，不填默认从头开始拉取
- 返回值
  - dynamic : 成功时
```
{
    "total":2,
    "count":2,
    "data":{
    "openid":["OPENID1","OPENID2"]},
    "next_openid":"NEXT_OPENID"
}
```
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
var userList = await _lazyWeChatBasic.GetUserListAsync("");
```

GetUsersDetailsAsync

作用

批量获取用户基本信息
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/Get_users_basic_information_UnionID.html

示例代码

调用方式 : 异步
参数 :
- user_list : 一个元组的列表,元组中的第一个元素为openid, 第二个元素为language, 指定该用户需要获取的语言信息

返回值

dynamic : 成功时

{
    "total":2,
    "count":2,
    "data":{
    "openid":["OPENID1","OPENID2"]},
    "next_openid":"NEXT_OPENID"
}

前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

var userList = await _lazyWeChatBasic.GetUserListAsync("");

var openids = userList.data.openid as List<object>;

var user_list = new List<(string, string)>();
openids.Take(10).ToList().ForEach(i =>
{
	user_list.Add((i.ToString(), "zh_CN"));
});
var res = await _lazyWeChatBasic.GetUsersDetailsAsync(user_list);

GetBlacklistAsync

作用

获取公众号的黑名单列表
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/Getting_a_User_List.html

示例代码

调用方式 : 异步
参数 :
- begin_openid : begin_openid 为空时，默认从开头拉取

返回值

dynamic : 成功时

{
 "total":23000,
 "count":10000,
 "data":{"
    openid":[
       "OPENID1",
       "OPENID2",
       ...,
       "OPENID10000"
    ]
  },
  "next_openid":"OPENID10000"
}

前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

var blackList = await _lazyWeChatBasic.GetBlacklistAsync("");

SetBlackUsersAsync

作用

拉黑用户
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/Manage_blacklist.html
示例代码
- 调用方式 : 异步
- 参数 :
  - openid_list : 需要拉入黑名单的用户的openid，一次拉黑最多允许20个
- 返回值
  - dynamic : 成功时
```
{
  "errcode": 0,
  "errmsg": "ok"
}
```
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
var result = await _lazyWeChatBasic.SetBlackUsersAsync(openid);
```

CancelBlackUsersAsync

作用

取消拉黑用户
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/Manage_blacklist.html

示例代码

调用方式 : 异步
参数 :
- openid_list : 需要取消拉入黑名单的用户的openid，一次拉黑最多允许20个
返回值
- dynamic : 成功时
```
{
  "errcode": 0,
  "errmsg": "ok"
}
```
前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

var userList = await _lazyWeChatBasic.GetUserListAsync("");

var openids = userList.data.openid as List<object>;

var user_list = new List<string>();
openids.Take(3).ToList().ForEach(i =>
{
	user_list.Add(i.ToString());
});

var blackList = await _lazyWeChatBasic.GetBlacklistAsync("");
var result = await _lazyWeChatBasic.SetBlackUsersAsync(user_list.ToArray());
if (result1.errmsg == "ok")
{
    blackList = await _lazyWeChatBasic.GetBlacklistAsync("");
    result = await _lazyWeChatBasic.CancelBlackUsersAsync(user_list.ToArray());
}

账号管理

GenerateQRCodeAsync

作用

用来生成事件推送的二维码
1. 临时二维码
  1. 是有过期时间的，最长可以设置为在二维码生成后的30天（即2592000秒）后过期
  2. 临时二维码主要用于帐号绑定等不要求二维码永久保存的业务场景
2. 永久二维码
  1. 是无过期时间的，但数量较少（目前为最多10万个）
  2. 永久二维码主要用于适用于帐号绑定、用户来源统计等场景
3. 用户扫描带场景值二维码时，可能推送以下两种事件(可以在中间件的onScanEvent中触发扫描改二维码的事件)
  1. 如果用户还未关注公众号，则用户可以关注公众号，关注后微信会将带场景值关注事件推送给开发者
  2. 如果用户已经关注公众号，在用户扫描后会自动进入会话，微信也会将带场景值扫描事件推送给开发者
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/Account_Management/Generating_a_Parametric_QR_Code.html
示例代码
- 调用方式 : 异步
- 参数 :
  - tempOrNot : 是否临时二维码
  - expire_seconds : 过期时间
  - scene_value : 场景值
    - 场景值可以是 INT (scene_id) : 场景值ID，临时二维码时为32位非0整型，永久二维码时最大值为100000（目前参数只支持1--100000）
    - 也可以是 STRING (scene_str) : 场景值ID（字符串形式的ID），字符串类型，长度限制为1到64
- 返回值
  - string : 二维码的URL, 例如 https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=gQH27zoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL3JqcFJmWGJsRlpsc0I4eHhseFNOAAIE64gXVwMEEA4AAA==
    
    可以采用如下使用方式在页面中显示或者直接打印出来
```
<img src="https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=gQH27zoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL3JqcFJmWGJsRlpsc0I4eHhseFNOAAIE64gXVwMEEA4AAA==" />
```
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
var res1 = await _lazyWeChatBasic.GenerateQRCodeAsync(false, 60, "scene_str");
var res2 = await _lazyWeChatBasic.GenerateQRCodeAsync(false, 60, 1);
```
上面的res1和res2分别为二维码的图片链接, 扫描该服务器二维码会触发事件推送, 可使用如下事件对二维码扫描事件进行处理
```
app.UseLazyWeChat(msg =>
{
    msg.onScanEvent((eventKey, ticket) =>
    {
        var message = $"eventKey:{eventKey},ticket:{ticket}";
        msg.replyTextMessage(message);
    });
});
```

ShortUrlAsync

作用

将一条长链接转成短链接
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/Account_Management/URL_Shortener.html
示例代码
- 调用方式 : 异步
- 参数 :
  - long_url : 原始URL
- 返回值
  - string : 短链接地址 ,例如 https://w.url.cn/s/AB2y0Qx
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
var short_url = await _lazyWeChatBasic.ShortUrlAsync("https://developers.weixin.qq.com/doc/offiaccount/Account_Management/URL_Shortener.html");
```

自定义菜单

CreateMenuAsync

作用

创建菜单
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/Custom_Menus/Creating_Custom-Defined_Menu.html

示例代码

调用方式 : 异步

参数 :

menuButton : 菜单结构(MenuButton)的class

该class有AddMenu 方法, 用于添加菜单或者子菜单(菜单类 WeChatMenu)

WeChatMenu的结构如下, 该类的结构中包含了微信菜单的所有字段, 菜单会根据类型的不同而拥有不同的字段, 开发者可以根据自己的需要选择需要赋值的字段, LazyWeChat会自动忽略未赋值字段, 具体字段选择情况请参考官方文档

public class WeChatMenu
{
    public WeChatMenu() => sub_button = new List<WeChatMenu>();

    public string type { get; set; }

    public string name { get; set; }

    public string url { get; set; }

    public string appid { get; set; }

    public string pagepath { get; set; }

    public string key { get; set; }

    public List<WeChatMenu> sub_button { get; set; }
}

菜单类型的结构如下, 菜单类型说明请参考官方文档

public enum MenuType
{
    click,
    view,
    miniprogram,
    scancode_waitmsg,
    scancode_push,
    pic_sysphoto,
    pic_photo_or_album,
    pic_weixin,
    location_select,
    media_id
}

可参考如下代码创建菜单

MenuButton menuButton = new MenuButton();
menuButton.AddMenu(new WeChatMenu
{
    type = MenuType.click.ToString(),
    name = "Click Menu",
    key = "Key_Event1",
});
var sub_button = new WeChatMenu
{
	name = "Sub Menu"
};
sub_button.sub_button.Add(new WeChatMenu
{
    type = MenuType.view.ToString(),
    name = "Sub View Menu",
    url = "http://www.soso.com/"
});
sub_button.sub_button.Add(new WeChatMenu
{
    type = MenuType.click.ToString(),
    name = "Sub Click Menu",
    key = "Key_Event2",
});

menuButton.AddMenu(sub_button);

var res = await _lazyWeChatBasic.CreateMenuAsync(menuButton);

返回值
- dynamic
```
{"errcode":0,"errmsg":"ok"}
```
前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置

GetCurrentMenuAsync

作用

获取当前菜单结构
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/Custom_Menus/Querying_Custom_Menus.html

示例代码

调用方式 : 异步
参数 :
- long_url : 原始URL

返回值

dynamic : is_menu_open 字段表示当前公众号是否设置了菜单, 1为是, 0 为否

{ 
   "is_menu_open": 1, 
   "selfmenu_info": { 
       "button": [ 
           { 
               "name": "button", 
               "sub_button": { 
                   "list": [ 
                       { 
                           "type": "view", 
                           "name": "view_url", 
                           "url": "http://www.qq.com"
                       }, 
                       { 
                           "type": "news", 
                           "name": "news", 
                           "value":"KQb_w_Tiz-nSdVLoTV35Psmty8hGBulGhEdbb9SKs-o",
                           "news_info": { 
                               "list": [ 
                                   { 
                                       "title": "MULTI_NEWS", 
                                       "author": "JIMZHENG", 
                                       "digest": "text", 
                                       "show_cover": 0, 
                                       "cover_url": "http://mmbiz.qpic.cn/mmbiz/GE7et87vE9vicuCibqXsX9GPPLuEtBfXfK0HKuBIa1A1cypS0uY1wickv70iaY1gf3I1DTszuJoS3lAVLvhTcm9sDA/0", 
                                       "content_url": "http://mp.weixin.qq.com/s?__biz=MjM5ODUwNTM3Ng==&mid=204013432&idx=1&sn=80ce6d9abcb832237bf86c87e50fda15#rd", 
                                       "source_url": ""
                                   }, 
                                   { 
                                       "title": "MULTI_NEWS1", 
                                       "author": "JIMZHENG", 
                                       "digest": "MULTI_NEWS1", 
                                       "show_cover": 1, 
                                       "cover_url": "http://mmbiz.qpic.cn/mmbiz/GE7et87vE9vicuCibqXsX9GPPLuEtBfXfKnmnpXYgWmQD5gXUrEApIYBCgvh2yHsu3ic3anDUGtUCHwjiaEC5bicd7A/0", 
                                       "content_url": "http://mp.weixin.qq.com/s?__biz=MjM5ODUwNTM3Ng==&mid=204013432&idx=2&sn=8226843afb14ecdecb08d9ce46bc1d37#rd", 
                                       "source_url": ""
                                   }
                               ]
                           }
                       },
                       {
                           "type": "video", 
                           "name": "video", 
                           "value": "http://61.182.130.30/vweixinp.tc.qq.com/1007_114bcede9a2244eeb5ab7f76d951df5f.f10.mp4?vkey=77A42D0C2015FBB0A3653D29C571B5F4BBF1D243FBEF17F09C24FF1F2F22E30881BD350E360BC53F&sha=0&save=1"
                       }, 
                       { 
                           "type": "voice",
                           "name": "voice", 
                           "value": "nTXe3aghlQ4XYHa0AQPWiQQbFW9RVtaYTLPC1PCQx11qc9UB6CiUPFjdkeEtJicn"
                       }
                   ]
               }
           }, 
           { 
               "type": "text", 
               "name": "text", 
               "value": "This is text!"
           }, 
           { 
               "type": "img", 
               "name": "photo", 
               "value": "ax5Whs5dsoomJLEppAvftBUuH7CgXCZGFbFJifmbUjnQk_ierMHY99Y5d2Cv14RD"
           }
       ]
   }
}

前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
var menu = await _lazyWeChatBasic.GetCurrentMenuAsync();
```

DeleteMenuAsync

作用

删除当前菜单结构
官方文档 : https://developers.weixin.qq.com/doc/offiaccount/Custom_Menus/Deleting_Custom-Defined_Menu.html
示例代码
- 调用方式 : 异步
- 返回值
  - dynamic
```
{"errcode":0,"errmsg":"ok"}
```
- 前提 : Startup.cs中注册 services.AddLazyPay(); 并在appsettings.json中完成LazyWeChat的配置
```
var res = await _lazyWeChatBasic.DeleteMenuAsync();
```

posted @ 2020-08-26 19:18 LazyWeChat 阅读(279) 评论(0) 收藏举报

刷新页面返回顶部

LazyWeChat

3.公众号 - 1.ILazyWeChatBasic

一些基础接口

GetAccessTokenAsync

GetWeChatIPAddress

微信网页开发

GetAuthorizationCode

GetWebAccessTokenAsync

GetUserInfoAsync

ValidateWebAccessTokenAsync

GetJSTicketAsync

GenerateWXConfigScriptAsync

用户管理

CreateTagAsync

GetTagsAsync

EditTagAsync

DeleteTagAsync

SetTagforUsersAsync

GetTagUsersAsync

RemoveTagforUsersAsync

GetUserTagsAsync

SetCommentsforUsersAsync

GetUserDetailsAsync

GetUserListAsync

GetUsersDetailsAsync

GetBlacklistAsync

SetBlackUsersAsync

CancelBlackUsersAsync

账号管理

GenerateQRCodeAsync

ShortUrlAsync

自定义菜单

CreateMenuAsync

GetCurrentMenuAsync

DeleteMenuAsync

公告