diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpAiOpenService.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpAiOpenService.java index 07bc1e52e..ad995bba2 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpAiOpenService.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpAiOpenService.java @@ -6,74 +6,112 @@ import me.chanjar.weixin.common.error.WxErrorException; import me.chanjar.weixin.mp.enums.AiLangType; /** - * 
- * 微信AI开放接口（语音识别，微信翻译）.
- * https://mp.weixin.qq.com/wiki?t=resource/res_main&id=21516712282KzWVE
- *  Created by BinaryWang on 2018/6/9.
- *
+ * 微信AI开放接口（语音识别，微信翻译） + *

+ * 提供微信AI相关的功能，包括语音识别、微信翻译等。 + * 支持上传语音文件进行语音识别，以及文本翻译功能。 + *

+ *

+ * 详情请见：微信AI开放接口 + *

+ * Created by BinaryWang on 2018/6/9. * * @author Binary Wang */ public interface WxMpAiOpenService { - /** - * 
-   * 提交语音.
-   * http请求方式: POST
-   * http://api.weixin.qq.com/cgi-bin/media/voice/addvoicetorecofortext?access_token=ACCESS_TOKEN&format=&voice_id=xxxxxx&lang=zh_CN
-   *
- * - * @param voiceId 语音唯一标识 - * @param lang 语言，zh_CN 或 en_US，默认中文 - * @param voiceFile 语音文件 - * @throws WxErrorException the wx error exception - */ - void uploadVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException; + /** + * 
+     * 提交语音
+     *
+ * + * @param voiceId 语音唯一标识 + * @param lang 语言，zh_CN 或 en_US，默认中文 + * @param voiceFile 语音文件 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 提交语音接口 + */ + void uploadVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException; - /** - * 
-   * 获取语音识别结果.
-   * 接口调用请求说明
-   *
-   * http://api.weixin.qq.com/cgi-bin/media/voice/queryrecoresultfortext?access_token=ACCESS_TOKEN&voice_id=xxxxxx&lang=zh_CN
-   * 请注意，添加完文件之后10s内调用这个接口
-   *
-   *
- * - * @param voiceId 语音唯一标识 - * @param lang 语言，zh_CN 或 en_US，默认中文 - * @return the string - * @throws WxErrorException the wx error exception - */ - String queryRecognitionResult(String voiceId, AiLangType lang) throws WxErrorException; + /** + * 
+     * 获取语音识别结果
+     * 请注意，添加完文件之后10s内调用这个接口
+     *
+ * + * @param voiceId 语音唯一标识 + * @param lang 语言，zh_CN 或 en_US，默认中文 + * @return 语音识别结果文本 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 获取语音识别结果接口 + */ + String queryRecognitionResult(String voiceId, AiLangType lang) throws WxErrorException; - /** - * 识别指定语音文件内容. - * 此方法揉合了前两两个方法：uploadVoice 和 queryRecognitionResult - * - * @param voiceId 语音唯一标识 - * @param lang 语言，zh_CN 或 en_US，默认中文 - * @param voiceFile 语音文件 - * @return the string - * @throws WxErrorException the wx error exception - */ - String recogniseVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException; + /** + * 
+     * 识别指定语音文件内容
+     * 此方法揉合了前两两个方法：uploadVoice 和 queryRecognitionResult
+     *
+ * + * @param voiceId 语音唯一标识 + * @param lang 语言，zh_CN 或 en_US，默认中文 + * @param voiceFile 语音文件 + * @return 语音识别结果文本 + * @throws WxErrorException 微信API调用异常，可能包括： + * + */ + String recogniseVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException; - /** - * 
-   * 微信翻译.
-   * 接口调用请求说明
-   *
-   * http请求方式: POST
-   * http://api.weixin.qq.com/cgi-bin/media/voice/translatecontent?access_token=ACCESS_TOKEN&lfrom=xxx<o=xxx
-   *
-   *
- * - * @param langFrom 源语言，zh_CN 或 en_US - * @param langTo 目标语言，zh_CN 或 en_US - * @param content 要翻译的文本内容 - * @return the string - * @throws WxErrorException the wx error exception - */ - String translate(AiLangType langFrom, AiLangType langTo, String content) throws WxErrorException; + /** + * 
+     * 微信翻译
+     *
+ * + * @param langFrom 源语言，zh_CN 或 en_US + * @param langTo 目标语言，zh_CN 或 en_US + * @param content 要翻译的文本内容 + * @return 翻译结果文本 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 微信翻译接口 + */ + String translate(AiLangType langFrom, AiLangType langTo, String content) throws WxErrorException; } diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpCardService.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpCardService.java index 08c040e14..188e4be78 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpCardService.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpCardService.java @@ -7,298 +7,611 @@ import me.chanjar.weixin.mp.bean.card.*; import java.util.List; /** - * 卡券相关接口. + * 卡券相关接口 + *

+ * 提供微信卡券的创建、查询、核销、管理等功能。 + * 支持卡券API签名生成、卡券Code解码、卡券核销、库存管理等功能。 + *

+ *

+ * 详情请见：卡券开发文档 + *

* * @author YuJian(mgcnrx11 @ hotmail.com) on 01/11/2016 * @author yuanqixun 2018-08-29 */ public interface WxMpCardService { /** - * 得到WxMpService. + * 
+     * 获取WxMpService实例
+     *
* - * @return WxMpService wx mp service + * @return WxMpService实例 */ WxMpService getWxMpService(); /** - * 获得卡券api_ticket，不强制刷新卡券api_ticket. + * 
+     * 获得卡券api_ticket，不强制刷新卡券api_ticket
+     *
* - * @return 卡券api_ticket card api ticket - * @throws WxErrorException 异常 - * @see #getCardApiTicket(boolean) #getCardApiTicket(boolean)#getCardApiTicket(boolean) + * @return 卡券api_ticket + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see #getCardApiTicket(boolean) */ String getCardApiTicket() throws WxErrorException; /** * 
-     * 获得卡券api_ticket.
+     * 获得卡券api_ticket
      * 获得时会检查卡券apiToken是否过期，如果过期了，那么就刷新一下，否则就什么都不干
-     *
-     * 详情请见：http://mp.weixin.qq.com/wiki/7/aaa137b55fb2e0456bf8dd9148dd613f.html#.E9.99.84.E5.BD.954-.E5.8D.A1.E5.88.B8.E6.89.A9.E5.B1.95.E5.AD.97.E6.AE.B5.E5.8F.8A.E7.AD.BE.E5.90.8D.E7.94.9F.E6.88.90.E7.AE.97.E6.B3.95
      *
* - * @param forceRefresh 强制刷新 - * @return 卡券api_ticket card api ticket - * @throws WxErrorException 异常 + * @param forceRefresh 强制刷新，如果为true则强制刷新api_ticket + * @return 卡券api_ticket + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 卡券签名生成算法 */ String getCardApiTicket(boolean forceRefresh) throws WxErrorException; /** * 
-     * 创建调用卡券api时所需要的签名.
-     *
-     * 详情请见：http://mp.weixin.qq.com/wiki/7/aaa137b55fb2e0456bf8dd9148dd613f.html#.E9.99.84.E5.BD
-     * .954-.E5.8D.A1.E5.88.B8.E6.89.A9.E5.B1.95.E5.AD.97.E6.AE.B5.E5.8F.8A.E7.AD.BE.E5.90.8D.E7.94
-     * .9F.E6.88.90.E7.AE.97.E6.B3.95
+     * 创建调用卡券api时所需要的签名
      *
* - * @param optionalSignParam 参与签名的参数数组。可以为下列字段：app_id, card_id, card_type, code, openid, location_id
注意：当做wx.chooseCard调用时，必须传入app_id参与签名，否则会造成签名失败导致拉取卡券列表为空 - * @return 卡券Api签名对象 wx card api signature - * @throws WxErrorException 异常 + * @param optionalSignParam 参与签名的参数数组。可以为下列字段：app_id, card_id, card_type, code, openid, location_id + * 注意：当做wx.chooseCard调用时，必须传入app_id参与签名，否则会造成签名失败导致拉取卡券列表为空 + * @return 卡券Api签名对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 卡券签名生成算法 */ WxCardApiSignature createCardApiSignature(String... optionalSignParam) throws WxErrorException; /** - * 卡券Code解码. + * 
+     * 卡券Code解码
+     *
* * @param encryptCode 加密Code，通过JSSDK的chooseCard接口获得 - * @return 解密后的Code string - * @throws WxErrorException 异常 + * @return 解密后的Code + * @throws WxErrorException 微信API调用异常，可能包括： + * */ String decryptCardCode(String encryptCode) throws WxErrorException; /** - * 卡券Code查询. - * 文档地址： https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025272&anchor=1 + * 
+     * 卡券Code查询
+     *
* * @param cardId 卡券ID代表一类卡券 * @param code 单张卡券的唯一标准 * @param checkConsume 是否校验code核销状态，填入true和false时的code异常状态返回数据不同 - * @return WxMpCardResult对象 wx mp card result - * @throws WxErrorException 异常 + * @return WxMpCardResult对象，包含卡券查询结果信息 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 卡券Code查询接口 */ WxMpCardResult queryCardCode(String cardId, String code, boolean checkConsume) throws WxErrorException; /** + * 
      * 卡券Code核销。核销失败会抛出异常
+     *
* * @param code 单张卡券的唯一标准 - * @return 调用返回的JSON字符串 。可用 com.google.gson.JsonParser#parse 等方法直接取JSON串中的errcode等信息。 - * @throws WxErrorException 异常 + * @return 调用返回的JSON字符串，可用 com.google.gson.JsonParser#parse 等方法直接取JSON串中的errcode等信息 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ String consumeCardCode(String code) throws WxErrorException; /** - * 卡券Code核销。核销失败会抛出异常. + * 
+     * 卡券Code核销。核销失败会抛出异常
+     *
* * @param code 单张卡券的唯一标准 * @param cardId 当自定义Code卡券时需要传入card_id - * @return 调用返回的JSON字符串 。可用 com.google.gson.JsonParser#parse 等方法直接取JSON串中的errcode等信息。 - * @throws WxErrorException 异常 + * @return 调用返回的JSON字符串，可用 com.google.gson.JsonParser#parse 等方法直接取JSON串中的errcode等信息 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ String consumeCardCode(String code, String cardId) throws WxErrorException; /** - * 卡券Mark接口. + * 
+     * 卡券Mark接口
      * 开发者在帮助消费者核销卡券之前，必须帮助先将此code（卡券串码）与一个openid绑定（即mark住），
      * 才能进一步调用核销接口，否则报错。
+     *
* * @param code 卡券的code码 * @param cardId 卡券的ID * @param openId 用券用户的openid * @param isMark 是否要mark（占用）这个code，填写true或者false，表示占用或解除占用 - * @throws WxErrorException 异常 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ void markCardCode(String code, String cardId, String openId, boolean isMark) throws WxErrorException; /** - * 查看卡券详情接口. - * 详见 https://mp.weixin.qq.com/wiki/14/8dd77aeaee85f922db5f8aa6386d385e.html#.E6.9F.A5.E7.9C.8B.E5.8D.A1.E5.88.B8.E8.AF.A6.E6.83.85 + * 
+     * 查看卡券详情接口
+     *
* * @param cardId 卡券的ID - * @return 返回的卡券详情JSON字符串
[注] 由于返回的JSON格式过于复杂，难以定义其对应格式的Bean并且难以维护，因此只返回String格式的JSON串。
可由 com.google.gson.JsonParser#parse 等方法直接取JSON串中的某个字段。 - * @throws WxErrorException 异常 + * @return 返回的卡券详情JSON字符串 + * [注] 由于返回的JSON格式过于复杂，难以定义其对应格式的Bean并且难以维护，因此只返回String格式的JSON串。 + * 可由 com.google.gson.JsonParser#parse 等方法直接取JSON串中的某个字段。 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 查看卡券详情 */ String getCardDetail(String cardId) throws WxErrorException; /** - * 添加测试白名单. + * 
+     * 添加测试白名单
+     *
* * @param openid 用户的openid - * @return string string - * @throws WxErrorException 异常 + * @return 操作结果字符串 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ String addTestWhiteList(String openid) throws WxErrorException; /** - * 创建卡券. + * 
+     * 创建卡券
+     *
* - * @param cardCreateMessage 请求 - * @return result wx mp card create result - * @throws WxErrorException 异常 + * @param cardCreateRequest 卡券创建请求对象 + * @return 卡券创建结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ WxMpCardCreateResult createCard(WxMpCardCreateRequest cardCreateMessage) throws WxErrorException; /** - * 创建卡券二维码. + * 
+     * 创建卡券二维码
+     *
* * @param cardId 卡券编号 * @param outerStr 二维码标识 - * @return WxMpCardQrcodeCreateResult wx mp card qrcode create result - * @throws WxErrorException 异常 + * @return 卡券二维码创建结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ WxMpCardQrcodeCreateResult createQrcodeCard(String cardId, String outerStr) throws WxErrorException; /** - * 创建卡券二维码. + * 
+     * 创建卡券二维码
+     *
* * @param cardId 卡券编号 - * @param outerStr 二维码标识 + * @param outerStr 用户首次领卡时，会通过 领取事件推送 给商户； 对于会员卡的二维码，用户每次扫码打开会员卡后点击任何url，会将该值拼入url中，方便开发者定位扫码来源 * @param expiresIn 指定二维码的有效时间，范围是60 ~ 1800秒。不填默认为365天有效 - * @return WxMpCardQrcodeCreateResult wx mp card qrcode create result - * @throws WxErrorException 异常 + * @return 卡券二维码创建结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ WxMpCardQrcodeCreateResult createQrcodeCard(String cardId, String outerStr, int expiresIn) throws WxErrorException; /** - * 创建卡券二维码. + * 
+     * 创建卡券二维码
+     *
* * @param cardId 卡券编号 * @param outerStr 用户首次领卡时，会通过 领取事件推送 给商户； 对于会员卡的二维码，用户每次扫码打开会员卡后点击任何url，会将该值拼入url中，方便开发者定位扫码来源 * @param expiresIn 指定二维码的有效时间，范围是60 ~ 1800秒。不填默认为365天有效 - * @param openid 指定领取者的openid，只有该用户能领取。bind_openid字段为true的卡券必须填写，非指定openid不必填写。 - * @param code 卡券Code码,use_custom_code字段为true的卡券必须填写，非自定义code和导入code模式的卡券不必填写。 - * @param isUniqueCode 指定下发二维码，生成的二维码随机分配一个code，领取后不可再次扫描。填写true或false。默认false，注意填写该字段时，卡券须通过审核且库存不为0。 - * @return WxMpCardQrcodeCreateResult wx mp card qrcode create result - * @throws WxErrorException 异常 + * @param openid 指定领取者的openid，只有该用户能领取。bind_openid字段为true的卡券必须填写，非指定openid不必填写 + * @param code 卡券Code码,use_custom_code字段为true的卡券必须填写，非自定义code和导入code模式的卡券不必填写 + * @param isUniqueCode 指定下发二维码，生成的二维码随机分配一个code，领取后不可再次扫描。填写true或false。默认false，注意填写该字段时，卡券须通过审核且库存不为0 + * @return 卡券二维码创建结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ WxMpCardQrcodeCreateResult createQrcodeCard(String cardId, String outerStr, int expiresIn, String openid, String code, boolean isUniqueCode) throws WxErrorException; /** - * 创建卡券货架. + * 
+     * 创建卡券货架
+     *
* * @param createRequest 货架创建参数 - * @return WxMpCardLandingPageCreateResult wx mp card landing page create result - * @throws WxErrorException 异常 + * @return 货架创建结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ WxMpCardLandingPageCreateResult createLandingPage(WxMpCardLandingPageCreateRequest createRequest) throws WxErrorException; /** - * 将用户的卡券设置为失效状态. - * 详见:https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025272&anchor=9 + * 
+     * 将用户的卡券设置为失效状态
+     *
* * @param cardId 卡券编号 * @param code 用户会员卡号 * @param reason 设置为失效的原因 - * @return result string - * @throws WxErrorException 异常 + * @return 操作结果字符串 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 设置卡券失效 */ String unavailableCardCode(String cardId, String code, String reason) throws WxErrorException; /** - * 删除卡券接口. + * 
+     * 删除卡券接口
+     *
* * @param cardId 卡券id - * @return 删除结果 wx mp card delete result - * @throws WxErrorException 异常 + * @return 删除结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ WxMpCardDeleteResult deleteCard(String cardId) throws WxErrorException; /** + * 
      * 导入自定义code(仅对自定义code商户)
+     *
* * @param cardId 卡券id - * @param codeList 需导入微信卡券后台的自定义code，上限为100个。 - * @return the wx mp card code deposit result - * @throws WxErrorException the wx error exception + * @param codeList 需导入微信卡券后台的自定义code，上限为100个 + * @return 导入结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ WxMpCardCodeDepositResult cardCodeDeposit(String cardId, List codeList) throws WxErrorException; /** + * 
      * 查询导入code数目接口
+     *
* * @param cardId 卡券id - * @return the wx mp card code deposit count result - * @throws WxErrorException the wx error exception + * @return 查询结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ WxMpCardCodeDepositCountResult cardCodeDepositCount(String cardId) throws WxErrorException; /** + * 
      * 核查code接口
+     *
* * @param cardId 卡券id * @param codeList 已经微信卡券后台的自定义code，上限为100个 - * @return the wx mp card code checkcode result - * @throws WxErrorException the wx error exception + * @return 核查结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ WxMpCardCodeCheckcodeResult cardCodeCheckcode(String cardId, List codeList) throws WxErrorException; /** + * 
      * 图文消息群发卡券获取内嵌html
+     *
* * @param cardId 卡券id - * @return the wx mp card mpnews gethtml result - * @throws WxErrorException the wx error exception + * @return HTML获取结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * */ WxMpCardMpnewsGethtmlResult cardMpnewsGethtml(String cardId) throws WxErrorException; - /** + * 
      * 修改库存接口
-     * https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Managing_Coupons_Vouchers_and_Cards.html#5
+     *
* * @param cardId 卡券ID * @param changeValue 库存变更值，负值为减少库存 - * @throws WxErrorException the wx error exception + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 修改库存接口 */ void cardModifyStock(String cardId, Integer changeValue) throws WxErrorException; - /** + * 
      * 更改Code接口
-     * https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Managing_Coupons_Vouchers_and_Cards.html#6
+     *
* * @param cardId 卡券ID * @param oldCode 需变更的Code码 * @param newCode 变更后的有效Code码 - * @throws WxErrorException the wx error exception + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 更改Code接口 */ void cardCodeUpdate(String cardId, String oldCode, String newCode) throws WxErrorException; /** + * 
      * 设置买单接口
-     * https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Create_a_Coupon_Voucher_or_Card.html#12
+     *
* * @param cardId 卡券ID * @param isOpen 是否开启买单功能，填true/false - * @throws WxErrorException the wx error exception + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 设置买单接口 */ void cardPaycellSet(String cardId, Boolean isOpen) throws WxErrorException; /** + * 
      * 设置自助核销
-     * https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Create_a_Coupon_Voucher_or_Card.html#14
+     *
* * @param cardId 卡券ID * @param isOpen 是否开启自助核销功能 * @param needVerifyCod 用户核销时是否需要输入验证码， 填true/false， 默认为false * @param needRemarkAmount 用户核销时是否需要备注核销金额， 填true/false， 默认为false - * @throws WxErrorException the wx error exception + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 设置自助核销 */ void cardSelfConsumeCellSet(String cardId, Boolean isOpen, Boolean needVerifyCod, Boolean needRemarkAmount) throws WxErrorException; /** + * 
      * 获取用户已领取卡券接口
-     * https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Managing_Coupons_Vouchers_and_Cards.html#1
+     *
* * @param openId 需要查询的用户openid * @param cardId 卡券ID。不填写时默认查询当前appid下的卡券 - * @return user card list - * @throws WxErrorException the wx error exception + * @return 用户卡券列表结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 获取用户已领取卡券接口 */ WxUserCardListResult getUserCardList(String openId, String cardId) throws WxErrorException; - } diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpKefuService.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpKefuService.java index bceb80448..234a7160e 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpKefuService.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpKefuService.java @@ -29,9 +29,9 @@ public interface WxMpKefuService { * 接口url格式：https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN * * - * @param message the message - * @return the boolean - * @throws WxErrorException 异常 + * @param message 客服消息对象，包含消息类型、内容、接收者等信息 + * @return 发送是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常 */ boolean sendKefuMessage(WxMpKefuMessage message) throws WxErrorException; @@ -42,9 +42,9 @@ public interface WxMpKefuService { * 接口url格式：https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN * * - * @param message the message - * @return the response - * @throws WxErrorException 异常 + * @param message 客服消息对象，包含消息类型、内容、接收者等信息 + * @return 微信API响应结果，JSON格式字符串 + * @throws WxErrorException 微信API调用异常 */ String sendKefuMessageWithResponse(WxMpKefuMessage message) throws WxErrorException; @@ -57,8 +57,8 @@ public interface WxMpKefuService { * 接口url格式：https://api.weixin.qq.com/cgi-bin/customservice/getkflist?access_token=ACCESS_TOKEN * * - * @return the wx mp kf list - * @throws WxErrorException 异常 + * @return 客服基本信息列表，包含客服账号、昵称、头像等信息 + * @throws WxErrorException 微信API调用异常 */ WxMpKfList kfList() throws WxErrorException; @@ -69,8 +69,8 @@ public interface WxMpKefuService { * 接口url格式：https://api.weixin.qq.com/cgi-bin/customservice/getonlinekflist?access_token=ACCESS_TOKEN * * - * @return the wx mp kf online list - * @throws WxErrorException 异常 + * @return 在线客服接待信息列表，包含在线客服账号、接待状态等信息 + * @throws WxErrorException 微信API调用异常 */ WxMpKfOnlineList kfOnlineList() throws WxErrorException; @@ -81,9 +81,9 @@ public interface WxMpKefuService { * 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN * * - * @param request the request - * @return the boolean - * @throws WxErrorException 异常 + * @param request 客服账号请求对象，包含客服账号、昵称等信息 + * @return 添加是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常 */ boolean kfAccountAdd(WxMpKfAccountRequest request) throws WxErrorException; @@ -94,22 +94,22 @@ public interface WxMpKefuService { * 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/update?access_token=ACCESS_TOKEN * * - * @param request the request - * @return the boolean - * @throws WxErrorException the wx error exception + * @param request 客服账号请求对象，包含客服账号、昵称等信息 + * @return 更新是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常 */ boolean kfAccountUpdate(WxMpKfAccountRequest request) throws WxErrorException; /** * 
-     * 设置客服信息（即更新客服信息）
+     * 邀请绑定客服账号
      * 详情请见：客服管理
      * 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/inviteworker?access_token=ACCESS_TOKEN
      *
* - * @param request the request - * @return the boolean - * @throws WxErrorException 异常 + * @param request 客服账号请求对象，包含客服账号、邀请者微信号等信息 + * @return 邀请是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常 */ boolean kfAccountInviteWorker(WxMpKfAccountRequest request) throws WxErrorException; @@ -120,10 +120,10 @@ public interface WxMpKefuService { * 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/uploadheadimg?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT * * - * @param kfAccount the kf account - * @param imgFile the img file - * @return the boolean - * @throws WxErrorException 异常 + * @param kfAccount 客服账号，格式为：账号前缀@微信号 + * @param imgFile 头像图片文件，支持JPG、PNG格式，大小不超过2MB + * @return 上传是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常 */ boolean kfAccountUploadHeadImg(String kfAccount, File imgFile) throws WxErrorException; @@ -134,9 +134,9 @@ public interface WxMpKefuService { * 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/del?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT * * - * @param kfAccount the kf account - * @return the boolean - * @throws WxErrorException 异常 + * @param kfAccount 客服账号，格式为：账号前缀@微信号 + * @return 删除是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常 */ boolean kfAccountDel(String kfAccount) throws WxErrorException; @@ -150,10 +150,10 @@ public interface WxMpKefuService { * 接口url格式： https://api.weixin.qq.com/customservice/kfsession/create?access_token=ACCESS_TOKEN * * - * @param openid the openid - * @param kfAccount the kf account - * @return the boolean - * @throws WxErrorException 异常 + * @param openid 用户的openid，标识具体的用户 + * @param kfAccount 客服账号，格式为：账号前缀@微信号 + * @return 创建是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常 */ boolean kfSessionCreate(String openid, String kfAccount) throws WxErrorException; @@ -165,10 +165,10 @@ public interface WxMpKefuService { * 接口url格式： https://api.weixin.qq.com/customservice/kfsession/close?access_token=ACCESS_TOKEN * * - * @param openid the openid - * @param kfAccount the kf account - * @return the boolean - * @throws WxErrorException 异常 + * @param openid 用户的openid，标识具体的用户 + * @param kfAccount 客服账号，格式为：账号前缀@微信号 + * @return 关闭是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常 */ boolean kfSessionClose(String openid, String kfAccount) throws WxErrorException; @@ -180,9 +180,9 @@ public interface WxMpKefuService { * 接口url格式： https://api.weixin.qq.com/customservice/kfsession/getsession?access_token=ACCESS_TOKEN&openid=OPENID * * - * @param openid the openid - * @return the wx mp kf session get result - * @throws WxErrorException 异常 + * @param openid 用户的openid，标识具体的用户 + * @return 客户会话状态信息，包含客服账号、会话状态等 + * @throws WxErrorException 微信API调用异常 */ WxMpKfSessionGetResult kfSessionGet(String openid) throws WxErrorException; @@ -194,9 +194,9 @@ public interface WxMpKefuService { * 接口url格式： https://api.weixin.qq.com/customservice/kfsession/getsessionlist?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT * * - * @param kfAccount the kf account - * @return the wx mp kf session list - * @throws WxErrorException 异常 + * @param kfAccount 客服账号，格式为：账号前缀@微信号 + * @return 客服会话列表，包含正在接待的会话信息 + * @throws WxErrorException 微信API调用异常 */ WxMpKfSessionList kfSessionList(String kfAccount) throws WxErrorException; @@ -208,8 +208,8 @@ public interface WxMpKefuService { * 接口url格式： https://api.weixin.qq.com/customservice/kfsession/getwaitcase?access_token=ACCESS_TOKEN * * - * @return the wx mp kf session wait case list - * @throws WxErrorException 异常 + * @return 未接入会话列表，包含等待接入的会话信息 + * @throws WxErrorException 微信API调用异常 */ WxMpKfSessionWaitCaseList kfSessionGetWaitCase() throws WxErrorException; @@ -223,12 +223,12 @@ public interface WxMpKefuService { * 接口url格式： https://api.weixin.qq.com/customservice/msgrecord/getmsglist?access_token=ACCESS_TOKEN * * - * @param startTime 起始时间 - * @param endTime 结束时间 - * @param msgId 消息id顺序从小到大，从1开始 - * @param number 每次获取条数，最多10000条 - * @return 聊天记录对象 wx mp kf msg list - * @throws WxErrorException 异常 + * @param startTime 起始时间，用于筛选聊天记录的时间范围 + * @param endTime 结束时间，用于筛选聊天记录的时间范围 + * @param msgId 消息id顺序从小到大，从1开始，用于分页获取 + * @param number 每次获取条数，最多10000条，用于分页控制 + * @return 聊天记录对象，包含客服和用户的聊天消息列表 + * @throws WxErrorException 微信API调用异常 */ WxMpKfMsgList kfMsgList(Date startTime, Date endTime, Long msgId, Integer number) throws WxErrorException; @@ -240,17 +240,17 @@ public interface WxMpKefuService { * 接口url格式： https://api.weixin.qq.com/customservice/msgrecord/getmsglist?access_token=ACCESS_TOKEN * * - * @param startTime 起始时间 - * @param endTime 结束时间 - * @return 聊天记录对象 wx mp kf msg list - * @throws WxErrorException 异常 + * @param startTime 起始时间，用于筛选聊天记录的时间范围 + * @param endTime 结束时间，用于筛选聊天记录的时间范围 + * @return 聊天记录对象，包含客服和用户的聊天消息列表 + * @throws WxErrorException 微信API调用异常 */ WxMpKfMsgList kfMsgList(Date startTime, Date endTime) throws WxErrorException; /** * 
      * 客服输入状态
-     * 开发者可通过调用“客服输入状态”接口，返回客服当前输入状态给用户。
+     * 开发者可通过调用"客服输入状态"接口，返回客服当前输入状态给用户。
      * 此接口需要客服消息接口权限。
      * 如果不满足发送客服消息的触发条件，则无法下发输入状态。
      * 下发输入状态，需要客服之前30秒内跟用户有过消息交互。
@@ -261,10 +261,10 @@ public interface WxMpKefuService {
      * 接口url格式：https://api.weixin.qq.com/cgi-bin/message/custom/typing?access_token=ACCESS_TOKEN
      *
* - * @param openid 用户id - * @param command "Typing"：对用户下发“正在输入"状态 "CancelTyping"：取消对用户的”正在输入"状态 - * @return the boolean - * @throws WxErrorException 异常 + * @param openid 用户的openid，标识具体的用户 + * @param command 输入状态命令，可选值："Typing"：对用户下发"正在输入"状态；"CancelTyping"：取消对用户的"正在输入"状态 + * @return 发送是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常 */ boolean sendKfTypingState(String openid, String command) throws WxErrorException; } diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMassMessageService.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMassMessageService.java index 823c2c634..5ad3098c2 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMassMessageService.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMassMessageService.java @@ -8,138 +8,234 @@ import me.chanjar.weixin.mp.bean.result.WxMpMassSpeedGetResult; import me.chanjar.weixin.mp.bean.result.WxMpMassUploadResult; /** - * 
- * 群发消息服务类.
+ * 群发消息服务类
+ * 

+ * 提供微信公众号群发消息的功能，包括图文消息、视频消息的群发，
+ * 支持按分组群发、按openid列表群发、消息预览、群发状态查询等功能。
+ * 

+ * 

+ * 详情请见：群发消息开发文档
+ * 

  * Created by Binary Wang on 2017-8-16.
- *
* * @author Binary Wang */ public interface WxMpMassMessageService { /** * 
-     * 上传群发用的图文消息，上传后才能群发图文消息.
-     *
-     * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549&token=&lang=zh_CN
+     * 上传群发用的图文消息，上传后才能群发图文消息
      *
* - * @param news the news - * @return the wx mp mass upload result - * @throws WxErrorException the wx error exception - * @see #massGroupMessageSend(WxMpMassTagMessage) #massGroupMessageSend(WxMpMassTagMessage) - * @see #massOpenIdsMessageSend(WxMpMassOpenIdsMessage) #massOpenIdsMessageSend(WxMpMassOpenIdsMessage) + * @param news 图文消息对象 + * @return 上传结果对象，包含media_id等信息 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see #massGroupMessageSend(WxMpMassTagMessage) + * @see #massOpenIdsMessageSend(WxMpMassOpenIdsMessage) + * @see 上传群发用的图文消息 */ WxMpMassUploadResult massNewsUpload(WxMpMassNews news) throws WxErrorException; /** * 
-     * 上传群发用的视频，上传后才能群发视频消息.
-     * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549&token=&lang=zh_CN
+     * 上传群发用的视频，上传后才能群发视频消息
      *
* - * @param video the video - * @return the wx mp mass upload result - * @throws WxErrorException the wx error exception - * @see #massGroupMessageSend(WxMpMassTagMessage) #massGroupMessageSend(WxMpMassTagMessage) - * @see #massOpenIdsMessageSend(WxMpMassOpenIdsMessage) #massOpenIdsMessageSend(WxMpMassOpenIdsMessage) + * @param video 视频消息对象 + * @return 上传结果对象，包含media_id等信息 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see #massGroupMessageSend(WxMpMassTagMessage) + * @see #massOpenIdsMessageSend(WxMpMassOpenIdsMessage) + * @see 上传群发用的视频 */ WxMpMassUploadResult massVideoUpload(WxMpMassVideo video) throws WxErrorException; /** * 
-     * 分组群发消息.
+     * 分组群发消息
      * 如果发送图文消息，必须先使用 {@link #massNewsUpload(WxMpMassNews)} 获得media_id，然后再发送
      * 如果发送视频消息，必须先使用 {@link #massVideoUpload(WxMpMassVideo)} 获得media_id，然后再发送
-     * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549&token=&lang=zh_CN
      *
* - * @param message the message - * @return the wx mp mass send result - * @throws WxErrorException the wx error exception + * @param message 分组群发消息对象 + * @return 群发结果对象，包含msg_id等信息 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 分组群发消息 */ WxMpMassSendResult massGroupMessageSend(WxMpMassTagMessage message) throws WxErrorException; /** * 
-     * 按openId列表群发消息.
+     * 按openId列表群发消息
      * 如果发送图文消息，必须先使用 {@link #massNewsUpload(WxMpMassNews)} 获得media_id，然后再发送
      * 如果发送视频消息，必须先使用 {@link #massVideoUpload(WxMpMassVideo)} 获得media_id，然后再发送
-     * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549&token=&lang=zh_CN
      *
* - * @param message the message - * @return the wx mp mass send result - * @throws WxErrorException the wx error exception + * @param message 按openid列表群发消息对象 + * @return 群发结果对象，包含msg_id等信息 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 按openId列表群发消息 */ WxMpMassSendResult massOpenIdsMessageSend(WxMpMassOpenIdsMessage message) throws WxErrorException; /** * 
-     * 群发消息预览接口.
+     * 群发消息预览接口
      * 开发者可通过该接口发送消息给指定用户，在手机端查看消息的样式和排版。为了满足第三方平台开发者的需求，
      * 在保留对openID预览能力的同时，增加了对指定微信号发送预览的能力，但该能力每日调用次数有限制（100次），请勿滥用。
-     * 接口调用请求说明
-     *  http请求方式: POST
-     *  https://api.weixin.qq.com/cgi-bin/message/mass/preview?access_token=ACCESS_TOKEN
-     * 详情请见：http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549&token=&lang=zh_CN
      *
* - * @param wxMpMassPreviewMessage the wx mp mass preview message - * @return wxMpMassSendResult wx mp mass send result - * @throws WxErrorException the wx error exception + * @param wxMpMassPreviewMessage 预览消息对象 + * @return 群发结果对象，包含msg_id等信息 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 群发消息预览接口 */ WxMpMassSendResult massMessagePreview(WxMpMassPreviewMessage wxMpMassPreviewMessage) throws WxErrorException; /** * 
-     * 删除群发.
+     * 删除群发
      * 群发之后，随时可以通过该接口删除群发。
      * 请注意：
      * 1、只有已经发送成功的消息才能删除
      * 2、删除消息是将消息的图文详情页失效，已经收到的用户，还是能在其本地看到消息卡片。
      * 3、删除群发消息只能删除图文消息和视频消息，其他类型的消息一经发送，无法删除。
      * 4、如果多次群发发送的是一个图文消息，那么删除其中一次群发，就会删除掉这个图文消息也，导致所有群发都失效
-     * 接口调用请求说明：
-     *  http请求方式: POST
-     *  https://api.weixin.qq.com/cgi-bin/message/mass/delete?access_token=ACCESS_TOKEN
-     * 详情请见：https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1481187827_i0l21
      *
* * @param msgId 发送出去的消息ID * @param articleIndex 要删除的文章在图文消息中的位置，第一篇编号为1，该字段不填或填0会删除全部文章 - * @throws WxErrorException the wx error exception + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 删除群发 */ void delete(Long msgId, Integer articleIndex) throws WxErrorException; - /** + * 
      * 获取群发速度
-     * https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Batch_Sends_and_Originality_Checks.html#9
+     *
* - * @return the wx mp mass speed get result - * @throws WxErrorException the wx error exception + * @return 群发速度获取结果对象 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 获取群发速度 */ WxMpMassSpeedGetResult messageMassSpeedGet() throws WxErrorException; - /** + * 
      * 设置群发速度
-     * https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Batch_Sends_and_Originality_Checks.html#9
+     *
* - * @param speed 群发速度的级别，是一个0到4的整数，数字越大表示群发速度越慢。 speed realspeed 0 80w/分钟 1 60w/分钟 2 45w/分钟 3 30w/分钟 4 10w/分钟 - * @throws WxErrorException the wx error exception + * @param speed 群发速度的级别，是一个0到4的整数，数字越大表示群发速度越慢。 + * speed realspeed + * 0 80w/分钟 + * 1 60w/分钟 + * 2 45w/分钟 + * 3 30w/分钟 + * 4 10w/分钟 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 设置群发速度 */ void messageMassSpeedSet(Integer speed) throws WxErrorException; - /** + * 
      * 查询群发消息发送状态【订阅号与服务号认证后均可用】
-     * https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Batch_Sends_and_Originality_Checks.html#%E6%9F%A5%E8%AF%A2%E7%BE%A4%E5%8F%91%E6%B6%88%E6%81%AF%E5%8F%91%E9%80%81%E7%8A%B6%E6%80%81%E3%80%90%E8%AE%A2%E9%98%85%E5%8F%B7%E4%B8%8E%E6%9C%8D%E5%8A%A1%E5%8F%B7%E8%AE%A4%E8%AF%81%E5%90%8E%E5%9D%87%E5%8F%AF%E7%94%A8%E3%80%91
+     *
* * @param msgId 群发消息后返回的消息id - * @return 消息发送后的状态 ，SEND_SUCCESS表示发送成功，SENDING表示发送中，SEND_FAIL表示发送失败，DELETE表示已删除 - * @throws WxErrorException the wx error exception + * @return 消息发送后的状态，SEND_SUCCESS表示发送成功，SENDING表示发送中，SEND_FAIL表示发送失败，DELETE表示已删除 + * @throws WxErrorException 微信API调用异常，可能包括： + * + * @see 查询群发消息发送状态 */ WxMpMassGetResult messageMassGet(Long msgId) throws WxErrorException; - } diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMaterialService.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMaterialService.java index ef396b703..3c7a525b0 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMaterialService.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMaterialService.java @@ -17,7 +17,6 @@ import me.chanjar.weixin.mp.bean.material.WxMpMaterialVideoInfoResult; /** * 
- * Created by Binary Wang on 2016/7/21.
  * 素材管理的相关接口，包括媒体管理的接口，
  * 即以https://api.weixin.qq.com/cgi-bin/material
  * 和 https://api.weixin.qq.com/cgi-bin/media开头的接口
@@ -36,7 +35,7 @@ public interface WxMpMaterialService {
      *  2、media_id是可复用的。
      *  3、素材的格式大小等要求与公众平台官网一致。具体是，图片大小不超过2M，支持png/jpeg/jpg/gif格式，语音大小不超过5M，长度不超过60秒，支持mp3/amr格式
      *  4、需使用https调用本接口。
-     *  本接口即为原“上传多媒体文件”接口。
+     *  本接口即为原"上传多媒体文件"接口。
      *  注意事项：
      *    上传的临时多媒体文件有格式和大小限制，如下：
      *    图片（image）: 2M，支持PNG\JPEG\JPG\GIF格式
@@ -49,17 +48,17 @@ public interface WxMpMaterialService {
      *
* * @param mediaType 媒体类型, 请看{@link me.chanjar.weixin.common.api.WxConsts} - * @param file 文件对象 - * @return the wx media upload result - * @throws WxErrorException the wx error exception - * @see #mediaUpload(String, String, InputStream) #mediaUpload(String, String, InputStream)#mediaUpload(String, String, InputStream) + * @param file 文件对象，需要上传的临时素材文件 + * @return 上传结果，包含media_id等信息 + * @throws WxErrorException 微信API调用异常 + * @see #mediaUpload(String, String, InputStream) 使用输入流上传临时素材 */ WxMediaUploadResult mediaUpload(String mediaType, File file) throws WxErrorException; /** * 
      * 新增临时素材
-     * 本接口即为原“上传多媒体文件”接口。
+     * 本接口即为原"上传多媒体文件"接口。
      *
      * 详情请见: 新增临时素材
      * 接口url格式：https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE
@@ -67,10 +66,10 @@ public interface WxMpMaterialService {
      *
      * @param mediaType   媒体类型, 请看{@link me.chanjar.weixin.common.api.WxConsts}
      * @param fileType    文件类型，请看{@link me.chanjar.weixin.common.api.WxConsts}
-     * @param inputStream 输入流
-     * @return the wx media upload result
-     * @throws WxErrorException the wx error exception
-     * @see #mediaUpload(java.lang.String, java.io.File) #mediaUpload(java.lang.String, java.io.File)#mediaUpload(java.lang.String, java.io.File)
+     * @param inputStream 输入流，包含要上传的临时素材内容
+     * @return 上传结果，包含media_id等信息
+     * @throws WxErrorException 微信API调用异常
+     * @see #mediaUpload(String, File) 使用文件对象上传临时素材
      */
     WxMediaUploadResult mediaUpload(String mediaType, String fileType, InputStream inputStream) throws WxErrorException;
 
@@ -78,15 +77,15 @@ public interface WxMpMaterialService {
      * 
      * 获取临时素材
      * 公众号可以使用本接口获取临时素材（即下载临时的多媒体文件）。请注意，视频文件不支持https下载，调用该接口需http协议。
-     * 本接口即为原“下载多媒体文件”接口。
+     * 本接口即为原"下载多媒体文件"接口。
      * 根据微信文档，视频文件下载不了，会返回null
      * 详情请见: 获取临时素材
      * 接口url格式：https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID
      * 

      *
-     * @param mediaId 媒体文件Id
-     * @return 保存到本地的临时文件 file
-     * @throws WxErrorException the wx error exception
+     * @param mediaId 媒体文件Id，通过上传临时素材接口获取
+     * @return 保存到本地的临时文件，如果下载失败则返回null
+     * @throws WxErrorException 微信API调用异常
      */
     File mediaDownload(String mediaId) throws WxErrorException;
 
@@ -100,9 +99,9 @@ public interface WxMpMaterialService {
      * 接口url格式：https://api.weixin.qq.com/cgi-bin/media/get/jssdk?access_token=ACCESS_TOKEN&media_id=MEDIA_ID
      *
* - * @param mediaId 媒体文件Id - * @return 保存到本地的临时文件 file - * @throws WxErrorException the wx error exception + * @param mediaId 媒体文件Id，通过JSSDK上传语音素材获取 + * @return 保存到本地的临时文件，高清语音素材 + * @throws WxErrorException 微信API调用异常 */ File jssdkMediaDownload(String mediaId) throws WxErrorException; @@ -114,9 +113,9 @@ public interface WxMpMaterialService { * 接口url格式：https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN * * - * @param file 上传的文件对象 - * @return WxMediaImgUploadResult 返回图片url - * @throws WxErrorException the wx error exception + * @param file 上传的文件对象，图片素材，支持jpg/png格式，大小不超过1MB + * @return 图片上传结果，包含图片URL，可用于图文消息中 + * @throws WxErrorException 微信API调用异常 */ WxMediaImgUploadResult mediaImgUpload(File file) throws WxErrorException; @@ -141,8 +140,8 @@ public interface WxMpMaterialService { * * @param mediaType 媒体类型, 请看{@link me.chanjar.weixin.common.api.WxConsts} * @param material 上传的素材, 请看{@link WxMpMaterial} - * @return the wx mp material upload result - * @throws WxErrorException the wx error exception + * @return 上传结果，包含media_id等信息 + * @throws WxErrorException 微信API调用异常 */ WxMpMaterialUploadResult materialFileUpload(String mediaType, WxMpMaterial material) throws WxErrorException; @@ -155,8 +154,8 @@ public interface WxMpMaterialService { * * * @param mediaId 永久素材的id - * @return the input stream - * @throws WxErrorException the wx error exception + * @return 素材内容的输入流，可用于读取图片或语音文件 + * @throws WxErrorException 微信API调用异常 */ InputStream materialImageOrVoiceDownload(String mediaId) throws WxErrorException; @@ -169,8 +168,8 @@ public interface WxMpMaterialService { * * * @param mediaId 永久素材的id - * @return the wx mp material video info result - * @throws WxErrorException the wx error exception + * @return 视频素材信息，包含标题、描述和下载地址 + * @throws WxErrorException 微信API调用异常 */ WxMpMaterialVideoInfoResult materialVideoInfo(String mediaId) throws WxErrorException; @@ -183,8 +182,8 @@ public interface WxMpMaterialService { * * * @param mediaId 永久素材的id - * @return the wx mp material news - * @throws WxErrorException the wx error exception + * @return 图文素材信息，包含文章列表和标题等 + * @throws WxErrorException 微信API调用异常 */ WxMpMaterialNews materialNewsInfo(String mediaId) throws WxErrorException; @@ -201,8 +200,8 @@ public interface WxMpMaterialService { * * * @param mediaId 永久素材的id - * @return the boolean - * @throws WxErrorException the wx error exception + * @return 删除是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常 */ boolean materialDelete(String mediaId) throws WxErrorException; @@ -219,8 +218,8 @@ public interface WxMpMaterialService { * 接口url格式：https://api.weixin.qq.com/cgi-bin/material/get_materialcount?access_token=ACCESS_TOKEN * * - * @return the wx mp material count result - * @throws WxErrorException the wx error exception + * @return 素材统计结果，包含各类素材的数量 + * @throws WxErrorException 微信API调用异常 */ WxMpMaterialCountResult materialCount() throws WxErrorException; @@ -232,10 +231,10 @@ public interface WxMpMaterialService { * 接口url格式：https://api.weixin.qq.com/cgi-bin/material/batchget_material?access_token=ACCESS_TOKEN * * - * @param offset 从全部素材的该偏移位置开始返回，0表示从第一个素材 返回 + * @param offset 从全部素材的该偏移位置开始返回，0表示从第一个素材返回 * @param count 返回素材的数量，取值在1到20之间 - * @return the wx mp material news batch get result - * @throws WxErrorException the wx error exception + * @return 图文素材列表，包含文章列表和标题等信息 + * @throws WxErrorException 微信API调用异常 */ WxMpMaterialNewsBatchGetResult materialNewsBatchGet(int offset, int count) throws WxErrorException; @@ -248,10 +247,10 @@ public interface WxMpMaterialService { * * * @param type 媒体类型, 请看{@link me.chanjar.weixin.common.api.WxConsts} - * @param offset 从全部素材的该偏移位置开始返回，0表示从第一个素材 返回 + * @param offset 从全部素材的该偏移位置开始返回，0表示从第一个素材返回 * @param count 返回素材的数量，取值在1到20之间 - * @return the wx mp material file batch get result - * @throws WxErrorException the wx error exception + * @return 其他媒体素材列表，包含图片、语音、视频等素材信息 + * @throws WxErrorException 微信API调用异常 */ WxMpMaterialFileBatchGetResult materialFileBatchGet(String type, int offset, int count) throws WxErrorException; diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMenuService.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMenuService.java index 3e7889300..ad1813ee8 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMenuService.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMenuService.java @@ -19,9 +19,9 @@ public interface WxMpMenuService { * 详情请见：https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1455782296&token=&lang=zh_CN * * - * @param menu the menu - * @return 如果是个性化菜单 ，则返回menuid，否则返回null - * @throws WxErrorException the wx error exception + * @param menu 菜单对象，包含菜单结构和配置信息 + * @return 如果是个性化菜单，则返回menuid，否则返回null + * @throws WxErrorException 微信API调用异常 */ String menuCreate(WxMenu menu) throws WxErrorException; @@ -33,9 +33,9 @@ public interface WxMpMenuService { * 详情请见：https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1455782296&token=&lang=zh_CN * * - * @param json the json - * @return 如果是个性化菜单 ，则返回menuid，否则返回null - * @throws WxErrorException the wx error exception + * @param json 菜单配置的JSON字符串，包含菜单结构和配置信息 + * @return 如果是个性化菜单，则返回menuid，否则返回null + * @throws WxErrorException 微信API调用异常 */ String menuCreate(String json) throws WxErrorException; @@ -45,7 +45,7 @@ public interface WxMpMenuService { * 详情请见: https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141015&token=&lang=zh_CN * * - * @throws WxErrorException the wx error exception + * @throws WxErrorException 微信API调用异常 */ void menuDelete() throws WxErrorException; @@ -55,8 +55,8 @@ public interface WxMpMenuService { * 详情请见: https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1455782296&token=&lang=zh_CN * * - * @param menuId 个性化菜单的menuid - * @throws WxErrorException the wx error exception + * @param menuId 个性化菜单的menuid，通过创建个性化菜单时返回 + * @throws WxErrorException 微信API调用异常 */ void menuDelete(String menuId) throws WxErrorException; @@ -66,8 +66,8 @@ public interface WxMpMenuService { * 详情请见： https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141014&token=&lang=zh_CN * * - * @return the wx mp menu - * @throws WxErrorException the wx error exception + * @return 当前公众号的自定义菜单配置 + * @throws WxErrorException 微信API调用异常 */ WxMpMenu menuGet() throws WxErrorException; @@ -77,9 +77,9 @@ public interface WxMpMenuService { * 详情请见: http://mp.weixin.qq.com/wiki/0/c48ccd12b69ae023159b4bfaa7c39c20.html * * - * @param userid 可以是粉丝的OpenID，也可以是粉丝的微信号。 - * @return the wx menu - * @throws WxErrorException the wx error exception + * @param userid 可以是粉丝的OpenID，也可以是粉丝的微信号 + * @return 匹配到的菜单配置 + * @throws WxErrorException 微信API调用异常 */ WxMenu menuTryMatch(String userid) throws WxErrorException; @@ -98,8 +98,8 @@ public interface WxMpMenuService { * https://api.weixin.qq.com/cgi-bin/get_current_selfmenu_info?access_token=ACCESS_TOKEN * * - * @return the self menu info - * @throws WxErrorException the wx error exception + * @return 自定义菜单配置信息，包含菜单结构和配置详情 + * @throws WxErrorException 微信API调用异常 */ WxMpGetSelfMenuInfoResult getSelfMenuInfo() throws WxErrorException; } diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpQrcodeService.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpQrcodeService.java index ed8c5e6a7..df923512c 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpQrcodeService.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpQrcodeService.java @@ -22,8 +22,8 @@ public interface WxMpQrcodeService { * * @param sceneId 场景值ID，临时二维码时为32位非0整型 * @param expireSeconds 该二维码有效时间，以秒为单位。 最大不超过2592000（即30天），此字段如果不填，则默认有效期为30秒。 - * @return the wx mp qr code ticket - * @throws WxErrorException the wx error exception + * @return 二维码ticket，可用于获取二维码图片 + * @throws WxErrorException 微信API调用异常 */ WxMpQrCodeTicket qrCodeCreateTmpTicket(int sceneId, Integer expireSeconds) throws WxErrorException; @@ -36,8 +36,8 @@ public interface WxMpQrcodeService { * * @param sceneStr 场景值ID（字符串形式的ID），字符串类型，长度限制为1到64 * @param expireSeconds 该二维码有效时间，以秒为单位。 最大不超过2592000（即30天），此字段如果不填，则默认有效期为30秒。 - * @return the wx mp qr code ticket - * @throws WxErrorException the wx error exception + * @return 二维码ticket，可用于获取二维码图片 + * @throws WxErrorException 微信API调用异常 */ WxMpQrCodeTicket qrCodeCreateTmpTicket(String sceneStr, Integer expireSeconds) throws WxErrorException; @@ -48,8 +48,8 @@ public interface WxMpQrcodeService { * * * @param sceneId 场景值ID，最大值为100000（目前参数只支持1--100000） - * @return the wx mp qr code ticket - * @throws WxErrorException the wx error exception + * @return 二维码ticket，可用于获取二维码图片 + * @throws WxErrorException 微信API调用异常 */ WxMpQrCodeTicket qrCodeCreateLastTicket(int sceneId) throws WxErrorException; @@ -60,8 +60,8 @@ public interface WxMpQrcodeService { * * * @param sceneStr 参数。字符串类型长度现在为1到64 - * @return the wx mp qr code ticket - * @throws WxErrorException the wx error exception + * @return 二维码ticket，可用于获取二维码图片 + * @throws WxErrorException 微信API调用异常 */ WxMpQrCodeTicket qrCodeCreateLastTicket(String sceneStr) throws WxErrorException; @@ -71,9 +71,9 @@ public interface WxMpQrcodeService { * 详情请见: 生成带参数的二维码 * * - * @param ticket 二维码ticket - * @return the file - * @throws WxErrorException the wx error exception + * @param ticket 二维码ticket，通过创建二维码接口获取 + * @return 二维码图片文件，jpg格式 + * @throws WxErrorException 微信API调用异常 */ File qrCodePicture(WxMpQrCodeTicket ticket) throws WxErrorException; @@ -85,8 +85,9 @@ public interface WxMpQrcodeService { * * @param ticket 二维码ticket * @param needShortUrl 是否需要压缩的二维码地址 - * @return the string - * @throws WxErrorException the wx error exception + * @return 二维码图片的URL地址 + * @throws WxErrorException 微信API调用异常 + * @deprecated 请使用 {@link #qrCodePictureUrl(String)} 方法 */ @Deprecated String qrCodePictureUrl(String ticket, boolean needShortUrl) throws WxErrorException; @@ -97,9 +98,9 @@ public interface WxMpQrcodeService { * 详情请见: 生成带参数的二维码 * * - * @param ticket 二维码ticket - * @return the string - * @throws WxErrorException the wx error exception + * @param ticket 二维码ticket，通过创建二维码接口获取 + * @return 二维码图片的URL地址 + * @throws WxErrorException 微信API调用异常 */ String qrCodePictureUrl(String ticket) throws WxErrorException; diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpService.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpService.java index 47a24b793..468dced13 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpService.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpService.java @@ -37,7 +37,7 @@ public interface WxMpService extends WxService { * @param longData 需要转换的长信息，不超过4KB * @param expireSeconds 短key有效期(单位秒)，最大值为2592000（即30天），默认为2592000(30天) * @return shortKey 短key，15字节，base62编码(0-9/a-z/A-Z) - * @throws WxErrorException . + * @throws WxErrorException 微信API调用异常 */ String genShorten(String longData, Integer expireSeconds) throws WxErrorException; @@ -47,9 +47,9 @@ public interface WxMpService extends WxService { * 详情请见: https://developers.weixin.qq.com/doc/offiaccount/Account_Management/KEY_Shortener.html * * - * @param shortKey 短key - * @return WxMpShortKeyResult 解析结果 - * @throws WxErrorException . + * @param shortKey 短key，15字节，base62编码(0-9/a-z/A-Z) + * @return WxMpShortKeyResult 解析结果，包含原始长信息 + * @throws WxErrorException 微信API调用异常 */ WxMpShortKeyResult fetchShorten(String shortKey) throws WxErrorException; @@ -59,19 +59,19 @@ public interface WxMpService extends WxService { * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421135319&token=&lang=zh_CN * * - * @param timestamp 时间戳 - * @param nonce 随机串 - * @param signature 签名 - * @return 是否验证通过 boolean + * @param timestamp 时间戳，字符串格式 + * @param nonce 随机串，字符串格式 + * @param signature 签名，字符串格式 + * @return 是否验证通过，true表示验证通过，false表示验证失败 */ boolean checkSignature(String timestamp, String nonce, String signature); /** * 获取access_token, 不强制刷新access_token. * - * @return token access token - * @throws WxErrorException . - * @see #getAccessToken(boolean) #getAccessToken(boolean)#getAccessToken(boolean)#getAccessToken(boolean) + * @return token access token，字符串格式 + * @throws WxErrorException 微信API调用异常 + * @see #getAccessToken(boolean) 获取access_token，可选择是否强制刷新 */ String getAccessToken() throws WxErrorException; @@ -87,21 +87,21 @@ public interface WxMpService extends WxService { * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140183&token=&lang=zh_CN * * - * @param forceRefresh 是否强制刷新 - * @return token access token - * @throws WxErrorException . + * @param forceRefresh 是否强制刷新，true表示强制刷新，false表示使用缓存 + * @return token access token，字符串格式 + * @throws WxErrorException 微信API调用异常 */ String getAccessToken(boolean forceRefresh) throws WxErrorException; /** * 获得ticket,不强制刷新ticket. * - * @param type ticket 类型 - * @return ticket ticket - * @throws WxErrorException . - * @see #getTicket(TicketType, boolean) #getTicket(TicketType, boolean)#getTicket(TicketType, boolean)#getTicket(TicketType, boolean) + * @param ticketType ticket 类型，通过TicketType枚举指定 + * @return ticket ticket，字符串格式 + * @throws WxErrorException 微信API调用异常 + * @see #getTicket(TicketType, boolean) 获得ticket，可选择是否强制刷新 */ - String getTicket(TicketType type) throws WxErrorException; + String getTicket(TicketType ticketType) throws WxErrorException; /** * 
@@ -109,19 +109,19 @@ public interface WxMpService extends WxService {
    * 获得时会检查 Token是否过期，如果过期了，那么就刷新一下，否则就什么都不干
    *
* - * @param type ticket类型 - * @param forceRefresh 强制刷新 - * @return ticket ticket - * @throws WxErrorException . + * @param ticketType ticket类型，通过TicketType枚举指定 + * @param forceRefresh 强制刷新，true表示强制刷新，false表示使用缓存 + * @return ticket ticket，字符串格式 + * @throws WxErrorException 微信API调用异常 */ - String getTicket(TicketType type, boolean forceRefresh) throws WxErrorException; + String getTicket(TicketType ticketType, boolean forceRefresh) throws WxErrorException; /** * 获得jsapi_ticket,不强制刷新jsapi_ticket. * - * @return jsapi ticket - * @throws WxErrorException . - * @see #getJsapiTicket(boolean) #getJsapiTicket(boolean)#getJsapiTicket(boolean)#getJsapiTicket(boolean) + * @return jsapi ticket，字符串格式 + * @throws WxErrorException 微信API调用异常 + * @see #getJsapiTicket(boolean) 获得jsapi_ticket，可选择是否强制刷新 */ String getJsapiTicket() throws WxErrorException; @@ -133,9 +133,9 @@ public interface WxMpService extends WxService { * 详情请见：http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141115&token=&lang=zh_CN * * - * @param forceRefresh 强制刷新 - * @return jsapi ticket - * @throws WxErrorException . + * @param forceRefresh 强制刷新，true表示强制刷新，false表示使用缓存 + * @return jsapi ticket，字符串格式 + * @throws WxErrorException 微信API调用异常 */ String getJsapiTicket(boolean forceRefresh) throws WxErrorException; @@ -146,9 +146,9 @@ public interface WxMpService extends WxService { * 详情请见：http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141115&token=&lang=zh_CN * * - * @param url 地址 - * @return 生成的签名对象 wx jsapi signature - * @throws WxErrorException . + * @param url 当前网页的URL，不包括#及其后面部分 + * @return 生成的签名对象，包含签名、时间戳、随机串等信息 + * @throws WxErrorException 微信API调用异常 */ WxJsapiSignature createJsapiSignature(String url) throws WxErrorException; @@ -158,9 +158,10 @@ public interface WxMpService extends WxService { * 详情请见: http://mp.weixin.qq.com/wiki/index.php?title=长链接转短链接接口 * * - * @param longUrl 长url - * @return 生成的短地址 string - * @throws WxErrorException . + * @param longUrl 长url，需要转换的原始URL + * @return 生成的短地址，字符串格式 + * @throws WxErrorException 微信API调用异常 + * @deprecated 请使用 {@link #genShorten(String, Integer)} 方法 */ @Deprecated String shortUrl(String longUrl) throws WxErrorException; @@ -171,9 +172,9 @@ public interface WxMpService extends WxService { * 详情请见：http://mp.weixin.qq.com/wiki/index.php?title=语义理解 * * - * @param semanticQuery 查询条件 - * @return 查询结果 wx mp semantic query result - * @throws WxErrorException . + * @param semanticQuery 查询条件，包含查询内容、类型等信息 + * @return 查询结果，包含语义理解的结果和建议回复 + * @throws WxErrorException 微信API调用异常 */ WxMpSemanticQueryResult semanticQuery(WxMpSemanticQuery semanticQuery) throws WxErrorException; @@ -187,7 +188,7 @@ public interface WxMpService extends WxService { * @param redirectUri 用户授权完成后的重定向链接，无需urlencode, 方法内会进行encode * @param scope 应用授权作用域，拥有多个作用域用逗号（,）分隔，网页应用目前仅填写snsapi_login即可 * @param state 非必填，用于保持请求和回调的状态，授权请求后原样带回给第三方。该参数可用于防止csrf攻击（跨站请求伪造攻击），建议第三方带上该参数，可设置为简单的随机数加session进行校验 - * @return url string + * @return url 构造好的授权登录URL，字符串格式 */ String buildQrConnectUrl(String redirectUri, String scope, String state); @@ -197,8 +198,8 @@ public interface WxMpService extends WxService { * http://mp.weixin.qq.com/wiki/0/2ad4b6bfd29f30f71d39616c2a0fcedc.html * * - * @return 微信服务器ip地址数组 string [ ] - * @throws WxErrorException . + * @return 微信服务器ip地址数组，包含所有微信服务器IP地址 + * @throws WxErrorException 微信API调用异常 */ String[] getCallbackIP() throws WxErrorException; @@ -209,10 +210,10 @@ public interface WxMpService extends WxService { * 为了帮助开发者排查回调连接失败的问题，提供这个网络检测的API。它可以对开发者URL做域名解析，然后对所有IP进行一次ping操作，得到丢包率和耗时。 * * - * @param action 执行的检测动作 - * @param operator 指定平台从某个运营商进行检测 - * @return 检测结果 wx net check result - * @throws WxErrorException . + * @param action 执行的检测动作，可选值：all（全部检测）、dns（仅域名解析）、ping（仅网络连通性检测） + * @param operator 指定平台从某个运营商进行检测，可选值：CHINANET（中国电信）、UNICOM（中国联通）、CAP（中国联通）、CUCC（中国联通） + * @return 检测结果，包含丢包率和耗时等信息 + * @throws WxErrorException 微信API调用异常 */ WxNetCheckResult netCheck(String action, String operator) throws WxErrorException; @@ -232,8 +233,8 @@ public interface WxMpService extends WxService { * https://api.weixin.qq.com/cgi-bin/get_current_autoreply_info?access_token=ACCESS_TOKEN * * - * @return 公众号的自动回复规则 current auto reply info - * @throws WxErrorException . + * @return 公众号的自动回复规则，包含关注后自动回复、消息自动回复、关键词自动回复等信息 + * @throws WxErrorException 微信API调用异常 */ WxMpCurrentAutoReplyInfo getCurrentAutoReplyInfo() throws WxErrorException; @@ -245,8 +246,8 @@ public interface WxMpService extends WxService { * * * - * @param appid 公众号的APPID - * @throws WxErrorException the wx error exception + * @param appid 公众号的APPID，需要清零调用的公众号的appid + * @throws WxErrorException 微信API调用异常 */ void clearQuota(String appid) throws WxErrorException; @@ -257,53 +258,53 @@ public interface WxMpService extends WxService { * 可以参考，{@link MediaUploadRequestExecutor}的实现方法 * * - * @param the type parameter - * @param the type parameter - * @param executor 执行器 - * @param url 接口地址 - * @param data 参数数据 - * @return 结果 t - * @throws WxErrorException 异常 + * @param 返回值类型 + * @param 参数类型 + * @param executor 执行器，用于处理请求和响应 + * @param url 接口地址，字符串格式 + * @param data 参数数据，根据API不同可能是不同类型 + * @return 结果，根据API不同可能是不同类型 + * @throws WxErrorException 微信API调用异常 */ T execute(RequestExecutor executor, String url, E data) throws WxErrorException; /** * 当本Service没有实现某个API的时候，可以用这个，针对所有微信API中的GET请求. * - * @param url 请求接口地址 - * @param queryParam 参数 - * @return 接口响应字符串 string - * @throws WxErrorException 异常 + * @param url 请求接口地址，通过WxMpApiUrl枚举指定 + * @param queryParam 参数，字符串格式，通常是URL查询参数 + * @return 接口响应字符串，JSON格式 + * @throws WxErrorException 微信API调用异常 */ String get(WxMpApiUrl url, String queryParam) throws WxErrorException; /** * 当本Service没有实现某个API的时候，可以用这个，针对所有微信API中的POST请求. * - * @param url 请求接口地址 - * @param postData 请求参数json值 - * @return 接口响应字符串 string - * @throws WxErrorException 异常 + * @param url 请求接口地址，通过WxMpApiUrl枚举指定 + * @param postData 请求参数json值，字符串格式 + * @return 接口响应字符串，JSON格式 + * @throws WxErrorException 微信API调用异常 */ String post(WxMpApiUrl url, String postData) throws WxErrorException; /** * 当本Service没有实现某个API的时候，可以用这个，针对所有微信API中的POST请求. * - * @param url 请求接口地址 - * @param obj 请求参数 - * @return 接口响应字符串 string - * @throws WxErrorException 异常 + * @param url 请求接口地址，通过WxMpApiUrl枚举指定 + * @param obj 请求参数，对象格式，会被序列化为JSON + * @return 接口响应字符串，JSON格式 + * @throws WxErrorException 微信API调用异常 */ String post(WxMpApiUrl url, Object obj) throws WxErrorException; /** * 当本Service没有实现某个API的时候，可以用这个，针对所有微信API中的POST请求. * - * @param url 请求接口地址 - * @param jsonObject 请求参数json对象 - * @return 接口响应字符串 string - * @throws WxErrorException 异常 + * @param url 请求接口地址，通过WxMpApiUrl枚举指定 + * @param jsonObject 请求参数json对象，JSON格式 + * @return 接口响应字符串，JSON格式 + * @throws WxErrorException 微信API调用异常 */ String post(WxMpApiUrl url, JsonObject jsonObject) throws WxErrorException; @@ -314,20 +315,20 @@ public interface WxMpService extends WxService { * 可以参考，{@link MediaUploadRequestExecutor}的实现方法 * * - * @param the type parameter - * @param the type parameter - * @param executor 执行器 - * @param url 接口地址 - * @param data 参数数据 - * @return 结果 t - * @throws WxErrorException 异常 + * @param 返回值类型 + * @param 参数类型 + * @param executor 执行器，用于处理请求和响应 + * @param url 接口地址，通过WxMpApiUrl枚举指定 + * @param data 参数数据，根据API不同可能是不同类型 + * @return 结果，根据API不同可能是不同类型 + * @throws WxErrorException 微信API调用异常 */ T execute(RequestExecutor executor, WxMpApiUrl url, E data) throws WxErrorException; /** * 设置当微信系统响应系统繁忙时，要等待多少 retrySleepMillis(ms) * 2^(重试次数 - 1) 再发起重试. * - * @param retrySleepMillis 默认：1000ms + * @param retrySleepMillis 重试等待时间，单位毫秒，默认1000ms */ void setRetrySleepMillis(int retrySleepMillis); @@ -337,36 +338,36 @@ public interface WxMpService extends WxService { * 默认：5次 * * - * @param maxRetryTimes 最大重试次数 + * @param maxRetryTimes 最大重试次数，默认5次 */ void setMaxRetryTimes(int maxRetryTimes); /** * 获取WxMpConfigStorage 对象. * - * @return WxMpConfigStorage wx mp config storage + * @return WxMpConfigStorage 微信公众号配置存储对象 */ WxMpConfigStorage getWxMpConfigStorage(); /** * 设置 {@link WxMpConfigStorage} 的实现. 兼容老版本 * - * @param wxConfigProvider . + * @param wxConfigProvider 微信公众号配置存储对象 */ void setWxMpConfigStorage(WxMpConfigStorage wxConfigProvider); /** * Map里 加入新的 {@link WxMpConfigStorage}，适用于动态添加新的微信公众号配置. * - * @param mpId 公众号id - * @param configStorage 新的微信配置 + * @param mpId 公众号id，用于标识不同的公众号 + * @param configStorage 新的微信配置，微信公众号配置存储对象 */ void addConfigStorage(String mpId, WxMpConfigStorage configStorage); /** * 从 Map中 移除 {@link String mpId} 所对应的 {@link WxMpConfigStorage}，适用于动态移除微信公众号配置. * - * @param mpId 对应公众号的标识 + * @param mpId 对应公众号的标识，用于标识不同的公众号 */ void removeConfigStorage(String mpId); @@ -374,14 +375,14 @@ public interface WxMpService extends WxService { * 注入多个 {@link WxMpConfigStorage} 的实现. 并为每个 {@link WxMpConfigStorage} 赋予不同的 {@link String mpId} 值 * 随机采用一个{@link String mpId}进行Http初始化操作 * - * @param configStorages WxMpConfigStorage map + * @param configStorages WxMpConfigStorage map，公众号id到配置存储对象的映射 */ void setMultiConfigStorages(Map configStorages); /** * 注入多个 {@link WxMpConfigStorage} 的实现. 并为每个 {@link WxMpConfigStorage} 赋予不同的 {@link String label} 值 * - * @param configStorages WxMpConfigStorage map + * @param configStorages WxMpConfigStorage map，公众号id到配置存储对象的映射 * @param defaultMpId 设置一个{@link WxMpConfigStorage} 所对应的{@link String mpId}进行Http初始化 */ void setMultiConfigStorages(Map configStorages, String defaultMpId); @@ -389,132 +390,146 @@ public interface WxMpService extends WxService { /** * 进行相应的公众号切换. * - * @param mpId 公众号标识 - * @return 切换是否成功 boolean + * @param mpId 公众号标识，用于标识不同的公众号 + * @return 切换是否成功，true表示成功，false表示失败 */ boolean switchover(String mpId); + /** + * 进行相应的公众号切换，支持自定义配置获取函数. + * + * @param mpId 公众号标识，用于标识不同的公众号 + * @param func 自定义配置获取函数，当配置不存在时使用 + * @return 切换是否成功，true表示成功，false表示失败 + */ boolean switchover(String mpId, Function func); /** * 进行相应的公众号切换. * - * @param mpId 公众号标识 + * @param mpId 公众号标识，用于标识不同的公众号 * @return 切换成功 ，则返回当前对象，方便链式调用，否则抛出异常 */ WxMpService switchoverTo(String mpId); + /** + * 进行相应的公众号切换，支持自定义配置获取函数. + * + * @param mpId 公众号标识，用于标识不同的公众号 + * @param func 自定义配置获取函数，当配置不存在时使用 + * @return 切换成功 ，则返回当前对象，方便链式调用，否则抛出异常 + */ WxMpService switchoverTo(String mpId, Function func); /** * 返回客服接口方法实现类，以方便调用其各个接口. * - * @return WxMpKefuService kefu service + * @return WxMpKefuService 客服服务接口 */ WxMpKefuService getKefuService(); /** * 返回素材相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpMaterialService material service + * @return WxMpMaterialService 素材服务接口 */ WxMpMaterialService getMaterialService(); /** * 返回菜单相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpMenuService menu service + * @return WxMpMenuService 菜单服务接口 */ WxMpMenuService getMenuService(); /** * 返回用户相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpUserService user service + * @return WxMpUserService 用户服务接口 */ WxMpUserService getUserService(); /** * 返回用户标签相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpUserTagService user tag service + * @return WxMpUserTagService 用户标签服务接口 */ WxMpUserTagService getUserTagService(); /** * 返回二维码相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpQrcodeService qrcode service + * @return WxMpQrcodeService 二维码服务接口 */ WxMpQrcodeService getQrcodeService(); /** * 返回卡券相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpCardService card service + * @return WxMpCardService 卡券服务接口 */ WxMpCardService getCardService(); /** * 返回数据分析统计相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpDataCubeService data cube service + * @return WxMpDataCubeService 数据分析服务接口 */ WxMpDataCubeService getDataCubeService(); /** * 返回用户黑名单管理相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpUserBlacklistService black list service + * @return WxMpUserBlacklistService 用户黑名单服务接口 */ WxMpUserBlacklistService getBlackListService(); /** * 返回门店管理相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpStoreService store service + * @return WxMpStoreService 门店服务接口 */ WxMpStoreService getStoreService(); /** * 返回模板消息相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpTemplateMsgService template msg service + * @return WxMpTemplateMsgService 模板消息服务接口 */ WxMpTemplateMsgService getTemplateMsgService(); /** * 返回一次性订阅消息相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpSubscribeMsgService subscribe msg service + * @return WxMpSubscribeMsgService 订阅消息服务接口 */ WxMpSubscribeMsgService getSubscribeMsgService(); /** * 返回硬件平台相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpDeviceService device service + * @return WxMpDeviceService 硬件平台服务接口 */ WxMpDeviceService getDeviceService(); /** * 返回摇一摇周边相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpShakeService shake service + * @return WxMpShakeService 摇一摇周边服务接口 */ WxMpShakeService getShakeService(); /** * 返回会员卡相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpMemberCardService member card service + * @return WxMpMemberCardService 会员卡服务接口 */ WxMpMemberCardService getMemberCardService(); /** * 返回营销相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpMarketingService marketing service + * @return WxMpMarketingService 营销服务接口 */ WxMpMarketingService getMarketingService(); @@ -526,329 +541,329 @@ public interface WxMpService extends WxService { /** * 获取RequestHttp对象. * - * @return RequestHttp对象 request http + * @return RequestHttp对象 HTTP请求处理对象 */ RequestHttp getRequestHttp(); /** * 返回群发消息相关接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpMassMessageService mass message service + * @return WxMpMassMessageService 群发消息服务接口 */ WxMpMassMessageService getMassMessageService(); /** * 返回AI开放接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpAiOpenService ai open service + * @return WxMpAiOpenService AI开放服务接口 */ WxMpAiOpenService getAiOpenService(); /** * 返回WIFI接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpWifiService wifi service + * @return WxMpWifiService WIFI服务接口 */ WxMpWifiService getWifiService(); /** - * 返回WIFI接口方法的实现类对象，以方便调用其各个接口. + * 返回OCR接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpWifiService ocr service + * @return WxOcrService OCR服务接口 */ WxOcrService getOcrService(); /** * 返回图像处理接口的实现类对象，以方便调用其各个接口. * - * @return WxImgProcService img proc service + * @return WxImgProcService 图像处理服务接口 */ WxImgProcService getImgProcService(); /** * 返回电子发票报销方相关接口 * - * @return WxMpReimburseInvoiceService reimburse invoice service + * @return WxMpReimburseInvoiceService 电子发票报销方服务接口 */ WxMpReimburseInvoiceService getReimburseInvoiceService(); /** * 返回草稿箱相关接口 * - * @return WxMpDraftService draft service + * @return WxMpDraftService 草稿箱服务接口 */ WxMpDraftService getDraftService(); /** * 返回发布能力接口 * - * @return WxMpFreePublishService free publish service + * @return WxMpFreePublishService 发布能力服务接口 */ WxMpFreePublishService getFreePublishService(); /** - * . + * 设置电子发票报销方服务接口 * - * @param reimburseInvoiceService . + * @param reimburseInvoiceService 电子发票报销方服务接口 */ void setReimburseInvoiceService(WxMpReimburseInvoiceService reimburseInvoiceService); /** - * . + * 设置客服服务接口 * - * @param kefuService . + * @param kefuService 客服服务接口 */ void setKefuService(WxMpKefuService kefuService); /** - * . + * 设置素材服务接口 * - * @param materialService . + * @param materialService 素材服务接口 */ void setMaterialService(WxMpMaterialService materialService); /** - * . + * 设置菜单服务接口 * - * @param menuService . + * @param menuService 菜单服务接口 */ void setMenuService(WxMpMenuService menuService); /** - * . + * 设置用户服务接口 * - * @param userService . + * @param userService 用户服务接口 */ void setUserService(WxMpUserService userService); /** - * . + * 设置用户标签服务接口 * - * @param userTagService . + * @param userTagService 用户标签服务接口 */ void setUserTagService(WxMpUserTagService userTagService); /** - * . + * 设置二维码服务接口 * - * @param qrcodeService . + * @param qrcodeService 二维码服务接口 */ void setQrcodeService(WxMpQrcodeService qrcodeService); /** - * . + * 设置卡券服务接口 * - * @param cardService . + * @param cardService 卡券服务接口 */ void setCardService(WxMpCardService cardService); /** - * . + * 设置门店服务接口 * - * @param storeService . + * @param storeService 门店服务接口 */ void setStoreService(WxMpStoreService storeService); /** - * . + * 设置数据分析服务接口 * - * @param dataCubeService . + * @param dataCubeService 数据分析服务接口 */ void setDataCubeService(WxMpDataCubeService dataCubeService); /** - * . + * 设置用户黑名单服务接口 * - * @param blackListService . + * @param blackListService 用户黑名单服务接口 */ void setBlackListService(WxMpUserBlacklistService blackListService); /** - * . + * 设置模板消息服务接口 * - * @param templateMsgService . + * @param templateMsgService 模板消息服务接口 */ void setTemplateMsgService(WxMpTemplateMsgService templateMsgService); /** - * . + * 设置硬件平台服务接口 * - * @param deviceService . + * @param deviceService 硬件平台服务接口 */ void setDeviceService(WxMpDeviceService deviceService); /** - * . + * 设置摇一摇周边服务接口 * - * @param shakeService . + * @param shakeService 摇一摇周边服务接口 */ void setShakeService(WxMpShakeService shakeService); /** - * . + * 设置会员卡服务接口 * - * @param memberCardService . + * @param memberCardService 会员卡服务接口 */ void setMemberCardService(WxMpMemberCardService memberCardService); /** - * . + * 设置群发消息服务接口 * - * @param massMessageService . + * @param massMessageService 群发消息服务接口 */ void setMassMessageService(WxMpMassMessageService massMessageService); /** - * . + * 设置AI开放服务接口 * - * @param aiOpenService . + * @param aiOpenService AI开放服务接口 */ void setAiOpenService(WxMpAiOpenService aiOpenService); /** - * . + * 设置营销服务接口 * - * @param marketingService . + * @param marketingService 营销服务接口 */ void setMarketingService(WxMpMarketingService marketingService); /** - * . + * 设置OCR服务接口 * - * @param ocrService . + * @param ocrService OCR服务接口 */ void setOcrService(WxOcrService ocrService); /** - * . + * 设置图像处理服务接口 * - * @param imgProcService . + * @param imgProcService 图像处理服务接口 */ void setImgProcService(WxImgProcService imgProcService); /** * 返回评论数据管理接口方法的实现类对象，以方便调用其各个接口. * - * @return WxMpWifiService comment service + * @return WxMpCommentService 评论数据管理服务接口 */ WxMpCommentService getCommentService(); /** - * . + * 设置评论数据管理服务接口 * - * @param commentService . + * @param commentService 评论数据管理服务接口 */ void setCommentService(WxMpCommentService commentService); /** - * Gets oauth2 service. + * 获取OAuth2服务接口 * - * @return the oauth2 service + * @return WxOAuth2Service OAuth2服务接口 */ WxOAuth2Service getOAuth2Service(); /** - * Sets oauth2Service. + * 设置OAuth2服务接口 * - * @param oAuth2Service the o auth 2 service + * @param oAuth2Service OAuth2服务接口 */ void setOAuth2Service(WxOAuth2Service oAuth2Service); /** - * Gets guide service. + * 获取微信导购服务接口 * - * @return the guide service + * @return WxMpGuideService 微信导购服务接口 */ WxMpGuideService getGuideService(); /** - * Sets guide service. + * 设置微信导购服务接口 * - * @param guideService the guide service + * @param guideService 微信导购服务接口 */ void setGuideService(WxMpGuideService guideService); /** - * Gets guideBuyer service. + * 获取微信导购买家服务接口 * - * @return the guideBuyer service + * @return WxMpGuideBuyerService 微信导购买家服务接口 */ WxMpGuideBuyerService getGuideBuyerService(); /** - * Sets guideBuyer service. + * 设置微信导购买家服务接口 * - * @param guideBuyerService the guideBuyer service + * @param guideBuyerService 微信导购买家服务接口 */ void setGuideBuyerService(WxMpGuideBuyerService guideBuyerService); /** - * Gets guideTag service. + * 获取微信导购标签服务接口 * - * @return the guide service + * @return WxMpGuideTagService 微信导购标签服务接口 */ WxMpGuideTagService getGuideTagService(); /** - * Sets guideTag service. + * 设置微信导购标签服务接口 * - * @param guideTagService the guideTag service + * @param guideTagService 微信导购标签服务接口 */ void setGuideTagService(WxMpGuideTagService guideTagService); /** - * Gets guideMaterial service. + * 获取微信导购素材服务接口 * - * @return the guideMaterial service + * @return WxMpGuideMaterialService 微信导购素材服务接口 */ WxMpGuideMaterialService getGuideMaterialService(); /** - * Sets guideMaterial service. + * 设置微信导购素材服务接口 * - * @param guideMaterialService the guideMaterial service + * @param guideMaterialService 微信导购素材服务接口 */ void setGuideMaterialService(WxMpGuideMaterialService guideMaterialService); /** - * Gets guideMassedJob service. + * 获取微信导购批量任务服务接口 * - * @return the guideMassedJob service + * @return WxMpGuideMassedJobService 微信导购批量任务服务接口 */ WxMpGuideMassedJobService getGuideMassedJobService(); /** - * Sets guide service. + * 设置微信导购批量任务服务接口 * - * @param guideMassedJobService the guide service + * @param guideMassedJobService 微信导购批量任务服务接口 */ void setGuideMassedJobService(WxMpGuideMassedJobService guideMassedJobService); /** - * Gets merchant invoice service. + * 获取微信商户发票服务接口 * - * @return the merchant invoice service + * @return WxMpMerchantInvoiceService 微信商户发票服务接口 */ WxMpMerchantInvoiceService getMerchantInvoiceService(); /** - * Sets merchant invoice service. + * 设置微信商户发票服务接口 * - * @param merchantInvoiceService the merchant invoice service + * @param merchantInvoiceService 微信商户发票服务接口 */ void setMerchantInvoiceService(WxMpMerchantInvoiceService merchantInvoiceService); /** - * Sets draft service. + * 设置草稿箱服务接口 * - * @param draftService the draft service + * @param draftService 草稿箱服务接口 */ void setDraftService(WxMpDraftService draftService); /** - * Sets free publish service. + * 设置发布能力服务接口 * - * @param freePublishService the free publish service + * @param freePublishService 发布能力服务接口 */ void setFreePublishService(WxMpFreePublishService freePublishService); } diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpTemplateMsgService.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpTemplateMsgService.java index 5605c9365..d84737909 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpTemplateMsgService.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpTemplateMsgService.java @@ -8,105 +8,178 @@ import me.chanjar.weixin.mp.bean.template.WxMpTemplateMessage; import java.util.List; /** - * 
  * 模板消息接口
- * http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
+ * 

+ * 提供微信模板消息的发送、行业设置、模板管理等功能。
+ * 模板消息用于在用户触发特定事件后，向用户发送重要的服务通知。
+ * 

+ * 

+ * 详情请见：模板消息开发文档
+ * 

  * Created by Binary Wang on 2016-10-14.
+ *
  * @author miller.lin
- * @author  Binary Wang
+ * @author Binary Wang */ public interface WxMpTemplateMsgService { - /** - * 
-   * 设置所属行业
-   * 官方文档中暂未告知响应内容
-   * 详情请见：http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   *
- * - * @param wxMpIndustry 行业信息 - * @return 是否成功 industry - * @throws WxErrorException . - */ - boolean setIndustry(WxMpTemplateIndustry wxMpIndustry) throws WxErrorException; + /** + * 
+     * 设置所属行业
+     * 官方文档中暂未告知响应内容
+     *
+ * + * @param wxMpIndustry 行业信息 + * @return 是否成功设置行业 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 设置所属行业 + */ + boolean setIndustry(WxMpTemplateIndustry wxMpIndustry) throws WxErrorException; - /*** - * 
-   * 获取设置的行业信息
-   * 详情请见：http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   *
- * - * @return wxMpIndustry industry - * @throws WxErrorException . - */ - WxMpTemplateIndustry getIndustry() throws WxErrorException; + /** + * 
+     * 获取设置的行业信息
+     *
+ * + * @return 行业信息对象 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 获取设置的行业信息 + */ + WxMpTemplateIndustry getIndustry() throws WxErrorException; - /** - * 
-   * 发送模板消息
-   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   *
- * - * @param templateMessage 模板消息 - * @return 消息Id string - * @throws WxErrorException . - */ - String sendTemplateMsg(WxMpTemplateMessage templateMessage) throws WxErrorException; + /** + * 
+     * 发送模板消息
+     *
+ * + * @param templateMessage 模板消息对象 + * @return 消息ID，可用于查询模板消息发送状态 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 发送模板消息 + */ + String sendTemplateMsg(WxMpTemplateMessage templateMessage) throws WxErrorException; - /** - * 
-   * 获得模板ID
-   * 从行业模板库选择模板到账号后台，获得模板ID的过程可在MP中完成
-   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   * 接口地址格式：https://api.weixin.qq.com/cgi-bin/template/api_add_template?access_token=ACCESS_TOKEN
-   *
- * - * @param shortTemplateId 模板库中模板的编号，有“TM**”和“OPENTMTM**”等形式 - * @return templateId 模板Id - * @throws WxErrorException . - * @deprecated 请使用 addTemplate(java.lang.String, java.util.List) - */ - @Deprecated - String addTemplate(String shortTemplateId) throws WxErrorException; + /** + * 
+     * 获得模板ID
+     * 从行业模板库选择模板到账号后台，获得模板ID的过程可在MP中完成
+     *
+ * + * @param shortTemplateId 模板库中模板的编号，有"TM**"和"OPENTMTM**"等形式 + * @return 模板ID + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @deprecated 请使用 {@link #addTemplate(String, List)} + * @see 获得模板ID + */ + @Deprecated + String addTemplate(String shortTemplateId) throws WxErrorException; - /** - * 
-   * 获得模板ID
-   * 从类目模板库选择模板到账号后台，获得模板ID的过程可在MP中完成
-   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   * 接口地址格式：https://api.weixin.qq.com/cgi-bin/template/api_add_template?access_token=ACCESS_TOKEN
-   *
- * - * @param shortTemplateId 模板库中模板的编号，有“TM**”和“OPENTMTM**”等形式,对于类目模板，为纯数字ID - * @param keywordNameList 选用的类目模板的关键词,按顺序传入,如果为空，或者关键词不在模板库中，会返回40246错误码 - * @return templateId 模板Id - * @throws WxErrorException . - */ - String addTemplate(String shortTemplateId, List keywordNameList) throws WxErrorException; + /** + * 
+     * 获得模板ID
+     * 从类目模板库选择模板到账号后台，获得模板ID的过程可在MP中完成
+     *
+ * + * @param shortTemplateId 模板库中模板的编号，有"TM**"和"OPENTMTM**"等形式，对于类目模板，为纯数字ID + * @param keywordNameList 选用的类目模板的关键词，按顺序传入，如果为空，或者关键词不在模板库中，会返回40246错误码 + * @return 模板ID + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 40246 - 关键词不在模板库中
    • + *
  • 其他业务错误码
    • + *
+ * @see 获得模板ID + */ + String addTemplate(String shortTemplateId, List keywordNameList) throws WxErrorException; - /** - * 
-   * 获取模板列表
-   * 获取已添加至账号下所有模板列表，可在MP中查看模板列表信息，为方便第三方开发者，提供通过接口调用的方式来获取账号下所有模板信息
-   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   * 接口地址格式：https://api.weixin.qq.com/cgi-bin/template/get_all_private_template?access_token=ACCESS_TOKEN
-   *
- * - * @return templateId 模板Id - * @throws WxErrorException . - */ - List getAllPrivateTemplate() throws WxErrorException; + /** + * 
+     * 获取模板列表
+     * 获取已添加至账号下所有模板列表，可在MP中查看模板列表信息，为方便第三方开发者，提供通过接口调用的方式来获取账号下所有模板信息
+     *
+ * + * @return 模板列表，包含所有已添加的模板信息 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 获取模板列表 + */ + List getAllPrivateTemplate() throws WxErrorException; - /** - * 
-   * 删除模板
-   * 删除模板可在MP中完成，为方便第三方开发者，提供通过接口调用的方式来删除某账号下的模板
-   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   * 接口地址格式：https://api.weixin.qq.com/cgi-bin/template/del_private_template?access_token=ACCESS_TOKEN
-   *
- * - * @param templateId 模板Id - * @return . boolean - * @throws WxErrorException . - */ - boolean delPrivateTemplate(String templateId) throws WxErrorException; + /** + * 
+     * 删除模板
+     * 删除模板可在MP中完成，为方便第三方开发者，提供通过接口调用的方式来删除某账号下的模板
+     *
+ * + * @param templateId 模板ID + * @return 是否成功删除 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 删除模板 + */ + boolean delPrivateTemplate(String templateId) throws WxErrorException; } diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserService.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserService.java index 882fe93c0..d696c512e 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserService.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserService.java @@ -22,9 +22,9 @@ public interface WxMpUserService { * 接口地址：https://api.weixin.qq.com/cgi-bin/user/info/updateremark?access_token=ACCESS_TOKEN * * - * @param openid 用户openid - * @param remark 备注名 - * @throws WxErrorException the wx error exception + * @param openid 用户openid，标识具体的用户 + * @param remark 备注名，长度限制为30字符以内 + * @throws WxErrorException 微信API调用异常 */ void userUpdateRemark(String openid, String remark) throws WxErrorException; @@ -36,9 +36,9 @@ public interface WxMpUserService { * 接口地址：https://api.weixin.qq.com/cgi-bin/user/info?access_token=ACCESS_TOKEN&openid=OPENID&lang=zh_CN * * - * @param openid 用户openid - * @return the wx mp user - * @throws WxErrorException the wx error exception + * @param openid 用户openid，标识具体的用户 + * @return 用户基本信息，包含昵称、头像、性别、关注时间等 + * @throws WxErrorException 微信API调用异常 */ WxMpUser userInfo(String openid) throws WxErrorException; @@ -50,10 +50,10 @@ public interface WxMpUserService { * 接口地址：https://api.weixin.qq.com/cgi-bin/user/info?access_token=ACCESS_TOKEN&openid=OPENID&lang=zh_CN * * - * @param openid 用户openid + * @param openid 用户openid，标识具体的用户 * @param lang 语言，zh_CN 简体(默认)，zh_TW 繁体，en 英语 - * @return the wx mp user - * @throws WxErrorException the wx error exception + * @return 用户基本信息，包含昵称、头像、性别、关注时间等 + * @throws WxErrorException 微信API调用异常 */ WxMpUser userInfo(String openid, String lang) throws WxErrorException; @@ -66,9 +66,9 @@ public interface WxMpUserService { * 接口地址：https://api.weixin.qq.com/cgi-bin/user/info/batchget?access_token=ACCESS_TOKEN * * - * @param openidList 用户openid列表 - * @return the list - * @throws WxErrorException the wx error exception + * @param openidList 用户openid列表，最多100个 + * @return 用户基本信息列表，包含每个用户的基本信息 + * @throws WxErrorException 微信API调用异常 */ List userInfoList(List openidList) throws WxErrorException; @@ -81,9 +81,9 @@ public interface WxMpUserService { * 接口地址：https://api.weixin.qq.com/cgi-bin/user/info/batchget?access_token=ACCESS_TOKEN * * - * @param userQuery 详细查询参数 - * @return the list - * @throws WxErrorException the wx error exception + * @param userQuery 详细查询参数，包含openid列表和语言设置 + * @return 用户基本信息列表，包含每个用户的基本信息 + * @throws WxErrorException 微信API调用异常 */ List userInfoList(WxMpUserQuery userQuery) throws WxErrorException; @@ -99,8 +99,8 @@ public interface WxMpUserService { * * * @param nextOpenid 可选，第一个拉取的OPENID，null为从头开始拉取 - * @return the wx mp user list - * @throws WxErrorException the wx error exception + * @return 用户列表，包含关注者OpenID列表和下一个OpenID + * @throws WxErrorException 微信API调用异常 */ WxMpUserList userList(String nextOpenid) throws WxErrorException; @@ -109,9 +109,13 @@ public interface WxMpUserService { * 获取用户列表（全部） * 公众号可通过本接口来获取账号的关注者列表， * 关注者列表由一串OpenID（加密后的微信号，每个用户对每个公众号的OpenID是唯一的）组成。 - * @return the wx mp user list - * @throws WxErrorException the wx error exception - * @see #userList(java.lang.String) #userList(java.lang.String)的增强，内部进行了多次数据拉取的汇总 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140840&token=&lang=zh_CN http请求方式: GET（请使用https协议） 接口地址：https://api.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&next_openid=NEXT_OPENID + * @return 用户列表，包含所有关注者的OpenID列表 + * @throws WxErrorException 微信API调用异常 + * @see #userList(String) #userList(String)的增强，内部进行了多次数据拉取的汇总 + * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140840&token=&lang=zh_CN + * http请求方式: GET（请使用https协议） + * 接口地址：https://api.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&next_openid=NEXT_OPENID + * */ WxMpUserList userList() throws WxErrorException; @@ -126,8 +130,8 @@ public interface WxMpUserService { * * @param fromAppid 原公众号的 appid * @param openidList 需要转换的openid，这些必须是旧账号目前关注的才行，否则会出错；一次最多100个 - * @return the list - * @throws WxErrorException the wx error exception + * @return openid转换结果列表，包含原openid和新openid的映射关系 + * @throws WxErrorException 微信API调用异常 */ List changeOpenid(String fromAppid, List openidList) throws WxErrorException; } diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserTagService.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserTagService.java index 3f1b7223c..8c131874c 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserTagService.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserTagService.java @@ -8,6 +8,14 @@ import java.util.List; /** * 用户标签管理相关接口 + *

+ * 提供微信公众号用户标签的创建、查询、更新、删除等功能。 + * 通过标签可以方便地对用户进行分组管理和精准营销。 + * 一个公众号最多可以创建100个标签。 + *

+ *

+ * 详情请见：用户标签管理 + *

* Created by Binary Wang on 2016/9/2. * * @author Binary Wang @@ -17,110 +25,193 @@ public interface WxMpUserTagService { * 
      * 创建标签
      * 一个公众号，最多可以创建100个标签。
-     * 详情请见：用户标签管理
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/create?access_token=ACCESS_TOKEN
      *
* * @param name 标签名字（30个字符以内） - * @return the wx user tag - * @throws WxErrorException the wx error exception + * @return 创建的标签对象，包含标签ID等信息 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 用户标签管理 + * @see 创建标签接口 */ WxUserTag tagCreate(String name) throws WxErrorException; /** * 
      * 获取公众号已创建的标签
-     * 详情请见：用户标签管理
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/get?access_token=ACCESS_TOKEN
      *
* - * @return the list - * @throws WxErrorException the wx error exception + * @return 标签列表，包含所有已创建的标签信息 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 用户标签管理 + * @see 获取标签接口 */ List tagGet() throws WxErrorException; /** * 
      * 编辑标签
-     * 详情请见：用户标签管理
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/update?access_token=ACCESS_TOKEN
+     * 可以修改标签的名称，但不能修改标签ID。
      *
* - * @param tagId the tag id - * @param name the name - * @return the boolean - * @throws WxErrorException the wx error exception + * @param tagId 标签ID，不能为null + * @param name 新的标签名字（30个字符以内） + * @return 操作是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 用户标签管理 + * @see 编辑标签接口 */ Boolean tagUpdate(Long tagId, String name) throws WxErrorException; /** * 
      * 删除标签
-     * 详情请见：用户标签管理
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/delete?access_token=ACCESS_TOKEN
+     * 删除标签后，该标签下的所有用户将被取消标签。
      *
* - * @param tagId the tag id - * @return the boolean - * @throws WxErrorException the wx error exception + * @param tagId 标签ID，不能为null + * @return 操作是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 用户标签管理 + * @see 删除标签接口 */ Boolean tagDelete(Long tagId) throws WxErrorException; /** * 
      * 获取标签下粉丝列表
-     * 详情请见：用户标签管理
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/user/tag/get?access_token=ACCESS_TOKEN
+     * 可用于获取某个标签下的所有用户信息，支持分页查询。
      *
* - * @param tagId the tag id - * @param nextOpenid the next openid - * @return the wx tag list user - * @throws WxErrorException the wx error exception + * @param tagId 标签ID，不能为null + * @param nextOpenid 第一个拉取用户的openid，不填从头开始拉取 + * @return 标签下粉丝列表对象，包含用户信息和分页信息 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 用户标签管理 + * @see 获取标签下粉丝列表接口 */ - WxTagListUser tagListUser(Long tagId, String nextOpenid) - throws WxErrorException; + WxTagListUser tagListUser(Long tagId, String nextOpenid) throws WxErrorException; /** * 
      * 批量为用户打标签
-     * 详情请见：用户标签管理
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/members/batchtagging?access_token=ACCESS_TOKEN
+     * 可以为多个用户同时打上同一个标签。
      *
* - * @param tagId the tag id - * @param openids the openids - * @return the boolean - * @throws WxErrorException the wx error exception + * @param tagId 标签ID，不能为null + * @param openids 用户openid数组，不能为null或空数组 + * @return 操作是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 用户标签管理 + * @see 批量为用户打标签接口 */ boolean batchTagging(Long tagId, String[] openids) throws WxErrorException; /** * 
      * 批量为用户取消标签
-     * 详情请见：用户标签管理
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/members/batchuntagging?access_token=ACCESS_TOKEN
+     * 可以为多个用户同时取消同一个标签。
      *
* - * @param tagId the tag id - * @param openids the openids - * @return the boolean - * @throws WxErrorException the wx error exception + * @param tagId 标签ID，不能为null + * @param openids 用户openid数组，不能为null或空数组 + * @return 操作是否成功，true表示成功，false表示失败 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 用户标签管理 + * @see 批量为用户取消标签接口 */ boolean batchUntagging(Long tagId, String[] openids) throws WxErrorException; - /** * 
      * 获取用户身上的标签列表
-     * 详情请见：用户标签管理
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/getidlist?access_token=ACCESS_TOKEN
+     * 可查询某个用户被打上的所有标签ID。
      *
* - * @param openid the openid - * @return 标签Id的列表 list - * @throws WxErrorException the wx error exception + * @param openid 用户的openid，不能为null或空字符串 + * @return 标签ID的列表，表示该用户被打上的所有标签 + * @throws WxErrorException 微信API调用异常，可能包括： + *
    + *
  • 40001 - 获取access_token时AppSecret错误，或者access_token无效
    • + *
  • 40002 - 请确保grant_type字段值为client_credential
    • + *
  • 40003 - appid对应公众号请开发者使用绑定的公众号测试
    • + *
  • 40004 - appid不正确
    • + *
  • 40006 - access_token超时
    • + *
  • 48001 - api功能未授权
    • + *
  • 45009 - 调用接口的QPS超限
    • + *
  • 其他业务错误码
    • + *
+ * @see 用户标签管理 + * @see 获取用户身上的标签列表接口 */ List userTagList(String openid) throws WxErrorException; - } diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpAiOpenServiceImpl.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpAiOpenServiceImpl.java index 9c9bbe84c..a6dd8135b 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpAiOpenServiceImpl.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpAiOpenServiceImpl.java @@ -15,59 +15,57 @@ import java.io.File; import static me.chanjar.weixin.mp.enums.WxMpApiUrl.AiOpen.*; /** - * 
- *  Created by BinaryWang on 2018/6/9.
- *
+ * Created by BinaryWang on 2018/6/9. * * @author Binary Wang */ @RequiredArgsConstructor public class WxMpAiOpenServiceImpl implements WxMpAiOpenService { - private final WxMpService wxMpService; + private final WxMpService wxMpService; - @Override - public void uploadVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException { - if (lang == null) { - lang = AiLangType.zh_CN; + @Override + public void uploadVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException { + if (lang == null) { + lang = AiLangType.zh_CN; + } + + this.wxMpService.execute(VoiceUploadRequestExecutor.create(this.wxMpService.getRequestHttp()), + String.format(VOICE_UPLOAD_URL.getUrl(this.wxMpService.getWxMpConfigStorage()), "mp3", voiceId, lang.getCode()), + voiceFile); } - this.wxMpService.execute(VoiceUploadRequestExecutor.create(this.wxMpService.getRequestHttp()), - String.format(VOICE_UPLOAD_URL.getUrl(this.wxMpService.getWxMpConfigStorage()), "mp3", voiceId, lang.getCode()), - voiceFile); - } + @Override + public String queryRecognitionResult(String voiceId, AiLangType lang) throws WxErrorException { + if (lang == null) { + lang = AiLangType.zh_CN; + } - @Override - public String recogniseVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException { - this.uploadVoice(voiceId, lang, voiceFile); - return this.queryRecognitionResult(voiceId, lang); - } + final String response = this.wxMpService.get(VOICE_QUERY_RESULT_URL, + String.format("voice_id=%s&lang=%s", voiceId, lang.getCode())); + WxError error = WxError.fromJson(response, WxType.MP); + if (error.getErrorCode() != 0) { + throw new WxErrorException(error); + } - @Override - public String translate(AiLangType langFrom, AiLangType langTo, String content) throws WxErrorException { - String response = this.wxMpService.post(String.format(TRANSLATE_URL.getUrl(this.wxMpService.getWxMpConfigStorage()), - langFrom.getCode(), langTo.getCode()), content); - - WxError error = WxError.fromJson(response, WxType.MP); - if (error.getErrorCode() != 0) { - throw new WxErrorException(error); + return GsonParser.parse(response).get("result").getAsString(); } - return GsonParser.parse(response).get("to_content").getAsString(); - } - - @Override - public String queryRecognitionResult(String voiceId, AiLangType lang) throws WxErrorException { - if (lang == null) { - lang = AiLangType.zh_CN; + @Override + public String recogniseVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException { + this.uploadVoice(voiceId, lang, voiceFile); + return this.queryRecognitionResult(voiceId, lang); } - final String response = this.wxMpService.get(VOICE_QUERY_RESULT_URL, - String.format("voice_id=%s&lang=%s", voiceId, lang.getCode())); - WxError error = WxError.fromJson(response, WxType.MP); - if (error.getErrorCode() != 0) { - throw new WxErrorException(error); - } + @Override + public String translate(AiLangType langFrom, AiLangType langTo, String content) throws WxErrorException { + String response = this.wxMpService.post(String.format(TRANSLATE_URL.getUrl(this.wxMpService.getWxMpConfigStorage()), + langFrom.getCode(), langTo.getCode()), content); - return GsonParser.parse(response).get("result").getAsString(); - } + WxError error = WxError.fromJson(response, WxType.MP); + if (error.getErrorCode() != 0) { + throw new WxErrorException(error); + } + + return GsonParser.parse(response).get("to_content").getAsString(); + } } diff --git a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpUserTagServiceImpl.java b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpUserTagServiceImpl.java index 007942f09..63a3208e4 100644 --- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpUserTagServiceImpl.java +++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpUserTagServiceImpl.java @@ -46,10 +46,10 @@ public class WxMpUserTagServiceImpl implements WxMpUserTagService { } @Override - public Boolean tagUpdate(Long id, String name) throws WxErrorException { + public Boolean tagUpdate(Long tagId, String name) throws WxErrorException { JsonObject json = new JsonObject(); JsonObject tagJson = new JsonObject(); - tagJson.addProperty("id", id); + tagJson.addProperty("id", tagId); tagJson.addProperty("name", name); json.add("tag", tagJson); @@ -63,10 +63,10 @@ public class WxMpUserTagServiceImpl implements WxMpUserTagService { } @Override - public Boolean tagDelete(Long id) throws WxErrorException { + public Boolean tagDelete(Long tagId) throws WxErrorException { JsonObject json = new JsonObject(); JsonObject tagJson = new JsonObject(); - tagJson.addProperty("id", id); + tagJson.addProperty("id", tagId); json.add("tag", tagJson); String responseContent = this.wxMpService.post(TAGS_DELETE, json.toString());