ApsaraVideo VOD：Unggah file menggunakan iOS SDK

Integrasikan SDK

Metode integrasi

Konfigurasi proyek

Setelah Anda mengintegrasikan SDK, buka proyek Anda dan ubah konfigurasi sebagai berikut.

1. Di bilah menu, klik Build Setting > Linking > Other Linker Flags.

2. Tambahkan -Objc.

Pengaturan dasar

Inisialisasi instans unggah

Pertama, pahami proses unggah keseluruhan untuk unggahan sisi client. Kemudian, deploy layanan otorisasi berdasarkan metode otorisasi yang Anda pilih:

1. Jika Anda menggunakan upload URL dan credential, peroleh upload URL dan credential dari layanan otorisasi Anda.

2. Jika Anda menggunakan token Security Token Service (STS), peroleh token STS dari layanan otorisasi Anda.

Menginisialisasi instans unggah melibatkan dua langkah: mendeklarasikan callback inisialisasi dan menginisialisasi instans tersebut.

1. Deklarasikan properti VODUploadClient. Properti ini tidak boleh berupa variabel lokal.

2. Inisialisasi instans unggah.

   Metode upload URL dan credential

   Catatan

   • Untuk menggunakan upload URL dan credential, panggil metode init untuk inisialisasi.

   • Jangan atur upload URL dan credential selama inisialisasi. Setelah unggahan dimulai, callback OnUploadStartedListener dipicu. Panggil metode setUploadAuthAndAddress:uploadAuth:uploadAddress: dalam callback ini untuk mengatur URL dan credential.

   • Saat credential kedaluwarsa, callback OnUploadTokenExpiredListener dipicu. Panggil metode resumeWithAuth dan berikan credential unggah baru untuk melanjutkan unggahan.

   Klik untuk melihat kode

   // Buat objek VODUploadClient
   self.uploader = [VODUploadClient new];
   // weakself
   __weak typeof(self) weakSelf = self;
   // Atur callback
   OnUploadFinishedListener FinishCallbackFunc = ^(UploadFileInfo* fileInfo, VodUploadResult* result){
       NSLog(@"Upload finished. Video ID: %@, Image URL: %@", result.videoId, result.imageUrl);
   };
   OnUploadFailedListener FailedCallbackFunc = ^(UploadFileInfo* fileInfo, NSString *code, NSString* message){
       NSLog(@"Upload failed. Error code: %@, Error message: %@", code, message);
   };
   OnUploadProgressListener ProgressCallbackFunc = ^(UploadFileInfo* fileInfo, long uploadedSize, long totalSize) {
       NSLog(@"Upload progress. Uploaded size: %li, Total size: %li", uploadedSize, totalSize);
   };
   OnUploadTokenExpiredListener TokenExpiredCallbackFunc = ^{
       NSLog(@"Upload token expired.");
       // Token telah kedaluwarsa. Atur kredensial unggah baru untuk melanjutkan unggahan.
       [weakSelf.uploader resumeWithAuth:@"new upload auth"];
   };
   OnUploadRertyListener RetryCallbackFunc = ^{
       NSLog(@"Upload retry started.");
   };
   OnUploadRertyResumeListener RetryResumeCallbackFunc = ^{
       NSLog(@"Upload retry finished.");
   };
   OnUploadStartedListener UploadStartedCallbackFunc = ^(UploadFileInfo* fileInfo) {
       NSLog(@"Upload started.");
       // Atur URL unggahan dan kredensial unggah.
       [weakSelf.uploader setUploadAuthAndAddress:fileInfo uploadAuth:@"upload auth" uploadAddress:@"upload address"];
   };
   VODUploadListener *listener = [[VODUploadListener alloc] init];
   listener.finish = FinishCallbackFunc;
   listener.failure = FailedCallbackFunc;
   listener.progress = ProgressCallbackFunc;
   listener.expire = TokenExpiredCallbackFunc;
   listener.retry = RetryCallbackFunc;
   listener.retryResume = RetryResumeCallbackFunc;
   listener.started = UploadStartedCallbackFunc;
   // Inisialisasi pengunggah.
   [self.uploader init:listener];

   Metode token STS

   Catatan

   • Untuk menginisialisasi menggunakan token STS, panggil metode init dan berikan kredensial STS sementara menggunakan metode setKeyId:accessKeySecret:secretToken:expireTime:listener:.

   • Saat token kedaluwarsa, callback OnUploadTokenExpiredListener dipicu. Panggil metode resumeWithToken:accessKeySecret:secretToken:expireTime: dan berikan token STS baru untuk melanjutkan unggahan.

   Klik untuk melihat kode

   // Buat objek VODUploadClient
   self.uploader = [VODUploadClient new];
   // weakself
   __weak typeof(self) weakSelf = self;
   // atur callback
   OnUploadFinishedListener FinishCallbackFunc = ^(UploadFileInfo* fileInfo,  VodUploadResult* result){
       NSLog(@"Unggahan selesai. ID Video: %@, URL Gambar: %@", result.videoId, result.imageUrl);
   };
   OnUploadFailedListener FailedCallbackFunc = ^(UploadFileInfo* fileInfo, NSString *code, NSString* message){
       NSLog(@"Unggahan gagal. Kode kesalahan: %@, Pesan kesalahan: %@", code, message);
   };
   OnUploadProgressListener ProgressCallbackFunc = ^(UploadFileInfo* fileInfo, long uploadedSize, long totalSize) {
       NSLog(@"Kemajuan unggahan. Ukuran terunggah: %li, Ukuran total: %li", uploadedSize, totalSize);
   };
   OnUploadTokenExpiredListener TokenExpiredCallbackFunc = ^{
       NSLog(@"Token unggahan kedaluwarsa.");
       // Token kedaluwarsa. Atur token STS baru untuk melanjutkan unggahan.
       [weakSelf.uploader resumeWithToken:@"STS Key Id" accessKeySecret:@"STS Key Secret" secretToken:@"STS Secret Token" expireTime:@"STS Expire Time"];
   };
   OnUploadRertyListener RetryCallbackFunc = ^{
       NSLog(@"Percobaan ulang unggahan dimulai.");
   };
   OnUploadRertyResumeListener RetryResumeCallbackFunc = ^{
       NSLog(@"Percobaan ulang unggahan selesai.");
   };
   OnUploadStartedListener UploadStartedCallbackFunc = ^(UploadFileInfo* fileInfo) {
       NSLog(@"Unggahan dimulai.");
   };
   // Inisialisasi
   VODUploadListener *listener = [[VODUploadListener alloc] init];
   listener.finish = FinishCallbackFunc;
   listener.failure = FailedCallbackFunc;
   listener.progress = ProgressCallbackFunc;
   listener.expire = TokenExpiredCallbackFunc;
   listener.retry = RetryCallbackFunc;
   listener.retryResume = RetryResumeCallbackFunc;
   listener.started = UploadStartedCallbackFunc;
   // Atur token STS dan listener.
   [self.uploader setKeyId:@"STS Key Id" accessKeySecret:@"STS Key Secret" secretToken:@"STS Secret Token" expireTime:@"STS Expire Time" listener:listener];

