5.5 KiB
5.5 KiB
CommonUploadParam 额外表单字段功能使用示例
背景
微信公众号在上传永久视频素材时,需要在POST请求中同时提交文件和一个名为description的表单字段,该字段包含视频的描述信息(JSON格式)。
根据微信公众号文档:
在上传视频素材时需要POST另一个表单,id为description,包含素材的描述信息,内容格式为JSON,格式如下:
{ "title": "VIDEO_TITLE", "introduction": "INTRODUCTION" }
解决方案
CommonUploadParam 类已经扩展支持额外的表单字段,可以在上传文件的同时提交其他表单数据。
使用示例
1. 基本用法 - 上传永久视频素材
import me.chanjar.weixin.common.bean.CommonUploadParam;
import me.chanjar.weixin.common.util.json.WxGsonBuilder;
import me.chanjar.weixin.mp.api.WxMpService;
import java.io.File;
import java.util.HashMap;
import java.util.Map;
public class VideoMaterialUploadExample {
public void uploadVideoMaterial(WxMpService wxMpService) throws Exception {
// 准备视频文件
File videoFile = new File("/path/to/video.mp4");
// 创建上传参数
CommonUploadParam uploadParam = CommonUploadParam.fromFile("media", videoFile);
// 准备视频描述信息(JSON格式)
Map<String, String> description = new HashMap<>();
description.put("title", "我的视频标题");
description.put("introduction", "这是一个精彩的视频介绍");
String descriptionJson = WxGsonBuilder.create().toJson(description);
// 添加description表单字段
uploadParam.addFormField("description", descriptionJson);
// 调用微信API上传
String url = "https://api.weixin.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN&type=video";
String response = wxMpService.upload(url, uploadParam);
System.out.println("上传成功:" + response);
}
}
2. 链式调用风格
import me.chanjar.weixin.common.bean.CommonUploadParam;
import com.google.gson.JsonObject;
public class ChainStyleExample {
public void uploadWithChainStyle(WxMpService wxMpService) throws Exception {
File videoFile = new File("/path/to/video.mp4");
// 准备描述信息
JsonObject description = new JsonObject();
description.addProperty("title", "视频标题");
description.addProperty("introduction", "视频介绍");
// 使用链式调用
String response = wxMpService.upload(
"https://api.weixin.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN&type=video",
CommonUploadParam.fromFile("media", videoFile)
.addFormField("description", description.toString())
);
System.out.println("上传成功:" + response);
}
}
3. 多个额外表单字段
import me.chanjar.weixin.common.bean.CommonUploadParam;
public class MultipleFormFieldsExample {
public void uploadWithMultipleFields(WxMpService wxMpService) throws Exception {
File file = new File("/path/to/file.jpg");
// 可以添加多个表单字段
CommonUploadParam uploadParam = CommonUploadParam.fromFile("media", file)
.addFormField("field1", "value1")
.addFormField("field2", "value2")
.addFormField("field3", "value3");
String response = wxMpService.upload("https://api.weixin.qq.com/some/upload/url", uploadParam);
System.out.println("上传成功:" + response);
}
}
4. 从字节数组上传并添加表单字段
import me.chanjar.weixin.common.bean.CommonUploadParam;
public class ByteArrayUploadExample {
public void uploadFromBytes(WxMpService wxMpService) throws Exception {
// 从字节数组创建上传参数
byte[] fileBytes = getFileBytes();
CommonUploadParam uploadParam = CommonUploadParam
.fromBytes("media", "video.mp4", fileBytes)
.addFormField("description", "{\"title\":\"标题\",\"introduction\":\"介绍\"}");
String response = wxMpService.upload(
"https://api.weixin.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN&type=video",
uploadParam
);
System.out.println("上传成功:" + response);
}
private byte[] getFileBytes() {
// 获取文件字节数组的逻辑
return new byte[0];
}
}
API 说明
CommonUploadParam 类
构造方法
fromFile(String name, File file)- 从文件创建上传参数fromBytes(String name, String fileName, byte[] bytes)- 从字节数组创建上传参数
方法
addFormField(String fieldName, String fieldValue)- 添加额外的表单字段,返回当前对象支持链式调用getFormFields()- 获取所有额外的表单字段(Map类型)setFormFields(Map<String, String> formFields)- 设置额外的表单字段
属性
name- 文件对应的接口参数名称(如:media)data- 上传数据(CommonUploadData对象)formFields- 额外的表单字段(可选,Map<String, String>类型)
注意事项
- 表单字段是可选的:如果不需要额外的表单字段,可以不调用
addFormField方法 - JSON格式:对于需要JSON格式的表单字段(如description),需要先将对象转换为JSON字符串
- 编码:表单字段值会使用UTF-8编码
- 所有HTTP客户端支持:该功能在所有HTTP客户端实现中都得到支持(OkHttp、Apache HttpClient、HttpComponents、JoddHttp)
兼容性
该功能向后兼容,现有的不使用额外表单字段的代码无需修改即可继续工作。