ApsaraVideo VOD:iOS SDK を使用したファイルのアップロード

統合方法

Podfile に次の内容を追加します。

platform :ios, '12.0'
target 'YourApp' do
  pod 'VODUpload', '~> 2.0'
end

次のコマンドを実行します。

pod repo update
pod install

SDK は、基礎となる AliyunOSSiOS 依存関係を自動的にプルします。

プロジェクト設定

podspec は次のシステムライブラリを宣言し、CocoaPods を使用して統合する際に自動的にリンクされます。

SystemConfiguration.framework
MobileCoreServices.framework
CoreMedia.framework
AVFoundation.framework
CoreTelephony.framework
libresolv.tbd

SDK には PrivacyInfo.xcprivacy プライバシーマニフェストが含まれており、pod 統合中に VODUpload.bundle/PrivacyInfo.xcprivacy に自動的にインジェクトされます。追加の設定は不要です。

必要なヘッダーファイルをインポートします。

#import <VODUpload/VODUploadV2Client.h>
#import <VODUpload/VODUploadConfig.h>
#import <VODUpload/VODAuthContext.h>
#import <VODUpload/VODGetAuthCallback.h>
#import <VODUpload/VODUploadOptions.h>
#import <VODUpload/VODUploadResult.h>
#import <VODUpload/VODUploadError.h>
#import <VODUpload/VODVideoMeta.h>
#import <VODUpload/VODImageMeta.h>
#import <VODUpload/VODUploadTask.h>

アップロードインスタンスの初期化

VODUploadConfig はプロパティを使用して直接設定します。+uploaderWithConfig: ファクトリメソッドを呼び出してインスタンスを作成します。

VODUploadConfig *config = [[VODUploadConfig alloc] init];
config.getAuth = getAuth;                  // 必須：認可コールバック。詳細については、「認可コールバックの処理」をご参照ください。

VODUploadV2Client *uploader = [VODUploadV2Client uploaderWithConfig:config];

uploader インスタンスはプロパティとして保持する必要があります。ローカル変数の場合、ARC によって解放され、コールバックが失われる原因となります。同じインスタンスを再利用して、複数のファイルを同時にアップロードできます。ライフサイクルが終了したら、[uploader dispose] を呼び出してリソースを解放します。

ファイルのアップロード

uploadFile:options:callback: を呼び出してアップロードを開始します。このメソッドは、キャンセルに使用できる VODUploadTask ハンドルを返します。

VODVideoMeta *meta = [[VODVideoMeta alloc] init];
meta.title = @"My Video";
meta.tags = @"demo";
meta.cateId = @(1000);

VODUploadOptions *options = [[VODUploadOptions alloc] init];
options.videoMeta = meta;
options.onProgress = ^(float percent, int64_t uploaded, int64_t total) {
    NSLog(@"%.1f%%", percent * 100);
};

VODUploadTask *task = [uploader uploadFile:filePath
                                   options:options
                                  callback:^(VODUploadResult *r, VODUploadError *e) {
    if (e) {
        NSLog(@"%@: %@", e.errorCode, e.errorMessage);
        return;
    }
    NSLog(@"videoId=%@ uploadTaskId=%@ etag=%@ requestId=%@ durationMs=%lld",
          r.videoId, r.uploadTaskId, r.etag, r.requestId, r.durationMs);
}];

// アップロード中にキャンセルします。再開可能なアップロードはデフォルトで有効になっています。同じファイルで次に uploadFile を呼び出すと、アップロードが自動的に再開されます。
[task cancel];
// task.uploadTaskId は、ログの関連付けやトラッキングとの統合に使用できます。

画像のアップロード：SDK は、ファイル拡張子 (jpg、jpeg、png、gif、bmp、webp、heic) に基づいて、または options.imageMeta != nil が明示的に設定されている場合、自動的に画像アップロードプロセスを使用します。成功時のコールバックでは、imageId と imageUrl に値が設定されます。

VODImageMeta *imgMeta = [[VODImageMeta alloc] init];
imgMeta.imageType = @"cover";
imgMeta.title = @"Cover";

VODUploadOptions *opts = [[VODUploadOptions alloc] init];
opts.imageMeta = imgMeta;

[uploader uploadFile:imagePath options:opts callback:cb];

認可コールバックの処理

v2 では、VODGetAuthCallback ブロックがアプリケーションにアップロード認証情報をリクエストします。SDK は特定の時点で getAuth を呼び出し、VODAuthContext.kind を使用して必要な認証情報の種類を示します。

アプリケーションは、バックエンドの OpenAPI 呼び出しから得られた生の JSON レスポンスを直接 completion に渡します。SDK は、OpenAPI レスポンスから次のキーをフィールド名で読み取ります (大文字と小文字は区別されます)。

フィールド名は大文字と小文字を区別します。OpenAPI のレスポンスを直接渡してください。手動でフィールド名を videoId、imageUrl、または image_url に変更すると、SDK はそれらを nil として解析します。

VODGetAuthCallback getAuth = ^(VODAuthContext *ctx,
                               void (^completion)(NSDictionary *result, NSError *error)) {
    switch (ctx.kind) {
        case VODAuthKindCreateVideo:
            [YourBackend createUploadVideo:ctx.fileName
                                  fileSize:ctx.fileSize
                                completion:^(NSDictionary *json, NSError *err) {
                completion(json, err);
            }];
            break;
        case VODAuthKindRefreshVideo:
            [YourBackend refreshUploadVideo:ctx.videoId
                                 completion:^(NSDictionary *json, NSError *err) {
                completion(json, err);
            }];
            break;
        case VODAuthKindCreateImage:
            [YourBackend createUploadImage:ctx.fileName
                                completion:^(NSDictionary *json, NSError *err) {
                completion(json, err);
            }];
            break;
    }
};

