ApsaraVideo VOD：使用Android SDK上傳檔案

前提條件

使用限制

• 目前Android SDK 只支援上傳音、視頻，不支援上傳輔助媒資。

整合SDK

整合方式

在工程根 build.gradle 中加入阿里雲 Maven 倉庫：

allprojects {
    repositories {
        maven { url "https://maven.aliyun.com/nexus/content/repositories/releases" }
    }
}

在模組 build.gradle 中加入 SDK 依賴：

dependencies {
    implementation 'com.aliyun.video.android:upload:<sdk_version>'
}

底層 OSS Android SDK 已由 VODUpload 通過 api 依賴傳遞，無需重複聲明。

專案配置

在 AndroidManifest.xml 中聲明許可權：

<uses-permission android:name="android.permission.INTERNET" />2<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />3<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />4<!-- Android 13+ 媒體細分許可權按需聲明 -->5<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />6<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />

如開啟了代碼混淆，在 proguard-rules.pro 中追加：

-keep class com.alibaba.sdk.android.vod.upload.v2.** { *; }
-keep interface com.alibaba.sdk.android.vod.upload.v2.** { *; }

底層 OSS Android SDK 內建 ProGuard 規則，無需重複聲明。

基礎設定

import com.alibaba.sdk.android.vod.upload.v2.*;23VODUploadConfig config = new VODUploadConfig.Builder()4        .setGetAuth(getAuth)               // 必填：鑒權回調，詳見"回調處理"5        .build();67VODUploadClient uploader = VODUploadClient.create(context, config);

上傳控制

調用 upload(...) 啟動一次上傳，返回 VODUploadTask 控制代碼用於取消：

VODVideoMeta meta = new VODVideoMeta.Builder()
        .setTitle("我的視訊")
        .setTags("demo")
        .setCateId(1000)
        .build();

VODUploadOptions options = new VODUploadOptions.Builder()
        .setVideoMeta(meta)
        .setOnProgress((percent, uploaded, total) ->
                Log.d("Upload", String.format("%.1f%%", percent * 100)))
        .build();

VODUploadTask task = uploader.upload(filePath, options, new VODUploadResultCallback() {
    @Override public void onSuccess(VODUploadResult r) {
        Log.i("Upload",
                "videoId=" + r.getVideoId()
                + " uploadTaskId=" + r.getUploadTaskId()
                + " etag=" + r.getEtag()
                + " requestId=" + r.getRequestId()
                + " durationMs=" + r.getDurationMs());
    }
    @Override public void onFailure(VODUploadError e) {
        Log.e("Upload", e.getErrorCode() + " : " + e.getErrorMessage(), e.getCause());
    }
});

// 中途取消（預設開啟斷點續傳，下次同檔案 upload 自動續傳）
task.cancel();
// task.getUploadTaskId() 可用於關聯日誌、對接埋點

upload(...) 提供兩種重載，支援檔案路徑和 content:// Uri（適配 Android 10+ Scoped Storage）：

uploader.upload(String filePath, VODUploadOptions options, VODUploadResultCallback callback);
uploader.upload(Uri fileUri, VODUploadOptions options, VODUploadResultCallback callback);

圖片上傳：SDK 根據副檔名（jpg / jpeg / png / gif / bmp / webp / heic）或 options.imageMeta != null 自動走圖片鏈路，成功回調中 result.getImageId() 與 result.getImageUrl() 有值：

VODImageMeta imgMeta = new VODImageMeta.Builder()
        .setImageType("cover")
        .setTitle("封面")
        .build();
uploader.upload("/sdcard/cover.jpg",
        new VODUploadOptions.Builder().setImageMeta(imgMeta).build(),
        callback);

回調處理

v2 通過統一的 VODGetAuthCallback 非同步回調向業務方索取上傳憑證。SDK 在以下時機調用 getAuth，並通過 VODAuthContext.getKind() 告知所需憑證類型：

業務方只需把後端 OpenAPI 返回的原始 JSON 原樣回傳給 SDK。SDK 按 OpenAPI 原始欄位名（大小寫敏感）讀取以下鍵：