3. Atur callback untuk menerima pesan tentang event penting selama proses unggahan.

   Atur objek VODUploadListener. Objek ini merupakan kelas callback untuk status unggahan. Anda perlu mengatur metode callback berikut:

   Klik untuk melihat kode

   /**
    Callback untuk unggahan berhasil.
    @param fileInfo Informasi tentang file yang diunggah.
    @param result Hasil unggahan.
    */
   typedef void (^OnUploadFinishedListener) (UploadFileInfo* fileInfo, VodUploadResult* result);
   /**
    Callback untuk unggahan gagal.
    @param fileInfo Informasi tentang file yang diunggah.
    @param code Kode kesalahan.
    @param message Pesan kesalahan.
    */
   typedef void (^OnUploadFailedListener) (UploadFileInfo* fileInfo, NSString *code, NSString * message);
   /**
    Callback untuk kemajuan unggahan.
    @param fileInfo Informasi tentang file yang diunggah.
    @param uploadedSize Ukuran bagian yang telah diunggah.
    @param totalSize Ukuran total file.
    */
   typedef void (^OnUploadProgressListener) (UploadFileInfo* fileInfo, long uploadedSize, long totalSize);
   /**
    Callback untuk token yang kedaluwarsa.
    Jika Anda menggunakan upload URL dan credential, panggil metode resumeWithAuth: untuk melanjutkan unggahan.
    Jika Anda menggunakan token STS, panggil metode resumeWithToken:accessKeySecret:secretToken:expireTime: untuk melanjutkan unggahan.
    */
   typedef void (^OnUploadTokenExpiredListener) ();
   /**
    Callback untuk awal percobaan ulang unggahan.
    */
   typedef void (^OnUploadRertyListener) ();
   /**
    Callback untuk akhir percobaan ulang unggahan. Unggahan dilanjutkan.
    */
   typedef void (^OnUploadRertyResumeListener) ();
   /**
    Callback untuk awal unggahan.
    Jika Anda menggunakan upload URL dan credential, panggil metode setUploadAuthAndAddress:uploadAuth:uploadAddress: untuk mengatur upload URL dan credential.
    @param fileInfo Informasi tentang file yang diunggah.
    */
   typedef void (^OnUploadStartedListener) (UploadFileInfo* fileInfo);

