Data Agent OpenAPI 集成指南

流程概述

1. 获取签名：调用 DescribeFileUploadSignature 获取直传 OSS 所需的临时凭证和配置。

2. 上传文件：使用 HTTP客户端，构造 multipart/form-data POST 请求，将文件直传到签名中指定的 OSS 地址。

3. 上传回调：文件上传成功后，必须调用 FileUploadCallback 通知 DMS 服务，以获取 FileId。

4. (可选) 删除文件：使用 FileId 调用 DeleteFileUpload 删除已上传的文件。

流程详解

• 调用DescribeFileUploadSignature获取签名

  Config config = new Config()
    .setAccessKeyId("**********")
    .setAccessKeySecret("**********")
    .setEndpoint("dms.cn-hangzhou.aliyuncs.com")
    .setRegionId("cn-hangzhou");
  
  // 创建DMS客户端实例
  com.aliyun.dms20250414.Client client = new com.aliyun.dms20250414.Client(config);
  
  // 第一步：获取文件上传签名信息
  // 通过调用describeFileUploadSignature方法获取OSS上传所需的签名和配置信息
  DescribeFileUploadSignatureRequest request = new DescribeFileUploadSignatureRequest();
  DescribeFileUploadSignatureResponse response = client.describeFileUploadSignature(request);
  
  // response.getBody().getData()会返回如下信息，后续上传文件会依赖的参数
  // ossCredential
  // ossDate
  // ossSecurityToken
  // ossSignature
  // ossSignatureVersion
  // policy
  // uploadDir
  // uploadHost

