Data Agent OpenAPI integration

Process overview

1. Get a signature: Call DescribeFileUploadSignature to obtain the temporary credentials and configuration required for a direct upload to OSS.

2. Upload the file: Use an HTTP client to construct a multipart/form-data POST request to upload the file directly to the OSS address specified in the signature.

3. Confirm the upload: After the file uploads successfully, call FileUploadCallback to notify the DMS service and obtain a FileId.

4. (Optional) Delete the file: Call DeleteFileUpload with the FileId to delete the uploaded file.

Detailed process

• Call DescribeFileUploadSignature to get a signature

  Config config = new Config()
    .setAccessKeyId("**********")
    .setAccessKeySecret("**********")
    .setEndpoint("dms.cn-hangzhou.aliyuncs.com")
    .setRegionId("cn-hangzhou");
  
  // Create a DMS client instance.
  com.aliyun.dms20250414.Client client = new com.aliyun.dms20250414.Client(config);
  
  // Step 1: Get the file upload signature information.
  // Call the describeFileUploadSignature method to get the signature and configuration information required for the OSS upload.
  DescribeFileUploadSignatureRequest request = new DescribeFileUploadSignatureRequest();
  DescribeFileUploadSignatureResponse response = client.describeFileUploadSignature(request);
  
  // response.getBody().getData() returns the following information, which is required for the subsequent file upload.
  // ossCredential
  // ossDate
  // ossSecurityToken
  // ossSignature
  // ossSignatureVersion
  // policy
  // uploadDir
  // uploadHost

• Upload the file using the signature information

  • Code example:

    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();
    
            // The following variables are placeholders for the values returned by the DescribeFileUploadSignature API.
            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());
            }
        }
    }
    

  • Parameter description:

    Parameter	Type	Example	Description
    success_action_status	int	200	Required.
    policy	string	eyJjb25kaXRpb25zIjpbeyJ4***********************	Required. Returned by the DescribeFileUploadSignature API.
    x-oss-signature	string	78dc0f211df15e21e********	Required. Returned by the DescribeFileUploadSignature API.
    x-oss-signature-version	string	OSS4-HMAC-SHA256	Required. Returned by the DescribeFileUploadSignature API.
    x-oss-credential	string	STS.NZdn3cJ1UX************/20260101/cn-hangzhou/oss/aliyun_v4_request	Required. Returned by the DescribeFileUploadSignature API.
    x-oss-date	string	20260101T161427Z	Required. Returned by the DescribeFileUploadSignature API.
    x-oss-security-token	string	CAIS4gJ1q6Ft5B2yfSjIr5nRJYnXp+5075etelGD3HQjYsoUj****************************	Required. Returned by the DescribeFileUploadSignature API.
    key	string	data_agent/file_upload/16738266************/20260101T161427Z/80z0lplhacu4***************/date.csv	Required. The full upload path for the file. This path combines the UploadDir from the DescribeFileUploadSignature response with the filename: ${UploadDir}/${filename} UploadDir=data_agent/file_upload/16738266************/20260101T161427Z/80z0lplhacu4***************/ filename=date.csv
    file	binary	@date.csv;type=text/csv	Required. The filename, binary data, and MediaType of the file. The file field must be the last part of the multipart/form-data request. The maximum file size is 200 MB. Supported formats and their MediaType values: csv: text/csv xlsx: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet xls: application/vnd.ms-excel

  • Implementation example (cURL):

    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"

• Confirm the upload after it succeeds

  DescribeFileUploadSignatureResponseBody.DescribeFileUploadSignatureResponseBodyData data = response.getBody().getData();
  String filename = "data.csv";
  String uploadLocation = data.getUploadDir() + "/" +  filename;
  
  // Notify the DMS service that the file has been successfully uploaded to get the file ID.
  FileUploadCallbackRequest callbackRequest = new FileUploadCallbackRequest();
  callbackRequest.setFilename(filename);              // Set the filename.
  callbackRequest.setUploadLocation(uploadLocation);  // Set the upload location.
  
  // Send the callback request to get the file ID.
  FileUploadCallbackResponse callbackResponse = client.fileUploadCallback(callbackRequest);
  System.out.println("Upload successful. File ID: " + callbackResponse.getBody().getData().getFileId());

• Delete the uploaded file

  // Delete the uploaded file using its file ID.
  DeleteFileUploadRequest request = new DeleteFileUploadRequest();
  request.setFileId(callbackResponse.getBody().getData().getFileId());
  
  DeleteFileUploadResponse response = client.deleteFileUpload(request);

