HTTPDNS:Integrasikan SDK untuk iOS

Pendahuluan

Topik ini menjelaskan cara mengintegrasikan SDK HTTPDNS untuk iOS.

• Anda dapat menggunakan CocoaPods untuk mengelola dependensi dalam proyek Anda.

• Versi terbaru SDK mendukung iOS Deployment Target 10.0 dan yang lebih baru.

• SDK dikemas sebagai pustaka statis.

• SDK mendukung arsitektur x86_64 dan arm64 untuk emulator, serta arsitektur arm64 untuk perangkat fisik.

Langkah 1: Tambahkan SDK ke aplikasi Anda

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/aliyun/aliyun-specs.git'

use_framework!

pod 'AlicloudHTTPDNS', 'x.x.x'

pod install --repo-update

1. Impor file header

Impor file header ke file kode yang menggunakan HTTPDNS.

#import <AlicloudHttpDNS/AlicloudHttpDNS.h>

import AlicloudHttpDNS

2. Buat dan konfigurasi instans HTTPDNS

Buat dan konfigurasi instans HTTPDNS global dalam metode -[AppDelegate application:didFinishLaunchingWithOptions:].

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Override point for customization after application launch.

    // Buat instans global menggunakan AccountId yang ditetapkan di Konsol HTTPDNS Alibaba Cloud.
    // Instans hanya perlu diinisialisasi sekali secara global. Dapatkan kunci otentikasi dari konsol dan konfigurasikan secretKey saat inisialisasi.
    HttpDnsService *httpdns = [[HttpDnsService alloc] initWithAccountID:<Your AccountId> secretKey:@"<Your SecretKey>"];

    // Aktifkan logging untuk debugging dan troubleshooting.
    [httpdns setLogEnabled:NO];

    // Tentukan apakah akan menggunakan HTTPS untuk permintaan resolusi nama domain.
    [httpdns setHTTPSRequestEnabled:YES];
    
    // Tetapkan node startup. Pilih node startup berdasarkan skenario Anda.
    [httpdns setRegion:ALICLOUD_HTTPDNS_SINGAPORE_REGION_KEY];
    
    // Aktifkan cache persisten agar aplikasi dapat menggunakan kembali alamat IP yang di-cache secara lokal dari sesi aktif sebelumnya. Ini mempercepat pengambilan hasil resolusi nama domain setelah aplikasi dimulai.
    [httpdns setPersistentCacheIPEnabled:YES];

    // Izinkan penggunaan alamat IP yang telah kedaluwarsa. Anda dapat mengaktifkan fitur ini untuk meningkatkan efisiensi resolusi jika konfigurasi IP nama domain stabil.
    [httpdns setReuseExpiredIPEnabled:YES];

    // Tetapkan periode timeout untuk permintaan jaringan HTTPDNS tingkat dasar. Satuan: detik.
    [httpdns setNetworkingTimeoutInterval:2];

    return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.

    // Buat instans global menggunakan AccountId yang ditetapkan di Konsol HTTPDNS Alibaba Cloud.
    // Instans hanya perlu diinisialisasi sekali secara global. Dapatkan kunci otentikasi dari konsol dan konfigurasikan secretKey saat inisialisasi.
    let httpdns = HttpDnsService(accountID: <Your AccountId>, secretKey: "<Your SecretKey>")

    // Aktifkan logging untuk debugging dan troubleshooting.
    httpdns.setLogEnabled(false)

    // Tentukan apakah akan menggunakan HTTPS untuk permintaan resolusi nama domain.
    httpdns.setHTTPSRequestEnabled(true)
    
    // Tetapkan node layanan startup. Pilih node startup berdasarkan skenario Anda.
    httpdns.setRegion(ALICLOUD_HTTPDNS_SINGAPORE_REGION_KEY)

    // Aktifkan cache persisten agar aplikasi dapat menggunakan kembali alamat IP yang di-cache secara lokal dari sesi aktif sebelumnya. Ini mempercepat pengambilan hasil resolusi nama domain setelah aplikasi dimulai.
    httpdns.setPersistentCacheIPEnabled(true)

    // Izinkan penggunaan alamat IP yang telah kedaluwarsa. Anda dapat mengaktifkan fitur ini untuk meningkatkan efisiensi resolusi jika konfigurasi IP nama domain stabil.
    httpdns.setReuseExpiredIPEnabled(true)

    // Tentukan apakah akan mendukung resolusi alamat IPv6. Hanya ketika sakelar ini diaktifkan, antarmuka resolusi dapat menyelesaikan dan mengembalikan alamat IPv6 nama domain.
    httpdns.setIPv6Enabled(true)

    return true
}

3. Dapatkan instans layanan

