获取文件上传地址

• 接口：common/files/v3/uploadUrl
• Method：POST
• 数据格式：JSON
• 限流信息：每小时1000次
• 接口说明：本接口为批量接口，接口返回成功不代表全部处理成功。具体参见示例
• 变更历史

接口使用说明

文件上传分为以下两步完成：

1. 获取文件上传地址（upload_url）

   • 客户端向业务服务器发起请求，携带文件基本信息（文件名、类型）。
   • 服务器校验权限后，返回一个临时的文件上传地址（upload_url），有效期2小时。

2. 直传文件到对象存储

   • 客户端使用返回的 upload_url，直接向对象存储（如 AWS S3、阿里云 OSS、华为云 OBS）发起上传请求。
   • 对象存储处理完成后，返回上传结果（成功/失败）。

上传方式示例

curl -X PUT -T "your-file.txt" "{upload_url}" -H "Content-Type: your-file-mime-type"

调用说明

参数

请求参数

返回参数

示例

请求数据

{
  "bizId": "2c1ece50-3cab-4f1c-a5d9-fd297afdd1e2",
  "timestamp": 1744252563000,
  "data": [
    {
      "file_name": "test.png",
      "content_type": "image/png"
    },
    {
      "file_name": "test.pdf",
      "content_type": "application/pdf"
    }
  ]
}

返回数据

全部处理成功返回

{
  "resCode": 200000,
  "resMsg": "success",
  "bizId": "2c1ece50-3cab-4f1c-a5d9-fd297afdd1e2",
  "data": [
    {
      "file_name": "test.png",
      "upload_url": "https://xxx/cc28cda9-836c-493f-81c8-7e23d78cdf2f.png?xxxx",
      "attachment_url": "cc28cda9-836c-493f-81c8-7e23d78cdf2f.png"
    },
    {
      "file_name": "test.pdf",
      "upload_url": "https://xxxx/a2244808-ad23-437d-98b3-c0318e26a115.pdf?xxxxx",
      "attachment_url": "a2244808-ad23-437d-98b3-c0318e26a115.pdf"
    }
  ]
}

部分处理成功返回

{
  "resCode": 200000,
  "resMsg": "success",
  "bizId": "2c1ece50-3cab-4f1c-a5d9-fd297afdd1e2",
  "data": [
    {
      "file_name": "test.png",
      "upload_url": "https://xxx/cc28cda9-836c-493f-81c8-7e23d78cdf2f.png?xxxx",
      "attachment_url": "cc28cda9-836c-493f-81c8-7e23d78cdf2f.png"
    }
  ]
}

全部处理失败返回

{
  "resCode": 200000,
  "resMsg": "success",
  "bizId": "2c1ece50-3cab-4f1c-a5d9-fd297afdd1e2",
  "data": []
}

代码示例

使用文件上传地址上传文件

也可以参考各对象存储的使用签名URL临时授权上传文件的相关示例

import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.entity.FileEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;

import java.nio.file.Files;
import java.nio.file.Paths;
import java.io.File;
import java.io.IOException;

public class Test {
    public static void main(String[] args) throws IOException {
        CloseableHttpClient httpClient = null;
        CloseableHttpResponse response = null;
        String pathName = "test.pdf";
        URL signedUrl = new URL("https://xxxxxx.amazonaws.com.cn/6307ced9-c793-450f-a2a5-5c4f615619af.pdf?xxxxx");
        try {
            HttpPut put = new HttpPut(signedUrl.toString());
            HttpEntity entity = new FileEntity(new File(pathName));
            put.setEntity(entity);

            // 获取文件内容类型，与获取文件上传链接的入参一致
            String contentType = Files.probeContentType(Paths.get(pathName));
            if (contentType == null) {
                contentType = getContentType(Paths.get(pathName).getFileName().toString().toLowerCase());
            }
            put.setHeader("Content-Type", contentType);
            httpClient = HttpClients.createDefault();
            response = httpClient.execute(put);

            System.out.println("返回上传状态码：" + response.getStatusLine().getStatusCode());
            if (response.getStatusLine().getStatusCode() == 200) {
                System.out.println("上传成功");
            }
            System.out.println(response.toString());
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            if (response != null) {
                response.close();
            }
            if (httpClient != null) {
                httpClient.close();
            }
        }
    }

    private static String getContentType(String fileName) {
        String contentType = "application/octet-stream";
        if (fileName.endsWith(".pdf")) {
            contentType = "application/pdf";
        } else if (fileName.endsWith(".jpg") || fileName.endsWith(".jpeg")) {
            contentType = "image/jpeg";
        } else if (fileName.endsWith(".png")) {
            contentType = "image/png";
        } else if (fileName.endsWith(".gif")) {
            contentType = "image/gif";
        } else if (fileName.endsWith(".txt")) {
            contentType = "text/plain";
        } else if (fileName.endsWith(".html") || fileName.endsWith(".htm")) {
            contentType = "text/html";
        }
        return contentType;
    }
}

变更历史

历史版本