Cara menggunakan OSS SDK untuk iOS guna melakukan operasi umum - Object Storage Service

Topik ini menjelaskan cara menggunakan OSS SDK untuk iOS guna mengunggah dan mengunduh objek.

Prasyarat

Sebelum memulai, pastikan Anda telah:

Menginstal OSS SDK untuk iOS. Untuk informasi selengkapnya, lihat Instalasi (iOS SDK).

Proyek demo

Proyek demo berikut menunjukkan cara membuat bucket, mengunggah file lokal, dan mengunduh objek:

Untuk menjalankan proyek demo:

Klon proyek demo menggunakan git clone.
Konfigurasikan parameter yang diperlukan:
- Untuk demo AliyunOSSSwift: atur parameter di OSSSwiftGlobalDefines.swift.
- Untuk demo AliyunOSSSDK: atur parameter di OSSTestMacros.h.
Jalankan Security Token Service (STS):
- Jalankan server otentikasi STS lokal dengan menjalankan skrip otentikasi dari direktori sts_local_server, lalu atur parameter AccessKeyId, AccessKeySecret, dan RoleArn.
- Jalankan layanan HTTP lokal menggunakan httpserver.py. Klien kemudian mengambil nilai StsToken.AccessKeyId, StsToken.SecretKey, dan StsToken.SecurityToken dari layanan HTTP lokal ini.

Setelah meluncurkan demo iOS, aplikasi menyediakan titik masuk untuk pemilihan gambar (Select), unggahan bertanda tangan kustom (CustomSign), unggahan (Put), unduhan (Get), pengambilan gambar mini (GetResizeImage), watermark teks (Watermark), dan callback unggahan (triggerCallback).

Kode contoh

Langkah-langkah berikut menunjukkan cara mengunggah dan mengunduh objek di iOS dan macOS.

Impor paket OSS.

Impor file header yang diperlukan sebelum memanggil API OSS apa pun:
```
#import <AliyunOSSiOS/OSSService.h>
```

Inisialisasi instans OSSClient.
1. Pilih mode otentikasi.
  
  OSS SDK untuk iOS mendukung tiga mode otentikasi: teks biasa, self-signed, dan otentikasi STS. Untuk aplikasi seluler, gunakan otentikasi STS—mode ini mengeluarkan kredensial berumur pendek yang membatasi paparan jika kunci dikompromikan dan memungkinkan rotasi tanpa pembaruan aplikasi. Menyematkan ID AccessKey dan rahasia AccessKey secara langsung dalam binari aplikasi berisiko tinggi karena binari tersebut dapat direkayasa balik, serta mencegah rotasi kredensial tanpa rilis baru.
  
  Untuk informasi selengkapnya, lihat Mode otentikasi STS.
  1. Dapatkan kredensial:
    1. Mode teks biasa: lakukan otentikasi menggunakan ID AccessKey dan rahasia AccessKey Anda secara langsung.
    2. Mode self-signed: hasilkan string signature untuk otentikasi. Untuk informasi selengkapnya, lihat Mode self-signed.
    3. Mode otentikasi STS: gunakan kredensial akses sementara yang dikeluarkan oleh Security Token Service (STS). Panggil API AssumeRole atau gunakan STS SDK untuk mendapatkan kredensial sementara. Untuk detailnya, lihat Akses OSS menggunakan kredensial sementara STS.
  2. Gunakan kredensial tersebut untuk menginisialisasi OSS SDK untuk iOS.
2. Kode berikut menginisialisasi instans OSSClient untuk seluruh siklus hidup aplikasi. OSSAuthCredentialProvider secara otomatis memperbarui kredensial STS dari server Anda saat kredensial tersebut kedaluwarsa.
```
@interface AppDelegate ()
@property (nonatomic, strong) OSSClient *client;
@end
/**
 * URL untuk memperoleh informasi STS. Konfigurasikan ini di server Anda sendiri.
 */
#define OSS_STS_URL                 @"oss_sts_url"
/**
 * Titik akhir wilayah tempat bucket berada.
 */
#define OSS_ENDPOINT                @"your bucket's endpoint"
/**
 * Wilayah tempat bucket berada.
 */
#define OSS_REGION                	@"your bucket's region"
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Titik override untuk kustomisasi setelah peluncuran aplikasi.
    // Inisialisasi instans OSSClient.
    [self setupOSSClient];    
    return YES;
}
- (void)setupOSSClient {
    // Inisialisasi penyedia yang secara otomatis memperbarui kredensial.
    id<OSSCredentialProvider> credentialProvider = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:OSS_STS_URL];   
    // Konfigurasi sisi klien, seperti periode timeout dan pre-resolusi DNS.
    OSSClientConfiguration *cfg = [[OSSClientConfiguration alloc] init];
    cfg.signVersion = OSSSignVersionV4;
    client = [[OSSClient alloc] initWithEndpoint:OSS_ENDPOINT credentialProvider:credentialProvider clientConfiguration:cfg];
    client.region = OSS_REGION;
}
```
  Catatan
  Jika aplikasi Anda hanya menggunakan satu bucket di satu wilayah, atur siklus hidup OSSClient agar sesuai dengan siklus hidup aplikasi. Lihat Wilayah dan Titik Akhir.