SDK HTTPDNS untuk iOS menyediakan layanan resolusi nama domain melalui instans layanan global. Anda dapat mengambil instans tersebut sebagai berikut.

HttpDnsService *httpdns = [HttpDnsService sharedInstance];

let httpdns = HttpDnsService.sharedInstance()

4. Resolve nama domain

HTTPDNS menyediakan beberapa metode resolusi nama domain, seperti pre-resolution, resolusi sinkron, resolusi asinkron, dan resolusi sinkron non-blocking. Contoh berikut menggunakan antarmuka resolusi sinkron non-blocking.

HttpDnsService *httpdns = [HttpDnsService sharedInstance];
HttpdnsResult *result = [httpdns resolveHostSyncNonBlocking:@"www.aliyun.com" byIpType:HttpdnsQueryIPTypeAuto];
if (result) {
    // Gunakan hasil resolusi nama domain.
} else {
    // Antarmuka sinkron non-blocking langsung mengembalikan null jika tidak ditemukan hasil resolusi valid dalam cache untuk memastikan kecepatan resolusi tercepat. Permintaan resolusi baru diinisiasi di latar belakang.
    // Oleh karena itu, Anda harus menyiapkan fallback ke resolusi LocalDNS atau meneruskan nama domain lengkap langsung ke pustaka jaringan.
    // Anda dapat menggunakan antarmuka sinkron atau antarmuka berbasis callback untuk memastikan Anda mendapatkan hasil resolusi HTTPDNS.
}

let httpdns = HttpDnsService.sharedInstance()
if let result = httpdns.resolveHostSyncNonBlocking("www.aliyun.com", by: HttpdnsQueryIPType.auto) {
    // Gunakan hasil resolusi nama domain.
} else {
    // Antarmuka sinkron non-blocking langsung mengembalikan null jika tidak ditemukan hasil resolusi valid dalam cache untuk memastikan kecepatan resolusi tercepat. Permintaan resolusi baru diinisiasi di latar belakang.
    // Oleh karena itu, Anda harus menyiapkan fallback ke resolusi LocalDNS atau meneruskan nama domain lengkap langsung ke pustaka jaringan.
    // Anda dapat menggunakan antarmuka sinkron atau antarmuka berbasis callback untuk memastikan Anda mendapatkan hasil resolusi HTTPDNS.
}

Pilih antarmuka resolusi nama domain berdasarkan skenario bisnis Anda.

5. Gunakan hasil resolusi nama domain

Hasil resolusi nama domain dapat bervariasi tergantung situasinya.

• Hasil kosong. Hal ini dapat terjadi saat Anda menggunakan antarmuka sinkron non-blocking atau saat terjadi pengecualian jaringan.

• Hanya alamat IPv4. Terjadi ketika jaringan on-premises berada dalam lingkungan single-stack IPv4 dan tipe permintaan menentukan IPv4, atau hanya alamat IPv4 yang dikonfigurasi untuk nama domain tersebut.

• Hanya alamat IPv6. Terjadi ketika IPv6 diaktifkan dan resolusi alamat IPv6 ditentukan. Skenario ini jarang terjadi mengingat tingkat adopsi IPv6 saat ini.

• Kedua alamat IPv4 dan IPv6. Terjadi ketika IPv6 diaktifkan dan resolusi alamat dual-stack ditentukan, atau ketika deteksi tipe jaringan otomatis ditentukan dalam lingkungan dual-stack, serta kedua alamat IPv4 dan IPv6 dikonfigurasi untuk nama domain tersebut.

Dalam contoh ini, resolusi IPv6 diaktifkan, dan tipe IP yang diminta diatur ke Both. Jika kedua alamat IPv4 dan IPv6 dikonfigurasi untuk nama domain, hasil resolusi mencakup kedua alamat tersebut. Oleh karena itu, untuk memprioritaskan alamat IPv4, Anda dapat memproses hasil resolusi seperti yang ditunjukkan pada kode berikut.

HttpDnsService *httpdns = [HttpDnsService sharedInstance];
HttpdnsResult *result = [httpdns resolveHostSyncNonBlocking:@"www.aliyun.com" byIpType:HttpdnsQueryIPTypeAuto];
if (!result) {
    // Tidak ada alamat IP valid. Lakukan fallback ke logika default.
}

if (result.hasIpv4Address) {
    NSString *ip = result.firstIpv4Address;
    // Gunakan alamat IP.

    NSArray<NSString *> *ips = result.ips;
    // Gunakan daftar alamat IP.
} else if (result.hasIpv6Address) {
    NSString *ip = result.firstIpv6Address;
    // Gunakan alamat IP.

    NSArray<NSString *> *ips = result.ipv6s;
    // Gunakan daftar alamat IP.
} else {
    // Tidak ada alamat IP valid. Lakukan fallback ke logika default.
}