4. Bangun parameter unggahan berdasarkan jenis file, seperti audio, video, atau gambar.

   Catatan

   Parameter unggahan untuk file audio atau video dan file gambar sedikit berbeda. Client tidak mendukung unggahan aset media pendukung.

   Parameter file audio dan video

   Buat fungsi permintaan unggahan untuk menambahkan file audio atau video ke daftar unggahan.

   Klik untuk melihat kode

   NSString *filePath = [[NSBundle mainBundle] pathForResource:@"video_source_file_name" ofType:@"video_source_file_format_such_as_mp4"];
   VodInfo *vodInfo = [[VodInfo alloc] init];
   vodInfo.title = @"video_name_after_upload";
   vodInfo.desc = @"video_description_after_upload";
   vodInfo.cateId = @(video_category_id);
   vodInfo.tags = @"video_tags_such_as_sports";
   [self.uploader addFile:filePath vodInfo:vodInfo];

   Deskripsi VodInfo

   Klik untuk melihat kode

   // Judul
   @property (nonatomic, copy) NSString* title;
   // Tag
   @property (nonatomic, copy) NSString* tags;
   // Deskripsi
   @property (nonatomic, copy) NSString* desc;
   // ID kategori
   @property (nonatomic, strong) NSNumber* cateId;
   // URL thumbnail (URL lengkap yang dimulai dengan https://)
   @property (nonatomic, copy) NSString* coverUrl;

   Setelah Anda menambahkan file, SDK membungkus file tersebut menjadi objek UploadFileInfo. Strukturnya sebagai berikut:

   Klik untuk melihat kode

   // Jalur lokal file
   @property (nonatomic, copy) NSString* filePath;
   // Titik akhir
   @property (nonatomic, copy) NSString* endpoint;
   // Bucket
   @property (nonatomic, copy) NSString* bucket;
   // Objek
   @property (nonatomic, copy) NSString* object;
   // VodInfo
   @property (nonatomic, strong) VodInfo* vodInfo;

   Catatan

   Untuk mengunggah video dari album foto, gunakan jalur mutlak video yang dipilih sebagai jalur file untuk unggahan.

   Parameter file gambar

   Klik untuk melihat kode

   NSString *filePath = [[NSBundle mainBundle] pathForResource:@"image_source_file_name" ofType:@"image_source_file_format_such_as_jpg"];
   VodInfo *imageInfo = [[VodInfo alloc] init];
   imageInfo.title = @"image_name_after_upload";
   imageInfo.desc = @"image_description_after_upload";
   imageInfo.cateId = @(image_category_id);
   imageInfo.tags = @"image_tags_such_as_sports";
   [self.uploader addFile:filePath vodInfo:imageInfo];