• The following is a complete Java example that integrates all the preceding steps.

  import com.aliyun.dms20250414.models.*;
  import com.aliyun.teaopenapi.models.Config;
  import okhttp3.*;
  
  import java.io.File;
  import java.io.IOException;
  
  /**
   * Demonstrates the complete process of uploading a file to OSS by using the DMS service.
   * The process includes:
   * 1. Getting upload signature information.
   * 2. Uploading the file to OSS.
   * 3. Sending an upload callback for confirmation.
   */
  public class FileUploadExample {
  
      // Define the local file path and upload configurations.
      private static final String localFilePath = "/Users/******/Downloads/date.csv";  // Local file path
      private static final String filename = "date.csv";                               // Filename
  
      public static void main(String[] args) throws Exception {
          // Configure DMS client parameters.
          Config config = new Config()
                  .setAccessKeyId("********")
                  .setAccessKeySecret("********")
                  .setEndpoint("dms.cn-hangzhou.aliyuncs.com")
                  .setRegionId("cn-hangzhou");
  
          // Create a DMS client instance.
          com.aliyun.dms20250414.Client client = new com.aliyun.dms20250414.Client(config);
  
          // Step 1: Get the file upload signature information.
          // Call the describeFileUploadSignature method to get the signature and configuration information required for the OSS upload.
          DescribeFileUploadSignatureRequest request = new DescribeFileUploadSignatureRequest();
          DescribeFileUploadSignatureResponse response = client.describeFileUploadSignature(request);
          System.out.println(response.getBody().getData());
  
          // Parse the response data to get the required upload configuration information.
          DescribeFileUploadSignatureResponseBody.DescribeFileUploadSignatureResponseBodyData data = response.getBody().getData();
          String uploadLocation = data.getUploadDir() + "/" +  filename;                   // The upload path in OSS
  
          // Step 2: Upload the file to OSS.
          // Use the obtained signature information to upload the file to OSS.
          int code = doUploadFile(data, filename, localFilePath, uploadLocation);
          
          // After a successful upload, send a callback for confirmation.
          if (code == 200) {
              // Step 3: Send a callback for confirmation after a successful upload.
              // Notify the DMS service that the file has been successfully uploaded to get the file ID.
              FileUploadCallbackRequest callbackRequest = new FileUploadCallbackRequest();
              callbackRequest.setFilename(filename);              // Set the filename.
              callbackRequest.setUploadLocation(uploadLocation);  // Set the upload path.
  
              // Send the callback request to get the file ID.
              FileUploadCallbackResponse callbackResponse = client.fileUploadCallback(callbackRequest);
              
              // Print the file ID after a successful upload.
              System.out.println("Upload successful. File ID: " + callbackResponse.getBody().getData().getFileId());
          } else {
              System.out.println("File upload failed. Status code: " + code);
          }
      }
  
      /**
       * Uploads the file to OSS.
       * 
       * This method uses an OkHttp client to upload a file to OSS. It requires parameters such as OSS signature information and file details.
       * 
       * @param data The signature data obtained from the describeFileUploadSignature API.
       * @param filename The name of the file.
       * @param fileLocalPath The local path of the file.
       * @param uploadLocation The upload path in OSS.
       * @return The HTTP response code of the upload. 200 indicates success.
       * @throws IOException If a network or file operation error occurs.
       */
      private static int doUploadFile(DescribeFileUploadSignatureResponseBody.DescribeFileUploadSignatureResponseBodyData data, String filename, String fileLocalPath, String uploadLocation) throws IOException {
          OkHttpClient client = new OkHttpClient();
  
          // Build the multipart form request body, including all parameters required for the OSS upload.
          RequestBody requestBody = new MultipartBody.Builder()
                  .setType(MultipartBody.FORM)
                  .addFormDataPart("success_action_status", "200")                      // You must set success_action_status to 200.
                  .addFormDataPart("policy", data.getPolicy())                          // Signature policy
                  .addFormDataPart("x-oss-signature", data.getOssSignature())           // OSS signature
                  .addFormDataPart("x-oss-signature-version", data.getOssSignatureVersion()) // Signature version
                  .addFormDataPart("x-oss-credential", data.getOssCredential())         // Credential
                  .addFormDataPart("x-oss-date", data.getOssDate())                     // Date
                  .addFormDataPart("key", uploadLocation)                               // Upload path
                  .addFormDataPart("x-oss-security-token", data.getOssSecurityToken())  // Security token
                  .addFormDataPart("file", filename,                                    // File part
                          RequestBody.create(new File(fileLocalPath), MediaType.parse("text/csv"))) // Create the file request body. Set the media type according to the file type.
                  .build();
  
          // Build the POST request.
          Request request = new Request.Builder()
                  .url(data.getUploadHost())  // Use the returned upload host address.
                  .post(requestBody)          // Set the request body.
                  .build();
  
          // Execute the request and handle the response.
          try (Response response = client.newCall(request).execute()) {
              System.out.println("Upload response code: " + response.code());
              System.out.println("Upload response body: " + response.body().string());
              return response.code();
          }
      }
  }

  Important

  When you construct the upload request, make sure to include all form fields obtained from DescribeFileUploadSignature. The file field must be the last part of the multipart/form-data request.

  • Maximum file size: 200 MB.

  • Supported formats: CSV, XLSX, and XLS. Set the correct MediaType based on the file type.