let httpdns = HttpDnsService.sharedInstance()
if let result = httpdns.resolveHostSyncNonBlocking("www.aliyun.com", by: HttpdnsQueryIPType.auto) {
    if (result.hasIpv4Address()) {
        let ip = result.firstIpv4Address()
        // Gunakan alamat IP.

        let ipList = result.ips
        // Gunakan daftar alamat IP.
    } else if (result.hasIpv6Address()) {
        let ip = result.firstIpv6Address()
        // Gunakan alamat IP.

        let ipList = result.ipv6s
        // Gunakan daftar alamat IP.
    } else {
        // Tidak ada alamat IP valid. Lakukan fallback ke logika default.
    }
} else {
    // Tidak ada alamat IP valid. Lakukan fallback ke logika default.
}

Kode contoh

Untuk proyek contoh yang menunjukkan cara mengintegrasikan SDK HTTPDNS untuk iOS, lihat HTTPDNS iOS Demo.

Catatan

1. Tulis kode fallback

   Kode fallback menangani kasus ketika HTTPDNS gagal mengambil hasil yang diharapkan. Anda biasanya dapat melakukan fallback ke penggunaan LocalDNS untuk resolusi. Artinya, meneruskan nama domain asli ke pustaka jaringan dan membiarkan pustaka tersebut menyelesaikan nama domain menggunakan DNS lokal.

2. Catat alamat IP dan sessionId yang diambil dari HTTPDNS

   Kami menyediakan solusi untuk troubleshooting masalah resolusi. Anda perlu mencatat alamat IP dan sessionId yang diambil dari HTTPDNS dalam log Anda. Untuk informasi selengkapnya, lihat Cara menggunakan solusi pelacakan sesi untuk troubleshooting pengecualian resolusi.

3. Tetapkan bidang HOST di header permintaan HTTP

   Dalam protokol HTTP standar, server mengurai nilai bidang `HOST` di header permintaan HTTP sebagai nama domain yang diminta. Setelah Anda menggunakan HTTPDNS, Anda mungkin perlu mengganti host di URL permintaan dengan alamat IP yang diambil dari HTTPDNS. Pustaka jaringan standar kemudian menetapkan alamat IP ini ke bidang `HOST` di header permintaan HTTP. Hal ini dapat menyebabkan pengecualian penguraian di server karena server mengharapkan nama domain, bukan alamat IP.

   Untuk mengatasi masalah ini, Anda harus menetapkan nilai bidang `HOST` dalam permintaan HTTP. Kode berikut memberikan contoh sederhana:

   Object C

   - (void)sampleRequestUsingHttpdns {
       HttpDnsService *httpdns = [HttpDnsService sharedInstance];
   
       NSString *originalUrlStr = @"http://www.aliyun.com/";
       NSURL* url = [NSURL URLWithString:originalUrlStr];
   
       // Dapatkan alamat IP menggunakan antarmuka sinkron.
       HttpdnsResult* result = [httpdns resolveHostSyncNonBlocking:url.host byIpType:HttpdnsQueryIPTypeAuto];
       NSLog(@"resolve result: %@", result);
       NSString *validIp = nil;
       if (result) {
           if (result.hasIpv4Address) {
               validIp = result.firstIpv4Address;
           }
       }
   
       NSMutableURLRequest *request;
   
       if (validIp) {
           // Alamat IP diperoleh dari HTTPDNS. Ganti URL dan tetapkan header Host.
           NSRange hostFirstRange = [originalUrlStr rangeOfString:url.host];
           NSString* newUrl = [originalUrlStr stringByReplacingCharactersInRange:hostFirstRange withString:validIp];
           request = [[NSMutableURLRequest alloc] initWithURL:[NSURL URLWithString:newUrl]];
           // Tetapkan bidang HOST permintaan.
           [request setValue:url.host forHTTPHeaderField:@"host"];
       } else {
           // Ini menunjukkan cara menangani fallback.
           // Alamat IP tidak dapat diperoleh dari HTTPDNS. Gunakan URL asli untuk membuat permintaan jaringan.
           request = [[NSMutableURLRequest alloc] initWithURL:url];
       }
   
       // Kirim permintaan.
       NSURLSession *session = [NSURLSession sharedSession];
       NSURLSessionDataTask *task = [session dataTaskWithRequest:request completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
           if (error) {
               NSLog(@"error: %@", error);
           } else {
               NSLog(@"response: %@", response);
           }
       }];
       [task resume];
   }

   Swift

   func sampleRequestUsingHttpdns() {
       let httpdns = HttpDnsService.sharedInstance()
       let originalUrlStr = "http://www.aliyun.com/"
       let url = URL(string: originalUrlStr)!
   
       // Dapatkan alamat IP menggunakan antarmuka sinkron.
       let result = httpdns.resolveHostSyncNonBlocking(url.host!, by: HttpdnsQueryIPType.auto)
       print("resolve result: \(result?.description ?? "")")
   
       var validIp: String?
       if let result = result {
           if result.hasIpv4Address() {
               validIp = result.firstIpv4Address()
           }
       }
   
       var request: URLRequest
   
       if let validIp = validIp {
           // Alamat IP diperoleh dari HTTPDNS. Ganti URL dan tetapkan header Host.
           let hostFirstRange = originalUrlStr.firstRange(of: url.host!)!
           let newUrl = originalUrlStr.replacingCharacters(in: hostFirstRange, with: validIp)
           request = URLRequest(url: URL(string: newUrl)!)
           // Tetapkan bidang HOST permintaan.
           request.setValue(url.host!, forHTTPHeaderField: "host")
       } else {
           // Ini menunjukkan cara menangani fallback.
           // Alamat IP tidak dapat diperoleh dari HTTPDNS. Gunakan URL asli untuk membuat permintaan jaringan.
           request = URLRequest(url: url)
       }
   
       // Kirim permintaan.
       let session = URLSession.shared
       let task = session.dataTask(with: request) { (data, response, error) in
           if let error = error {
               print("error: \(error)")
           } else {
               print("response: \(response?.description ?? "")")
           }
       }
       task.resume()
   }

   Penting

   Dalam contoh sederhana ini, perhatikan juga detail berikut:

   • Contoh ini hanya menunjukkan resolusi yang berhasil dan tidak mempertimbangkan logika fallback.

   • Untuk kesederhanaan, contoh ini meminta alamat HTTP. Oleh karena itu, Anda harus mengonfigurasi NSAllowsArbitraryLoads di Info.plist untuk mengizinkan akses.

   • Jika alamat permintaan adalah alamat HTTPS, lihat panduan untuk skenario HTTPS di bagian selanjutnya dokumen ini.