5. Mulai unggahan.

   1. Panggil start untuk memulai unggahan.

      [self.uploader start];

      Setelah metode ini dipanggil, callback OnUploadStartedListener dipicu. Jika Anda menggunakan upload URL dan credential, Anda harus mengatur upload URL dan credential dalam metode callback ini. Contoh kodenya sebagai berikut:

      [weakSelf.uploader setUploadAuthAndAddress:fileInfo uploadAuth:weakSelf.uploadAuth uploadAddress:weakSelf.uploadAddress];

   2. Setelah file mulai diunggah, callback OnUploadProgressListener mulai menyinkronkan kemajuan unggahan.

      Parameter callback mencakup ukuran bagian yang telah diunggah (uploadedSize) dan ukuran total file (totalSize).

   3. Setelah file berhasil diunggah, callback OnUploadFinishedListener mengembalikan informasi file yang diunggah (UploadFileInfo) dan hasil unggahan (VodUploadResult).

      Objek VodUploadResult berisi properti berikut:

      @property (nonatomic, copy) NSString* videoId;
      @property (nonatomic, copy) NSString* imageUrl;

      Catatan

      Properti videoId hanya dikembalikan setelah video berhasil diunggah menggunakan token STS. Properti imageUrl hanya dikembalikan setelah gambar berhasil diunggah menggunakan token STS. Jika Anda menggunakan upload URL dan credential, videoId dan imageUrl tidak dikembalikan. Anda dapat memperoleh nilai-nilai ini saat meminta upload URL dan credential.

Hasil eksekusi

• Setelah video diunggah, videoId dikembalikan. Gunakan videoId ini untuk memperoleh URL pemutaran. Untuk informasi lebih lanjut, lihat Peroleh URL pemutaran.

• Setelah gambar diunggah, imageUrl dikembalikan. Jika Anda mengaktifkan penandatanganan URL, imageUrl memiliki waktu hidup (TTL). Untuk informasi lebih lanjut, lihat Konfigurasikan penandatanganan URL.

Manajemen antrian

VODUploadClient mendukung penambahan beberapa file untuk unggahan berurutan dan menyediakan metode berikut untuk mengelola antrian unggahan:

• Hapus file dari antrian unggahan. Jika file sedang diunggah, unggahan dibatalkan, dan file berikutnya dalam antrian mulai diunggah secara otomatis.

  - (BOOL)deleteFile:(int) index;

• Bersihkan antrian unggahan. Jika file sedang diunggah, unggahan dibatalkan.

  - (BOOL)clearFiles;

• Peroleh daftar file dalam antrian unggahan.

  - (NSMutableArray<UploadFileInfo *> *)listFiles;

• Tandai file sebagai dibatalkan. File tetap berada dalam daftar unggahan. Jika file sedang diunggah, unggahan dibatalkan, dan file berikutnya dalam antrian mulai diunggah secara otomatis.

  - (BOOL)cancelFile:(int)index;

• Lanjutkan unggahan file yang dibatalkan. Unggahan dimulai secara otomatis.

  - (BOOL)resumeFile:(int)index;

Kontrol unggahan

• Hentikan unggahan. Jika file sedang diunggah, unggahan dibatalkan.

  - (BOOL)stop;

  Catatan

  Setelah Anda menghentikan unggahan, Anda dapat memanggil resumeFile untuk melanjutkan unggahan file tersebut, atau membersihkan antrian dan menambahkan kembali file tersebut untuk memulai ulang unggahan.

• Jeda unggahan.

  - (BOOL)pause;

• Lanjutkan unggahan.

  - (BOOL)resume;

Penanganan callback

• Kegagalan unggahan

  Jika unggahan gagal, callback OnUploadFailedListener dipicu. Dalam metode callback ini, Anda dapat melihat penyebab kegagalan dari parameter code dan message serta menampilkan notifikasi di halaman. Untuk informasi lebih lanjut tentang kode kesalahan, lihat Kode kesalahan dan Kode kesalahan OSS.