アップロードの高速化

VODVideoMeta.userData を次の JSON に設定します。VOD サーバーは、UploadAddress を発行する際に、OSS のグローバル転送アクセラレーションエンドポイント (oss-accelerate.aliyuncs.com) を自動的に返します。その後、SDK は高速化エンドポイントに直接アップロードします。

VODVideoMeta *meta = [[VODVideoMeta alloc] init];
meta.title = @"My Video";
meta.userData = @"{\"Type\":\"oss\",\"Domain\":\"oss-accelerate.aliyuncs.com\"}";

アップロードの高速化は OSS のグローバル転送アクセラレーションに依存します。OSS コンソールでバケットの転送アクセラレーションを有効にする必要があります。詳細については、「転送アクセラレーションを使用した OSS へのアクセス」をご参照ください。

アップロードとトランスコード

VODVideoMeta を使用して、トランスコードテンプレートグループまたはワークフローを指定します。

VODVideoMeta *meta = [[VODVideoMeta alloc] init];
meta.title = @"My Video";
meta.desc = @"Video description";                     // 注：description ではなく desc を使用
meta.coverUrl = @"https://example.com/cover.jpg";
meta.cateId = @(1000);
meta.tags = @"tag1,tag2";
meta.storageLocation = @"<オプション：カスタムストレージリージョン>";
meta.templateGroupId = @"<お使いのテンプレートグループ ID>";    // トランスコードテンプレートグループ
meta.workflowId = @"<お使いのワークフロー ID>";          // ワークフロー (オプション)
meta.appId = @"<オプション：アプリケーション ID>";

VODVideoMeta のサポートされているフィールド：title、desc、coverUrl、cateId、tags、userData、storageLocation、templateGroupId、workflowId、および appId。すべてのフィールドはオプションであり、CreateUploadVideo に渡されます。

アップロードが完了すると、VOD サーバーはテンプレートグループに基づいてソースビデオをトランスコードします。トランスコードをトリガーしたくない場合は、バックエンドから CreateUploadVideo を呼び出す際に「トランスコードなし」のテンプレートグループを渡します。

タイムアウトとリトライ

VODUploadConfig *config = [[VODUploadConfig alloc] init];
config.getAuth = getAuth;
config.timeout = 60;            // 単位：秒。デフォルト値：60
config.maxRetryCount = 2;       // デフォルト値：2

timeout は、単一の OSS リクエストの接続および読み取り/書き込みタイムアウト (NSTimeInterval、秒単位) を制御します。maxRetryCount は、ネットワークエラー発生時の OSS リクエストのリトライ回数を制御します。

署名バージョン

config.signature = @"v4";        // デフォルト値：@"v4"。有効な値：@"v1"

OSS V4 署名は推奨バージョンです。2025 年 9 月 1 日以降、新しく作成されたバケットでは V4 署名が必須となります。既存のお客様も、できるだけ早く移行することを推奨します。アプリケーションで使用するバケットがまだ V1 署名のみをサポートしている場合にのみ、明示的に @"v1" を設定してください。

再開可能なアップロード

再開可能なアップロードはデフォルトで有効になっています。SDK は (lastModified, fileName, fileSize) のタプルを再開可能なアップロードのキーとして使用し、ローカルの Caches ディレクトリに自動的に永続化します。

再開可能なアップロードを無効にするには：

config.checkpoint = NO;

マルチパートアップロード

partSize でパートサイズを、parallel で同時パート数を制御します。

// グローバル設定
config.partSize = 1024 * 1024;     // デフォルト値：1 MB
config.parallel = 4;               // デフォルト値：4

// タスクごとの上書き
VODUploadOptions *options = [[VODUploadOptions alloc] init];
options.videoMeta = meta;
options.partSize = 2 * 1024 * 1024;
options.parallel = 6;

VOD サービスリージョンの設定

config.region = @"cn-shanghai";    // デフォルト値：cn-shanghai

サポートされているリージョンのリストについては、「ApsaraVideo VOD のリージョン ID」をご参照ください。

データ報告

SDK は、製品品質の監視のために、デフォルトでアップロードリンクトラッキングを有効にしています。収集されるのはアップロードプロセスのランタイムメトリクスのみで、ファイルの内容は含まれません。データ報告を無効にするには：

config.reportEnabled = NO;       // デフォルト値：YES

複数の uploadFile 呼び出しを同時に開始できますか？

はい。各 task は独立しています。parallel との組み合わせによる過剰なアップストリーム帯域幅の圧迫を避けるため、ネットワーク状況に基づいて同時アップロード数を制御してください。

キャンセルして再アップロードした後、再開可能なアップロードが機能しません

次の手順で問題をトラブルシューティングしてください。

• ファイルパスが同じかどうかを確認してください。

• ファイルの lastModified またはサイズが変更されていないかを確認してください。

• config.checkpoint が YES に設定されているかを確認してください。

• uploadId が期限切れになっていないかを確認してください。NoSuchUpload レスポンスが受信されると、SDK は自動的に新規アップロードにフォールバックします。これは期待される動作です。

App Store Connect のレビューが "missing privacy manifest" で拒否されました

SDK には PrivacyInfo.xcprivacy ファイルが含まれており、pod 統合中に自動的にインジェクトされます。アプリが使用する Required Reason API もアプリ自身で宣言していることを確認してください。

アップローダーを作成した後、コールバックがトリガーされません

uploader がローカル変数でないことを確認してください。VODUploadV2Client インスタンスは self のプロパティとして保持する必要があります。そうしないと、ARC によって早期に解放されてしまいます。