Buat bucket.

Kode berikut membuat bucket bernama examplebucket:

// Buat permintaan untuk membuat bucket.
OSSCreateBucketRequest * create = [OSSCreateBucketRequest new];
// Atur nama bucket menjadi examplebucket.
create.bucketName = @"examplebucket";
// Atur daftar kontrol akses (ACL) menjadi private.
create.xOssACL = @"private";
// Atur kelas penyimpanan menjadi Infrequent Access (IA).
create.storageClass = OSSBucketStorageClassIA;
OSSTask * createTask = [client createBucket:create];
[createTask continueWithBlock:^id(OSSTask *task) {
    if (!task.error) {
        NSLog(@"create bucket success!");
    } else {
        NSLog(@"create bucket failed, error: %@", task.error);
    }
    return nil;
}];
// Tunggu hingga tugas selesai secara sinkron.
// [createTask waitUntilFinished];

Catatan

Semua operasi SDK mengembalikan objek OSSTask. Tetapkan blok kelanjutan pada OSSTask untuk menangani hasil secara asinkron, atau panggil waitUntilFinished untuk memblokir hingga tugas selesai.

Unggah file lokal.

Kode berikut mengunggah file lokal ke OSS:

Parameter	Deskripsi
`bucketName`	Nama bucket tujuan. Contoh: `examplebucket`.
`objectKey`	Jalur lengkap objek, tidak termasuk nama bucket. Contoh: `exampledir/testdir/exampleobject.txt`.
`uploadingFileURL`	Jalur file lokal sebagai `NSURL`.
`uploadingData`	Alternatif untuk `uploadingFileURL` — teruskan `NSData` secara langsung.
`uploadProgress`	Blok callback yang melaporkan byte terkirim, total byte terkirim, dan total byte yang diharapkan.

OSSPutObjectRequest * put = [OSSPutObjectRequest new];
// Tentukan nama bucket. Contoh: examplebucket. 
put.bucketName = @"examplebucket";
// Tentukan jalur lengkap objek. Jangan sertakan nama bucket. Contoh: exampledir/testdir/exampleobject.txt. 
put.objectKey = @"exampledir/testdir/exampleobject.txt";
put.uploadingFileURL = [NSURL fileURLWithPath:@"<filePath>"];
// Atau, unggah NSData secara langsung. 
// put.uploadingData = <NSData *>;
put.uploadProgress = ^(int64_t bytesSent, int64_t totalByteSent, int64_t totalBytesExpectedToSend) {
    NSLog(@"%lld, %lld, %lld", bytesSent, totalByteSent, totalBytesExpectedToSend);
};
OSSTask * putTask = [client putObject:put];
[putTask continueWithBlock:^id(OSSTask *task) {
    if (!task.error) {
        NSLog(@"upload object success!");
    } else {
        NSLog(@"upload object failed, error: %@" , task.error);
    }
    return nil;
}];
// Tunggu hingga tugas selesai. 
// [putTask waitUntilFinished];

Unduh objek.

Kode berikut mengunduh objek ke perangkat lokal Anda:

Parameter	Deskripsi
`bucketName`	Nama bucket yang berisi objek tersebut. Contoh: `examplebucket`.
`objectKey`	Jalur lengkap objek, tidak termasuk nama bucket. Contoh: `exampledir/testdir/exampleobject.txt`.
`downloadProgress`	Blok callback yang melaporkan byte tertulis, total byte tertulis, dan total byte yang diharapkan.

OSSGetObjectRequest * request = [OSSGetObjectRequest new];
// Tentukan nama bucket. Contoh: examplebucket. 
request.bucketName = @"examplebucket";
// Tentukan jalur lengkap objek. Jangan sertakan nama bucket. Contoh: exampledir/testdir/exampleobject.txt. 
request.objectKey = @"exampledir/testdir/exampleobject.txt";
request.downloadProgress = ^(int64_t bytesWritten, int64_t totalBytesWritten, int64_t totalBytesExpectedToWrite) {
    NSLog(@"%lld, %lld, %lld", bytesWritten, totalBytesWritten, totalBytesExpectedToWrite);
};
OSSTask * getTask = [client getObject:request];
[getTask continueWithBlock:^id(OSSTask *task) {
    if (!task.error) {
        NSLog(@"download object success!");
        OSSGetObjectResult * getResult = task.result;
        NSLog(@"download result: %@", getResult.downloadedData);
    } else {
        NSLog(@"download object failed, error: %@" ,task.error);
    }
    return nil;
}];
// Tunggu hingga tugas selesai. 
// [task waitUntilFinished];