4. Bidang Cookie

   Beberapa pustaka jaringan mendukung penyimpanan dan manajemen cookie otomatis. Saat Anda menggunakan HTTPDNS untuk membuat permintaan ke URL yang berisi alamat IP, beberapa pustaka jaringan mungkin menyimpan alamat IP dari URL sebagai nama domain untuk cookie, bukan nilai bidang `HOST` dari header permintaan HTTP. Hal ini dapat menyebabkan masalah dalam manajemen dan penggunaan cookie. Oleh karena itu, Anda harus menonaktifkan fitur manajemen cookie otomatis. Fitur ini dinonaktifkan secara default.

5. Skema HTTPS, WebView, dan SNI

   Untuk skenario HTTPS, lihat Gunakan HTTPDNS dalam skenario native di iOS.

6. Penggunaan dengan proxy

   Saat terdapat proxy HTTP perantara, baris permintaan dalam permintaan yang diinisiasi klien menggunakan URL jalur mutlak. Jika Anda mengaktifkan HTTPDNS dan menggunakan URL yang berisi alamat IP untuk akses, proxy perantara mengidentifikasi alamat IP tersebut dan meneruskannya ke server tujuan sebagai informasi `HOST` aktual. Server tujuan tidak dapat memproses permintaan HTTP yang tidak memiliki informasi `HOST` asli. Mobile Gateway menyediakan bidang protokol eksklusif X-Online-Host untuk mengatasi masalah ini. Contohnya:

   Destination URL: http://www.aliyun.com/product/oss/
   IP address of www.aliyun.com resolved by HTTPDNS: X.X.X.X
   Proxy: 10.0.0.172:80
   
   Your HTTP request header:
   
   GET http://X.X.X.X/product/oss/ HTTP/1.1     # The request line of an HTTP request initiated through a proxy is an absolute path.
   Host: www.aliyun.com   # This header is ignored by the proxy gateway. The proxy gateway uses the host field in the absolute path of the request line as the host of the origin server, which is X.X.X.X.
   X-Online-Host: www.aliyun.com    # This header is a private header added by Mobile Gateway to transmit the real Host. The origin server needs to be configured to recognize this private header to obtain the real Host information.

   Tetapkan bidang header permintaan X-Online-Host menggunakan metode berikut. Lalu, konfigurasikan server untuk mengurai bidang header eksklusif ini.

   [request setValue:url.host forHTTPHeaderField:@"X-Online-Host"];

   Catatan

   Dalam sebagian besar skenario, Anda dapat memeriksa apakah proxy jaringan diaktifkan pada perangkat saat ini. Jika proxy diaktifkan, jangan gunakan HTTPDNS untuk resolusi nama domain.