• 使用签名信息进行上传文件

  • 代码示例：

    import okhttp3.*;
    import java.io.File;
    import java.io.IOException;
    
    /**
      * <dependency>
      *     <groupId>com.squareup.okhttp3</groupId>
      *     <artifactId>okhttp</artifactId>
      *     <version>4.12.0</version>
      * </dependency>
      */
    public class Main {
    
        public static void main(String[] args) throws IOException {
            OkHttpClient client = new OkHttpClient();
    
            # 以下参数为DescribeFileUploadSignature接口出参返回
            String policy = "eyJjb25kaXRpb25zIjpbeyJ4LW9zcy1jcmVkZW50aWFsIjoiU1RTLk5aZXdMdlN5SFRzdURFRGprSlh4VFF3YjgvMjAyNjAxMDMvY24taGFuZ3pob3Uvb3NzL2FsaXl1bl92NF9yZXF1ZXN0In0seyJ4LW9zcy1kYXRlIjoiMjAyNjAxMDNUMDYzN**********************************";
            String signature = "623e53b1d07431d17cd60389329de2906882d8c4eb****************";
            String signatureVersion = "OSS4-HMAC-SHA256";
            String credential = "STS.NZewLvSy**********/20260103/cn-hangzhou/oss/aliyun_v4_request";
            String date = "20260103T063703Z";
            String securityToken = "CAIS4gJ1q6Ft5B2yfSjIr5nQPPbCvqZp47GeRmP1jmsfVPd4vrLJ2jz2IHhMdXlrCOgYt/8xnG1V6f8flrJ/ToQAX0HfatZq5ZkS9AqnaoXM/te496IFg5D9r6Jc9c6gjqHoeOzcYI73WJXEMiLp9EJaxb/9ak/RPTiMOoGIjphKd8keWhLCAxNNGNZRIHkJyqZYTwyzU8ygKRn3mGHdIVN1sw5n8wNF5L+439eX52i17jS46JdM/9ysesH5NpQxbMwkDYnk5oEsKPqdihw3wgNR6aJ7gJZD/Tr6pdyHCzFTmU7ea7uEqYw3clYiOPBnRvEd8eKPnPl5q/HVm4Hs0wxKNuxOSCXZS4yp3MLeH+ekJgOGwWFHz9qnOLmtQXqV22tMCRpzXIiaZEa91greI6iNW+Ory74mxSFbrz3ZP4yv+o+Yv3QbMVumcySkKVbBbVvnv0R8GNsIC2lMUbp+hsgbbvFuG2QagAFh1H7d9Oe4VqNEu9A77lsl40KWoyVULPdbT+3fFlpd4s/gDL2lRdm1pTK60pwHPCp8LEI9sYOuUupKxVeNuCb0xRNOK**************************************************************";
            String key = "data_agent/file_upload/16738266********/20260103T063703Z/b8zokydg5bxg1d*********/date.csv";
            String uploadHost = "https://******.oss-cn-hangzhou.aliyuncs.com";
    
            RequestBody requestBody = new MultipartBody.Builder()
                    .setType(MultipartBody.FORM)
                    .addFormDataPart("success_action_status", "200")
                    .addFormDataPart("policy", policy)
                    .addFormDataPart("x-oss-signature", signature)
                    .addFormDataPart("x-oss-signature-version", signatureVersion)
                    .addFormDataPart("x-oss-credential", credential)
                    .addFormDataPart("x-oss-date", date)
                    .addFormDataPart("key", key)
                    .addFormDataPart("x-oss-security-token", securityToken)
                    .addFormDataPart("file", "date.csv",
                            RequestBody.create(new File("/Downloads/date.csv"), MediaType.parse("text/csv")))
                    .build();
    
            Request request = new Request.Builder()
                    .url(uploadHost)
                    .post(requestBody)
                    .build();
    
            try (Response response = client.newCall(request).execute()) {
                System.out.println("Response Code: " + response.code());
                System.out.println("Response Body: " + response.body().string());
            }
        }
    }
    

  • 参数说明：

    参数	类型	示例值	说明
    success_action_status	int	200	必填
    policy	string	eyJjb25kaXRpb25zIjpbeyJ4***********************	必填，DescribeFileUploadSignature接口出参会返回
    x-oss-signature	string	78dc0f211df15e21e********	必填，DescribeFileUploadSignature接口出参会返回
    x-oss-signature-version	string	OSS4-HMAC-SHA256	必填，DescribeFileUploadSignature接口出参会返回
    x-oss-credential	string	STS.NZdn3cJ1UX************/20260101/cn-hangzhou/oss/aliyun_v4_request	必填，DescribeFileUploadSignature接口出参会返回
    x-oss-date	string	20260101T161427Z	必填，DescribeFileUploadSignature接口出参会返回
    x-oss-security-token	string	CAIS4gJ1q6Ft5B2yfSjIr5nRJYnXp+5075etelGD3HQjYsoUj****************************	必填，DescribeFileUploadSignature接口出参会返回
    key	string	key=data_agent/file_upload/16738266************/20260101T161427Z/80z0lplhacu4***************/date.csv	必填，文件上传的完整路径，DescribeFileUploadSignature接口出参UploadDir拼接上文件名称：${UploadDir}/${文件名} UploadDir=data_agent/file_upload/16738266************/20260101T161427Z/80z0lplhacu4***************/date.csv 文件名称=date.csv
    file	string	@date.csv;type=text/csv	必填，文件名、二进制数据、文件MediaType，当前仅支持csv、xlsx、xls文件格式 file必须作为最后一个参数 文件大小上限为200MB 仅支持csv、xlsx、xls文件格式，MediaType如下 csv：text/csv xlsx：application/vnd.openxmlformats-officedocument.spreadsheetml.sheet xls：application/vnd.ms-excel

  • 实现示例：

    curl -v \
      -F "success_action_status=200" \
      -F "policy=eyJjb25kaXRpb25zIjpbeyJ4LW9zcy1jcmVkZW50aWFsIjoiU1RTLk5aZG4zY0oxVVhVRnh3Mjh0dm5FOGJ3V3ovMjAyNjAxMDEvY24taGFuZ3pob3Uvb3NzL2FsaXl1bl92NF9yZXF1ZXN0In0seyJ4LW9zcy1kYXRlIjoiMjAyNjAxMDFUMTYxNDI3WiJ9LHsieC1vc3Mtc2VjdXJpdHktdG9rZW4iOiJDQUlTNGdKMXE2RnQ1QjJ5ZlNqSXI1blJKWW5YcCs1MDc1ZXRlbEdEM0hRallzb1VqYkw4bUR6MklIaE1kWGxyQ09nWXQvOHhuRzFWNmY4ZmxySi9Ub1FBWDBIZmF0WnE1WmtTOUFxbmFvWE0vdGU0OTZJRmc1RDlvL2xOdDhHZ2pxSG9lT3pjWUk3M1dKWEVNaUxwOUVKYXhiLzlhay9SUFRpTU9vR****************************************************************************" \
      -F "x-oss-signature=78dc0f211df15e21e675ad3835a0f18f*******************" \
      -F "x-oss-signature-version=OSS4-HMAC-SHA256" \
      -F "x-oss-credential=STS.NZdn3cJ1UXU**************************************/20260101/cn-hangzhou/oss/aliyun_v4_request" \
      -F "x-oss-date=20260101T161427Z" \
      -F "key=data_agent/file_upload/16738266********/20260101T161427Z/80z0lplhacu40***********/date.csv" \
      -F "x-oss-security-token=CAIS4gJ1q6Ft5B2yfSjIr5nRJYnXp+5075etelGD3HQjYsoUjbL8mDz2IHhMdXlrCOgYt/8xnG1V6f8flrJ/ToQAX0HfatZq5ZkS9AqnaoXM/te496IFg5D9o/lNt8GgjqHoeOzcYI73WJXEMiLp9EJaxb/9ak/RPTiMOoGIjphKd8keWhLCAxNNGNZRIHkJyqZYTwyzU8ygKRn3mGHdIVN1sw5n8wNF5L+439eX52i17jS46JdM/9ysesH5NpQxbMwkDYnk5oEsKPqdihw3wgNR6aJ7gJZD/Tr6pdyHCzFTmU7ea7uEqYw3clYiOPBnRvEd8eKPnPl5q/HVm4Hs0wxKNuxOSCXZS4yp3MLeH+ekJgOGwWFHz9qnOLmtQXqV22tMCRpzXIiaJ1W/5/reI6iNW+Ory74mxSFbrz3ZP4yv+o+Yv3QbMVumcySkKVbBbVvnv0R8GNsIC2lMUbp+oQx4pPFuG2QagAFUp8U5qf8WDmpuc7ztSzLSLizgMnGPNbJGjU1dYCd2P0omHZaZyeuTj7QGpX0IW6DuKpvvHS9i/8R8M0dL2ssMsWTeK4wYE6sWXp7SbqM0mZY**************************************" \
      -F "file=@date.csv;type=text/csv" \
      "https://*******.oss-cn-hangzhou.aliyuncs.com"