VODGetAuthCallback getAuth = (ctx, completion) -> {
    switch (ctx.getKind()) {
        case CREATE_VIDEO:
            yourBackend.createUploadVideo(ctx.getFileName(), ctx.getFileSize(),
                json -> completion.onSuccess(json),
                err -> completion.onFailure("BIZ.CREATE_VIDEO", err.getMessage()));
            break;
        case REFRESH_VIDEO:
            yourBackend.refreshUploadVideo(ctx.getVideoId(),
                json -> completion.onSuccess(json),
                err -> completion.onFailure("BIZ.REFRESH_VIDEO", err.getMessage()));
            break;
        case CREATE_IMAGE:
            yourBackend.createUploadImage(ctx.getFileName(),
                json -> completion.onSuccess(json),
                err -> completion.onFailure("BIZ.CREATE_IMAGE", err.getMessage()));
            break;
    }
};

進階設定

VODVideoMeta meta = new VODVideoMeta.Builder()
        .setTitle("我的視訊")
        .setUserData("{\"Type\":\"oss\",\"Domain\":\"oss-accelerate.aliyuncs.com\"}")
        .build();

VODVideoMeta meta = new VODVideoMeta.Builder()
        .setTitle("我的視訊")
        .setDescription("視頻描述")
        .setCoverUrl("https://example.com/cover.jpg")
        .setCateId(1000)
        .setTags("tag1,tag2")
        .setStorageLocation("<可選：自訂儲存地區>")
        .setTemplateGroupId("<你的模板組 ID>")    // 轉碼模板組
        .setWorkflowId("<你的工作流程 ID>")          // 工作流程（可選）
        .setAppId("<可選：應用 ID>")
        .build();

VODUploadConfig config = new VODUploadConfig.Builder()
        .setGetAuth(getAuth)
        .setTimeout(60 * 1000)        // 單位：毫秒，預設 60s
        .setMaxRetryCount(2)          // 預設 2 次
        .build();

VODUploadConfig config = new VODUploadConfig.Builder()
        .setGetAuth(getAuth)
        .setSignature("v4")          // 預設 "v4"，可選 "v1"
        .build();

new VODUploadConfig.Builder().setGetAuth(getAuth).setCheckpoint(false).build();

// 全域配置
VODUploadConfig config = new VODUploadConfig.Builder()
        .setGetAuth(getAuth)
        .setPartSize(1024 * 1024)     // 預設 1MB
        .setParallel(4)               // 預設 4
        .build();

// 單次任務覆蓋
VODUploadOptions options = new VODUploadOptions.Builder()
        .setVideoMeta(meta)
        .setPartSize(2 * 1024 * 1024)
        .setParallel(6)
        .build();

new VODUploadConfig.Builder()
        .setGetAuth(getAuth)
        .setRegion("cn-shanghai")     // 預設 cn-shanghai
        .build();

VODUploadConfig config = new VODUploadConfig.Builder()
        .setGetAuth(getAuth)
        .setReportEnabled(false)     // 預設 true
        .build();

錯誤處理

VODUploadError 繼承自 java.lang.Exception，錯誤碼採用 UPLOAD.{LAYER}.{TYPE} 三段式：

公開方法：

• String getErrorCode() — 錯誤碼。

• String getErrorMessage() — 錯誤資訊。

• String getUploadTaskId() — 上傳任務 ID。

• String getSuggestion() — SDK 內建的修複建議。

• Throwable getCause() — 底層 OSS 異常（繼承自 Exception）。

@Override public void onFailure(VODUploadError e) {
    if (e.getErrorCode().startsWith("UPLOAD.AUTH.")) {
        // 提醒使用者檢查後端鑒權
    } else if (VODUploadError.OSS_UPLOAD_FAILED.equals(e.getErrorCode())) {
        // 重試或提示使用者檢查網路
    }
    Log.e(TAG, e.getErrorCode() + ": " + e.getErrorMessage()
            + " (suggestion=" + e.getSuggestion() + ")", e.getCause());
}

常見問題

能否同時發起多個upload

可以，每個 task 獨立。建議根據網路情況控制並發數，避免與 parallel 疊加放大上行頻寬壓力。

取消後再次upload沒有續傳

請按以下步驟排查：

1. 確認是否同一檔案路徑；

2. 確認檔案 lastModified / size 是否變化；

3. 確認config.checkpoint 是否為 true；

4. 確認uploadId 是否到期（響應 NoSuchUpload 時 SDK 自動 fallback 全新上傳，屬預期行為）。

上傳content://Uri時fileName/fileSize拿到的是什麼

SDK 通過 ContentResolver.query(...) 讀取 OpenableColumns.DISPLAY_NAME 與 OpenableColumns.SIZE。讀不到 size 直接返回 UPLOAD.FILE.EMPTY。

getCause()返回什麼

繼承自 Exception，保留底層 OSS ServerException / ClientException / IOException 等，便於深度排查。