169 lines
5.5 KiB
Markdown
169 lines
5.5 KiB
Markdown
# CommonUploadParam 额外表单字段功能使用示例
|
||
|
||
## 背景
|
||
|
||
微信公众号在上传永久视频素材时，需要在POST请求中同时提交文件和一个名为`description`的表单字段，该字段包含视频的描述信息（JSON格式）。
|
||
|
||
根据微信公众号文档：
|
||
> 在上传视频素材时需要POST另一个表单，id为description，包含素材的描述信息，内容格式为JSON，格式如下：
|
||
> ```json
|
||
> {
|
||
> "title": "VIDEO_TITLE",
|
||
> "introduction": "INTRODUCTION"
|
||
> }
|
||
> ```
|
||
|
||
## 解决方案
|
||
|
||
`CommonUploadParam` 类已经扩展支持额外的表单字段，可以在上传文件的同时提交其他表单数据。
|
||
|
||
## 使用示例
|
||
|
||
### 1. 基本用法 - 上传永久视频素材
|
||
|
||
```java
|
||
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. 链式调用风格
|
||
|
||
```java
|
||
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. 多个额外表单字段
|
||
|
||
```java
|
||
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. 从字节数组上传并添加表单字段
|
||
|
||
```java
|
||
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>类型）
|
||
|
||
## 注意事项
|
||
|
||
1. **表单字段是可选的**：如果不需要额外的表单字段，可以不调用`addFormField`方法
|
||
2. **JSON格式**：对于需要JSON格式的表单字段（如description），需要先将对象转换为JSON字符串
|
||
3. **编码**：表单字段值会使用UTF-8编码
|
||
4. **所有HTTP客户端支持**：该功能在所有HTTP客户端实现中都得到支持（OkHttp、Apache HttpClient、HttpComponents、JoddHttp）
|
||
|
||
## 兼容性
|
||
|
||
该功能向后兼容，现有的不使用额外表单字段的代码无需修改即可继续工作。
|