• 文件上传成功后进行回调

  DescribeFileUploadSignatureResponseBody.DescribeFileUploadSignatureResponseBodyData data = response.getBody().getData();
  String filename = "data.csv";
  String uploadLocation = data.getUploadDir() + "/" +  filename;
  
  // 通知DMS服务文件已成功上传，获取文件ID
  FileUploadCallbackRequest callbackRequest = new FileUploadCallbackRequest();
  callbackRequest.setFilename(filename);              // 设置文件名
  callbackRequest.setUploadLocation(uploadLocation);  // 设置上传路径
  
  // 发送回调请求，获取文件ID
  FileUploadCallbackResponse callbackResponse = client.fileUploadCallback(callbackRequest);
  System.out.println("上传成功，文件ID: " + callbackResponse.getBody().getData().getFileId());

• 删除上传的文件

  // 根据文件ID删除上传的文件
  DeleteFileUploadRequest request = new DeleteFileUploadRequest();
  request.setFileId(callbackResponse.getBody().getData().getFileId());
  
  DeleteFileUploadResponse response = client.deleteFileUpload(request);

• 以下是一个完整的 Java 示例，整合了上述所有步骤。

  import com.aliyun.dms20250414.models.*;
  import com.aliyun.teaopenapi.models.Config;
  import okhttp3.*;
  
  import java.io.File;
  import java.io.IOException;
  
  /**
   * 文件上传示例类
   * 
   * 该示例演示了如何使用DMS服务上传文件到OSS的完整流程：
   * 1. 获取上传签名信息
   * 2. 执行文件上传到OSS
   * 3. 发送上传回调确认
   */
  public class FileUploadExample {
  
      // 定义本地文件路径和上传配置
      private static final String localFilePath = "/Users/******/Downloads/date.csv";  // 本地文件路径
      private static final String filename = "date.csv";                               // 文件名
  
      public static void main(String[] args) throws Exception {
          // 配置DMS客户端参数
          Config config = new Config()
                  .setAccessKeyId("********")
                  .setAccessKeySecret("********")
                  .setEndpoint("dms.cn-hangzhou.aliyuncs.com")
                  .setRegionId("cn-hangzhou");
  
          // 创建DMS客户端实例
          com.aliyun.dms20250414.Client client = new com.aliyun.dms20250414.Client(config);
  
          // 第一步：获取文件上传签名信息
          // 通过调用describeFileUploadSignature方法获取OSS上传所需的签名和配置信息
          DescribeFileUploadSignatureRequest request = new DescribeFileUploadSignatureRequest();
          DescribeFileUploadSignatureResponse response = client.describeFileUploadSignature(request);
          System.out.println(response.getBody().getData());
  
          // 解析响应数据，获取上传所需的配置信息
          DescribeFileUploadSignatureResponseBody.DescribeFileUploadSignatureResponseBodyData data = response.getBody().getData();
          String uploadLocation = data.getUploadDir() + "/" +  filename;                   // 在OSS中的上传路径
  
          // 第二步：执行文件上传到OSS
          // 使用获取到的签名信息，将文件上传到OSS
          int code = doUploadFile(data, filename, localFilePath, uploadLocation);
          
          // 上传成功后，发送回调确认
          if (code == 200) {
              // 第三步：上传成功后发送回调确认
              // 通知DMS服务文件已成功上传，获取文件ID
              FileUploadCallbackRequest callbackRequest = new FileUploadCallbackRequest();
              callbackRequest.setFilename(filename);              // 设置文件名
              callbackRequest.setUploadLocation(uploadLocation);  // 设置上传路径
  
              // 发送回调请求，获取文件ID
              FileUploadCallbackResponse callbackResponse = client.fileUploadCallback(callbackRequest);
              
              // 打印上传成功后的文件ID
              System.out.println("上传成功，文件ID: " + callbackResponse.getBody().getData().getFileId());
          } else {
              System.out.println("文件上传失败，状态码: " + code);
          }
      }
  
      /**
       * 执行文件上传到OSS
       * 
       * 该方法使用OkHttp客户端将文件上传到OSS，需要提供OSS签名信息、文件信息等参数
       * 
       * @param data 从describeFileUploadSignature接口获取的签名数据
       * @param filename 文件名
       * @param fileLocalPath 本地文件路径
       * @param uploadLocation 在OSS中的上传路径
       * @return 上传HTTP响应码，200表示成功
       * @throws IOException 网络或文件操作异常
       */
      private static int doUploadFile(DescribeFileUploadSignatureResponseBody.DescribeFileUploadSignatureResponseBodyData data, String filename, String fileLocalPath, String uploadLocation) throws IOException {
          OkHttpClient client = new OkHttpClient();
  
          // 构建多部分表单请求体，包含OSS上传所需的各项参数
          RequestBody requestBody = new MultipartBody.Builder()
                  .setType(MultipartBody.FORM)
                  .addFormDataPart("success_action_status", "200")                      // 必须设置success_action_status=200
                  .addFormDataPart("policy", data.getPolicy())                          // 签名策略
                  .addFormDataPart("x-oss-signature", data.getOssSignature())           // OSS签名
                  .addFormDataPart("x-oss-signature-version", data.getOssSignatureVersion()) // 签名版本
                  .addFormDataPart("x-oss-credential", data.getOssCredential())         // 凭证
                  .addFormDataPart("x-oss-date", data.getOssDate())                     // 日期
                  .addFormDataPart("key", uploadLocation)                               // 上传路径
                  .addFormDataPart("x-oss-security-token", data.getOssSecurityToken())  // 安全令牌
                  .addFormDataPart("file", filename,                                    // 文件部分
                          RequestBody.create(new File(fileLocalPath), MediaType.parse("text/csv"))) // 创建文件请求体，需要按文件类型设置媒体类型
                  .build();
  
          // 构建POST请求
          Request request = new Request.Builder()
                  .url(data.getUploadHost())  // 使用返回的上传主机地址
                  .post(requestBody)          // 设置请求体
                  .build();
  
          // 执行请求并处理响应
          try (Response response = client.newCall(request).execute()) {
              System.out.println("上传响应码: " + response.code());
              System.out.println("上传响应体: " + response.body().string());
              return response.code();
          }
      }
  }

  重要

  在构造上传请求时，请确保所有从 DescribeFileUploadSignature 获取的表单字段都已包含，且 file 字段必须是 multipart/form-data 请求的最后一个部分。

  • 文件大小上限：200MB。

  • 支持格式：CSV, XLSX, XLS。请根据文件类型设置正确的 MediaType。