• Penanganan credential kedaluwarsa

  Jika credential unggahan atau token STS kedaluwarsa, callback OnUploadTokenExpiredListener dipicu. Dalam metode callback ini, mintalah credential unggahan baru atau token STS dari server aplikasi Anda dan panggil salah satu metode berikut untuk melanjutkan unggahan.

  • Atur ulang credential unggahan

    - (BOOL)resumeWithAuth:(NSString *)uploadAuth;

  • Atur ulang token STS

    - (BOOL)resumeWithToken:(NSString *)accessKeyId
            accessKeySecret:(NSString *)accessKeySecret
                secretToken:(NSString *)secretToken
                 expireTime:(NSString *)expireTime;

• Penanganan timeout

  Jika unggahan mengalami timeout, callback OnUploadRertyListener dipicu, dan unggahan secara otomatis dicoba ulang. Dalam metode callback ini, Anda dapat menampilkan notifikasi di halaman atau memanggil metode stop untuk menghentikan unggahan. Anda juga dapat mengatur properti maxRetryCount untuk menentukan jumlah maksimum percobaan ulang. Jika unggahan dapat dilanjutkan setelah percobaan ulang timeout, callback OnUploadRertyResumeListener dipicu, dan unggahan dilanjutkan.

Pengaturan lanjutan

VODUploadClient mendukung pengaturan lanjutan, seperti akselerasi unggahan, transkoding unggahan, percobaan ulang timeout, pengaturan lokasi folder cache, unggahan yang dapat dilanjutkan, unggahan multi-bagian, dan pengaturan wilayah layanan VOD. Bagian berikut memberikan contoh.

Akselerasi unggahan

Saat Anda perlu mengunggah file besar (dalam satuan gigabyte atau terabyte) atau melakukan unggahan cross-region, seperti mengunggah video dari Tiongkok daratan ke alamat penyimpanan di wilayah penyimpanan Singapura, Anda dapat mengaktifkan fitur akselerasi unggahan. Untuk informasi lebih lanjut, lihat cara mengaktifkan fitur tersebut. Setelah Anda mengaktifkan fitur tersebut, Anda harus menambahkan pasangan key-value yang diperlukan ke string UserData dalam konfigurasi vodInfo pada instans unggahan. String ini harus dalam format JSON. Contoh konfigurasinya sebagai berikut:

/** 
 Atur data kustom di VodInfo. 
*/
@property (nonatomic, copy) NSString *UserData;
vodInfo.UserData = "{\"Type\":\"oss\",\"Domain\":\"oss-accelerate.aliyuncs.com\"}";

Deskripsi parameter

Transkoding unggahan

/**
 Menentukan apakah file akan ditranskode di server setelah diunggah. Nilai default adalah YES. Untuk menentukan format output untuk transkoding video, lihat Transkoding video.
 */
@property (nonatomic, assign) BOOL transcode;

Timeout dan percobaan ulang

/**
 Jumlah maksimum percobaan ulang. Nilai default adalah INT_MAX.
 */
@property (nonatomic, assign) uint32_t maxRetryCount;
/**
 Periode timeout.
 */
@property (nonatomic, assign) NSTimeInterval timeoutIntervalForRequest;

Atur lokasi folder cache

/**
 Lokasi folder cache.
 */
@property (nonatomic, copy) NSString * recordDirectoryPath;

Unggahan yang dapat dilanjutkan

/**
 Menentukan apakah kemajuan unggahan direkam untuk unggahan yang dapat dilanjutkan. Nilai default adalah YES.
 */
@property (nonatomic, assign) BOOL recordUploadProgress;

Unggahan multi-bagian

/**
 Ukuran bagian. Nilai default adalah 1024 * 1024.
*/
@property (nonatomic, assign) NSInteger uploadPartSize;

Atur wilayah layanan VOD

/**
 Wilayah VOD. Nilai default adalah "cn-shanghai".
 */
@property (nonatomic, copy) NSString *region;