Alibaba Cloud DNS:Panduan pengembangan iOS SDK

Ikhtisar

iOS SDK ini mengenkapsulasi DoH JSON API untuk HTTPDNS. SDK ini menyediakan fungsi resolusi nama domain untuk aplikasi iOS serta fitur caching nama domain yang efisien berdasarkan kebijakan Time-to-Live (TTL) dan Least Recently Used (LRU). Dengan SDK ini, Anda dapat dengan mudah mengintegrasikan HTTPDNS ke dalam aplikasi iOS Anda guna mengatasi pengecualian resolusi nama domain dan menerapkan penjadwalan resolusi nama domain yang akurat dan berbiaya rendah.

Mulai dari iOS 14, sistem secara native mendukung dua protokol DNS terenkripsi standar: DNS over TLS (DoT) dan DNS over HTTPS (DoH). Untuk informasi lebih lanjut tentang cara menetapkan HTTPDNS sebagai resolver DNS terenkripsi default, lihat Solusi DNS terenkripsi native iOS 14.

SDK ini memiliki keunggulan berikut:

• Sederhana dan mudah digunakan

  Integrasikan SDK untuk mengakses layanan HTTPDNS. Metode integrasinya sederhana dan menyediakan layanan resolusi yang nyaman.

• Latensi nol

  SDK menerapkan mekanisme caching LRU internal untuk menyimpan cache alamat IP dari hasil resolusi nama domain secara lokal. SDK juga secara aktif memperbarui entri cache yang telah kedaluwarsa guna memastikan data cache tetap mutakhir dan efektif. Hal ini membantu Anda mencapai resolusi nama domain dengan latensi nol.

Untuk informasi lebih lanjut tentang cara menggunakan SDK ini dalam proyek Objective-C, lihat kode sumber proyek contoh alidns_ios_demo.

Untuk informasi lebih lanjut tentang cara menggunakan SDK ini dalam proyek Swift, lihat kode sumber proyek contoh DNSResolverSwiftDemo.

Integrasi SDK

Impor SDK

Inisialisasi SDK

Pertama, daftarkan aplikasi Anda di Konsol untuk mendapatkan identifier unik dan parameter otentikasi. Kemudian, inisialisasi SDK setelah integrasi.

Inisialisasi SDK di application:didFinishLaunchingWithOptions:.

DNSResolver *resolver = [DNSResolver share];
//setAccountId:@"******": Ganti konten tanda bintang dengan Account ID dari halaman Konfigurasi Akses di Konsol.
//andAccessKeyId:@"********": Ganti konten tanda bintang dengan ID AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
//andAccesskeySecret:@"********": Ganti konten tanda bintang dengan Rahasia AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
[resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
// Tentukan domain untuk pembaruan cache kedaluwarsa otomatis. Array dibatasi maksimal 10 nama domain.
[resolver setKeepAliveDomains:@[@"user_specified_domain_1",@"user_specified_domain_2"]];
// Pra-muat domain yang mungkin perlu di-resolve nanti.
[resolver preloadDomains:@[@"domain1", @"domain2", @"domain3"] complete:^{
// Semua domain telah dipra-muat.
}];

Pengenalan API

Pengaturan umum

1. ID Akun dan otentikasi

Ini adalah parameter yang diperlukan. Setelah Anda mendaftarkan aplikasi di Konsol, Konsol akan menghasilkan Account ID unik untuk aplikasi tersebut. Fitur otentikasi memastikan keamanan identitas pengguna dan mencegah penggunaan tidak sah oleh pihak ketiga. Untuk informasi lebih lanjut, lihat Buat Pasangan AccessKey untuk membuat AccessKey di Konsol. Atur di aplikasi menggunakan kode berikut:

//setAccountId:@"******": Ganti konten tanda bintang dengan Account ID dari halaman Konfigurasi Akses di Konsol.
//andAccessKeyId:@"********": Ganti konten tanda bintang dengan ID AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
//andAccesskeySecret:@"********": Ganti konten tanda bintang dengan Rahasia AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
[[DNSResolver share] setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];

2. Pengaturan protokol resolusi

SDK memungkinkan Anda menetapkan protokol untuk permintaan resolusi DNS. Anda dapat memilih untuk melakukan resolusi melalui HTTP atau HTTPS dengan mengatur properti scheme.

Secara default, SDK menggunakan dan merekomendasikan protokol HTTPS untuk resolusi karena HTTPS memberikan keamanan yang lebih baik. HTTPDNS ditagih berdasarkan jumlah permintaan resolusi HTTP. Permintaan resolusi HTTPS ditagih lima kali lipat dari tarif permintaan resolusi HTTP. Pilih jenis skema sesuai kebutuhan. Atur properti sebagai berikut:

[DNSResolver share].scheme = DNSResolverSchemeHttps;

3. Aktifkan atau nonaktifkan caching

Anda dapat mengaktifkan fitur caching di SDK. Jika caching diaktifkan, setelah nama domain di-resolve untuk pertama kalinya, resolusi berikutnya akan memprioritaskan pengambilan data dari cache. Hal ini dapat sangat meningkatkan kecepatan resolusi.

SDK mengaktifkan caching secara default. Untuk menonaktifkan caching, gunakan kode berikut:

[DNSResolver share].cacheEnable=NO;

4. Atur cache keep-alive untuk domain

Saat caching diaktifkan, Anda dapat mengaktifkan fitur cache keep-alive untuk domain tertentu. Jika fitur ini diaktifkan, SDK secara otomatis memperbarui cache yang telah kedaluwarsa untuk domain-domain tersebut guna memastikan data cache tetap mutakhir. Namun, hal ini dapat meningkatkan jumlah resolusi nama domain dan konsumsi traffic klien. Jika fitur ini tidak diaktifkan, SDK tidak akan memperbarui cache kedaluwarsa secara otomatis. Cache hanya diperbarui saat Anda memanggil metode resolusi. Untuk mengatur cache keep-alive untuk domain tertentu, gunakan kode berikut:

// Array dibatasi maksimal 10 nama domain.
[[DNSResolver share] setKeepAliveDomains:@[@"www.taobao.com",@"www.aliyun.com"]];

5. Pra-resolusi

Karena fitur caching SDK dapat diaktifkan, kecepatan resolusi untuk suatu domain dapat dikurangi hingga latensi nol pada permintaan berikutnya setelah resolusi awal menghasilkan entri cache. Untuk performa terbaik, pra-resolve domain yang mungkin perlu di-resolve oleh aplikasi Anda setelah aplikasi dimulai.

Contoh kode:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   // Titik override untuk kustomisasi setelah peluncuran aplikasi.
   
   DNSResolver *resolver = [DNSResolver share];
   //setAccountId:@"******": Ganti konten tanda bintang dengan Account ID dari halaman Konfigurasi Akses di Konsol.
   //andAccessKeyId:@"********": Ganti konten tanda bintang dengan ID AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
   //andAccesskeySecret:@"********": Ganti konten tanda bintang dengan Rahasia AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
   [resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
   resolver.cacheEnable = YES;
   // Pra-muat domain yang mungkin perlu di-resolve nanti.
   [resolver preloadDomains:@[@"domain1", @"domain2", @"domain3"] complete:^{
       // Semua domain telah dipra-muat.
       
   }];
   
   return YES;
}

Pengaturan lanjutan

1. Gunakan alamat IPv6 server-side

Layanan HTTPDNS mendukung akses dual-stack IPv4 dan IPv6. Secara default, SDK menggunakan alamat IPv4 untuk mengakses server DNS guna melakukan resolusi.

Untuk mengakses server DNS melalui alamat IPv6, jaringan saat ini harus mendukung IPv6. Gunakan kode berikut untuk mengaktifkan fitur ini:

[DNSResolver share].ipv6Enable = YES;

2. Mode singkat

DoH JSON API HTTPDNS mengembalikan data dalam format JSON lengkap atau format array alamat IP singkat. Secara default, SDK menggunakan format JSON lengkap.

Untuk menggunakan format array alamat IP singkat, gunakan kode berikut:

[DNSResolver share].shortEnable = YES;

3. Atur ukuran cache

Jika caching diaktifkan di SDK, Anda dapat menyesuaikan jumlah entri cache. Rentang yang didukung adalah 100 hingga 500.

Ukuran cache default adalah 100 nama domain. Untuk menyesuaikan ukuran cache, atur properti cacheCountLimit:

[DNSResolver share].cacheCountLimit = 200;

4. Konfigurasi pengaktifan uji kecepatan IP

Anda dapat mengaktifkan probing alamat IP di SDK. Jika probing alamat IP diaktifkan, hasil resolusi akan memprioritaskan alamat IP tercepat. Array alamat IP diurutkan dari tercepat ke terlambat berdasarkan hasil probing.

SDK tidak mengaktifkan pengujian kecepatan IP secara default. Untuk mengaktifkan pengujian kecepatan IP, gunakan kode berikut:

[DNSResolver share].speedTestEnable=YES;

5. Atur metode probing alamat IP

SDK dapat mengatur metode untuk pengujian kecepatan IP. Jika pengujian kecepatan IP diaktifkan dan parameter ini diatur ke 0, deteksi ICMP akan digunakan. Jika parameter ini diatur ke 80, 443, atau nomor port yang didukung lainnya, deteksi port spesifik socket akan digunakan.

Nilai default untuk parameter ini adalah 443.

[DNSResolver share].speedPort = 80;

6. Konfigurasi caching nama domain berbasis ISP

Anda dapat menggunakan SDK untuk mengaktifkan caching nama domain berdasarkan jaringan ISP. Jika diaktifkan, hasil resolusi nama domain yang dicache disimpan secara terpisah di lingkungan jaringan berbeda tanpa saling memengaruhi. Jika tidak diaktifkan, hasil resolusi nama domain yang sama digunakan di semua jaringan.

Secara default, SDK mengaktifkan diferensiasi cache nama domain berdasarkan jaringan ISP.

[DNSResolver share].ispEnable = YES;

7. Atur TTL maksimum untuk cache negatif

SDK dapat mengatur TTL maksimum untuk cache negatif (cache untuk pencarian nama domain yang gagal dan tidak mengembalikan alamat IP). Jika nilai ini diatur, TTL maksimum cache negatif tidak akan melebihi durasi yang ditentukan.

Nilai default parameter ini di SDK adalah 30 detik. Untuk mengatur TTL maksimum untuk cache negatif, gunakan kode berikut:

[DNSResolver share].maxNegativeCache = 30;

8. Atur TTL cache maksimum

Anda dapat menggunakan SDK untuk mengatur TTL maksimum untuk cache guna memastikan TTL data cache tidak melebihi batas ini.

Secara default, SDK mengatur parameter ini menjadi 3.600 detik. Untuk mengatur TTL cache maksimum, gunakan kode berikut:

[DNSResolver share].maxCacheTTL= 3600;

9. Atur apakah akan mengaktifkan cache immutable

[DNSResolver share].immutableCacheEnable = NO;// Cache immutable dinonaktifkan secara default dan tidak pernah kedaluwarsa

10. Timeout

Properti timeout menentukan timeout untuk resolusi nama domain. Timeout default adalah 3 detik. Pengguna dapat menyesuaikan timeout, dan disarankan mengaturnya antara 2 hingga 5 detik.

API Layanan

Contoh kode:

/// Pra-resolve informasi domain. Ini dapat dipanggil saat program dimulai. Hasil resolusi disimpan dalam cache untuk mempercepat resolusi nama domain berikutnya.
/// Secara otomatis mendeteksi lingkungan jaringan (IPv4-only, IPv6-only, atau dual-stack) untuk meng-resolve alamat IP yang sesuai dengan jaringan saat ini.
/// @param domainArray  Array nama domain.
/// @param complete     Callback setelah resolusi selesai.
- (void)preloadDomains:(NSArray<NSString *> *)domainArray complete:(void(^)(void))complete;

/// Mendapatkan array alamat IP setelah resolusi nama domain. Secara otomatis mendeteksi lingkungan jaringan (IPv4-only, IPv6-only, atau dual-stack) untuk mendapatkan alamat IP yang sesuai dengan jaringan saat ini.
/// Jika caching diaktifkan, memprioritaskan pengembalian data dari cache. Jika tidak ada cache atau cache telah kedaluwarsa, mendapatkan alamat IP yang sesuai melalui permintaan jaringan. Jika caching tidak diaktifkan, langsung mendapatkan alamat IP yang sesuai melalui permintaan jaringan.
/// @param domain           Nama domain.
/// @param complete       Callback (semua alamat IP).
- (void)getIpsDataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

/// Secara otomatis mendeteksi lingkungan jaringan (IPv4-only, IPv6-only, atau dual-stack) untuk langsung mendapatkan array alamat IP yang sesuai dengan jaringan saat ini dari cache, tanpa menunggu.  
/// Jika tidak ada cache, mengembalikan nil. Jika ada cache dan enable diatur ke YES, mengembalikan data cache dan secara asinkron meng-resolve nama domain untuk memperbarui cache jika data telah kedaluwarsa. Jika ada cache dan enable diatur ke NO, mengembalikan nil saat cache telah kedaluwarsa dan secara asinkron meng-resolve nama domain untuk memperbarui cache.
/// @param domain   Nama domain.
/// @param enable   Menentukan apakah boleh mengembalikan alamat IP kedaluwarsa.
- (NSArray<NSString *> *)getIpsByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

/// Mendapatkan array informasi IPv4 setelah resolusi nama domain.
/// Jika caching diaktifkan, memprioritaskan pengembalian data dari cache. Jika tidak ada cache atau cache telah kedaluwarsa, mendapatkan alamat IP yang sesuai melalui permintaan jaringan. Jika caching tidak diaktifkan, langsung mendapatkan alamat IP yang sesuai melalui permintaan jaringan.
/// @param domain           Nama domain.
/// @param complete       Callback (semua informasi domain).
- (void)getIpv4InfoWithDomain:(NSString *)domain complete:(void(^)(NSArray<DNSDomainInfo *> *domainInfoArray))complete;

/// Mendapatkan array informasi IPv6 setelah resolusi nama domain.
/// Jika caching diaktifkan, memprioritaskan pengembalian data dari cache. Jika tidak ada cache atau cache telah kedaluwarsa, mendapatkan alamat IP yang sesuai melalui permintaan jaringan. Jika caching tidak diaktifkan, langsung mendapatkan alamat IP yang sesuai melalui permintaan jaringan.
/// @param domain           Nama domain.
/// @param complete       Callback (semua informasi domain).
- (void)getIpv6InfoWithDomain:(NSString *)domain complete:(void(^)(NSArray<DNSDomainInfo *> *domainInfoArray))complete;

/// Mendapatkan informasi IPv4 setelah resolusi nama domain.
/// Jika caching diaktifkan, memprioritaskan pengembalian data dari cache. Jika tidak ada cache atau cache telah kedaluwarsa, mendapatkan alamat IP yang sesuai melalui permintaan jaringan. Jika caching tidak diaktifkan, langsung mendapatkan alamat IP yang sesuai melalui permintaan jaringan.
/// @param domain           Nama domain.
/// @param complete       Callback (entri acak dari semua informasi domain).
- (void)getRandomIpv4InfoWithDomain:(NSString *)domain complete:(void(^)(DNSDomainInfo *domainInfo))complete;

/// Mendapatkan informasi IPv6 setelah resolusi nama domain.
/// Jika caching diaktifkan, memprioritaskan pengembalian data dari cache. Jika tidak ada cache atau cache telah kedaluwarsa, mendapatkan alamat IP yang sesuai melalui permintaan jaringan. Jika caching tidak diaktifkan, langsung mendapatkan alamat IP yang sesuai melalui permintaan jaringan.
/// @param domain           Nama domain.
/// @param complete       Callback (entri acak dari semua informasi domain).
- (void)getRandomIpv6InfoWithDomain:(NSString *)domain complete:(void(^)(DNSDomainInfo *domainInfo))complete;

/// Mendapatkan array alamat IPv4 setelah resolusi nama domain.
/// Jika caching diaktifkan, memprioritaskan pengembalian data dari cache. Jika tidak ada cache atau cache telah kedaluwarsa, mendapatkan alamat IP yang sesuai melalui permintaan jaringan. Jika caching tidak diaktifkan, langsung mendapatkan alamat IP yang sesuai melalui permintaan jaringan.
/// @param domain           Nama domain.
/// @param complete       Callback (semua alamat IP).
- (void)getIpv4DataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

/// Mendapatkan array alamat IPv6 setelah resolusi nama domain.
/// Jika caching diaktifkan, memprioritaskan pengembalian data dari cache. Jika tidak ada cache atau cache telah kedaluwarsa, mendapatkan alamat IP yang sesuai melalui permintaan jaringan. Jika caching tidak diaktifkan, langsung mendapatkan alamat IP yang sesuai melalui permintaan jaringan.
/// @param domain           Nama domain.
/// @param complete       Callback (semua alamat IP).
- (void)getIpv6DataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

/// Mendapatkan alamat IPv4 setelah resolusi nama domain.
/// Jika caching diaktifkan, memprioritaskan pengembalian data dari cache. Jika tidak ada cache atau cache telah kedaluwarsa, mendapatkan alamat IP yang sesuai melalui permintaan jaringan. Jika caching tidak diaktifkan, langsung mendapatkan alamat IP yang sesuai melalui permintaan jaringan.
/// @param domain            Nama domain.
/// @param complete        Callback (alamat acak dari semua alamat IP).
- (void)getRandomIpv4DataWithDomain:(NSString *)domain complete:(void(^)(NSString *data))complete;

/// Mendapatkan alamat IPv6 setelah resolusi nama domain.
/// Jika caching diaktifkan, memprioritaskan pengembalian data dari cache. Jika tidak ada cache atau cache telah kedaluwarsa, mendapatkan alamat IP yang sesuai melalui permintaan jaringan. Jika caching tidak diaktifkan, langsung mendapatkan alamat IP yang sesuai melalui permintaan jaringan.
/// @param domain            Nama domain.
/// @param complete        Callback (alamat acak dari semua alamat IP).
- (void)getRandomIpv6DataWithDomain:(NSString *)domain complete:(void(^)(NSString *data))complete;

/// Pra-resolve informasi IPv4 domain. Ini dapat dipanggil saat program dimulai. Hasil resolusi disimpan dalam cache untuk mempercepat resolusi nama domain berikutnya.
/// @param domainArray  Array nama domain.
/// @param complete         Callback setelah resolusi selesai.
- (void)preloadIpv4Domains:(NSArray<NSString *> *)domainArray complete:(void(^)(void))complete;

/// Pra-resolve informasi IPv6 domain. Ini dapat dipanggil saat program dimulai. Hasil resolusi disimpan dalam cache untuk mempercepat resolusi nama domain berikutnya.
/// @param domainArray  Array nama domain.
/// @param complete         Callback setelah resolusi selesai.
- (void)preloadIpv6Domains:(NSArray<NSString *> *)domainArray complete:(void(^)(void))complete;

/// Langsung mendapatkan hasil resolusi IPv4 dari cache, tanpa menunggu.  
/// Jika tidak ada cache, mengembalikan nil. Jika ada cache dan enable diatur ke YES, mengembalikan data cache dan secara asinkron meng-resolve nama domain untuk memperbarui cache jika data telah kedaluwarsa. Jika ada cache dan enable diatur ke NO, mengembalikan nil saat cache telah kedaluwarsa dan secara asinkron meng-resolve nama domain untuk memperbarui cache.
/// @param domain   Nama domain.
/// @param enable   Menentukan apakah boleh mengembalikan alamat IP kedaluwarsa.
- (NSArray<NSString *> *)getIpv4ByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

/// Langsung mendapatkan hasil resolusi IPv6 dari cache, tanpa menunggu.  
/// Jika tidak ada cache, mengembalikan nil. Jika ada cache dan enable diatur ke YES, mengembalikan data cache dan secara asinkron meng-resolve nama domain untuk memperbarui cache jika data telah kedaluwarsa. Jika ada cache dan enable diatur ke NO, mengembalikan nil saat cache telah kedaluwarsa dan secara asinkron meng-resolve nama domain untuk memperbarui cache.
/// @param domain   Nama domain.
/// @param enable   Menentukan apakah boleh mengembalikan alamat IP kedaluwarsa.
- (NSArray<NSString *> *)getIpv6ByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

///Mengumpulkan informasi statistik.
-(NSArray *)getRequestReportInfo;

Contoh penggunaan API

1. Konfigurasi informasi dasar

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   // Titik override untuk kustomisasi setelah peluncuran aplikasi.
   // Metode inisialisasi unik
   DNSResolver *resolver = [DNSResolver share];
   //setAccountId:@"******": Ganti konten tanda bintang dengan Account ID dari halaman Konfigurasi Akses di Konsol.
   //andAccessKeyId:@"********": Ganti konten tanda bintang dengan ID AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
   //andAccesskeySecret:@"********": Ganti konten tanda bintang dengan Rahasia AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
   [resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
   // Tentukan domain untuk pembaruan cache kedaluwarsa otomatis. Array dibatasi maksimal 10 nama domain.
	 [resolver setKeepAliveDomains:@[@"user_specified_domain_1",@"user_specified_domain_2"]];
   // Pra-muat domain yang mungkin perlu di-resolve nanti untuk mendapatkan hasil resolusi lebih awal dan menyimpannya dalam cache.
   [resolver preloadDomains:@[@"domain1", @"domain2", @"domain3"] complete:^{
       // Semua domain telah dipra-muat.
       
   }];
   return YES;
}

2. API resolusi nama domain

SDK menyediakan berbagai metode resolusi nama domain, yang dapat Anda temukan di file header DNSResolver.h. Contoh berikut menjelaskan metode resolusi yang secara otomatis membedakan lingkungan jaringan (IPv4-only, IPv6-only, dan dual-stack IPv4 dan IPv6).

Deklarasi API:

/// Mendapatkan array alamat IP setelah resolusi nama domain. Secara otomatis mendeteksi lingkungan jaringan (IPv4-only, IPv6-only, atau dual-stack) untuk mendapatkan alamat IP yang sesuai dengan jaringan saat ini.
/// Jika caching diaktifkan, memprioritaskan pengembalian data dari cache. Jika tidak ada cache atau cache telah kedaluwarsa, mendapatkan alamat IP yang sesuai melalui permintaan jaringan. Jika caching tidak diaktifkan, langsung mendapatkan alamat IP yang sesuai melalui permintaan jaringan.
/// @param domain           Nama domain.
/// @param complete       Callback (semua alamat IP).
- (void)getIpsDataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

Contoh pemanggilan API:

[[DNSResolver share] getIpsDataWithDomain:@"www.taobao.com" complete:^(NSArray<NSString *> *dataArray) {
    // dataArray adalah array alamat IP untuk nama domain www.taobao.com.
   if (dataArray.count > 0) {
       //TODO: Gunakan alamat IP untuk koneksi URL.
   }    
}];

3. Ambil hasil resolusi langsung dari cache

Deklarasi API:

/// Secara otomatis mendeteksi lingkungan jaringan (IPv4-only, IPv6-only, atau dual-stack) untuk langsung mendapatkan array alamat IP yang sesuai dengan jaringan saat ini dari cache, tanpa menunggu.  
/// Jika tidak ada cache, mengembalikan nil. Jika ada cache dan enable diatur ke YES, mengembalikan data cache dan secara asinkron meng-resolve nama domain untuk memperbarui cache jika data telah kedaluwarsa. Jika ada cache dan enable diatur ke NO, mengembalikan nil saat cache telah kedaluwarsa dan secara asinkron meng-resolve nama domain untuk memperbarui cache.
/// @param domain   Nama domain.
/// @param enable   Menentukan apakah boleh mengembalikan alamat IP kedaluwarsa.
- (NSArray<NSString *> *)getIpsByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

Contoh pemanggilan:

NSArray *result = [[DNSResolver share] getIpsByCacheWithDomain:@"domain_name" andExpiredIPEnabled:YES];
// Dapatkan hasil cache.
if (result.count > 0) {
   //TODO: Gunakan alamat IP untuk koneksi URL.
   
}

Catatan: Mengambil hasil langsung dari cache lebih cepat. Namun, hasilnya akan bernilai nil jika tidak ada cache, atau jika hasil resolusi cache telah kedaluwarsa dan enable diatur ke NO.

4. Hapus cache

Deklarasi API:

/// hostArray adalah array nama domain host yang akan dihapus dari cache. Untuk menghapus semua data, teruskan nil atau array kosong.
-(void)clearHostCache:(NSArray <NSString *>*)hostArray;

Kode contoh:

[[DNSResolver share] clearHostCache:@[@"domain 1", @"domain 2"]];

5. Pengumpulan statistik

Deklarasi antarmuka:

///Pengumpulan informasi statistik
-(NSArray *)getRequestReportInfo;

Kode contoh:

NSArray *array = [[DNSResolver share] getRequestReportInfo];

Format data:

 (
      {
         avgRtt = "1";                                // Waktu resolusi domain rata-rata dalam ms
         cacheDnsNum = 0;                             // Jumlah hit cache                       
         domain = "www.taobao.com";                   // Nama domain yang di-resolve
         gobackLocaldnsNum = 0;                       // Jumlah downgrade ke LocalDNS
         localErro = 0;                               // Jumlah kegagalan resolusi LocalDNS
         maxRtt = "60";                               // Waktu resolusi domain maksimum dalam ms
         noPermissionErro = 0;                        // Jumlah kegagalan otentikasi pengguna
         noResponseErro = 0;                          // Jumlah timeout permintaan tanpa respons          
         requestPDnsNum = 1;                          // Jumlah query rekursif
         sp = "China Mobile";                         // Nama ISP
         successNum = 1;                              // Jumlah resolusi berhasil
         timeoutErro = 0;                             // Jumlah error timeout jaringan
         type = 28;                                   // Jenis IP, 1 merepresentasikan IPv4, 28 merepresentasikan IPv6
         urlParameterErro = 0;                        // Jumlah error format parameter permintaan
         urlPathErro = 0;                             // Jumlah error URL
      }
         ......
 );

Praktik terbaik untuk resolusi nama domain

Gabungkan pra-resolusi dengan mengizinkan respons kedaluwarsa untuk mencapai performa optimal.

Dalam skenario yang memerlukan performa jaringan tinggi, menggabungkan strategi pra-resolusi dan mengizinkan respons kedaluwarsa dapat secara signifikan meningkatkan kecepatan resolusi DNS bahkan mencapai resolusi latensi nol.

Berkat mekanisme caching bawaan SDK, setelah pra-resolusi selesai, permintaan resolusi domain berikutnya dapat langsung mengenai cache. Hal ini menghindari round-trip jaringan dan sangat mengoptimalkan pengalaman pengguna.

1. Pra-resolusi

Aktifkan caching dan pra-resolve nama domain utama. Kami merekomendasikan melakukan ini saat aplikasi dimulai.

Dalam metode AppDelegate's application:didFinishLaunchingWithOptions:, selesaikan terlebih dahulu nama domain yang digunakan dalam bisnis Anda dan simpan hasilnya di memori lokal.

1. Untuk skenario yang hanya mendukung IPv4

//********Untuk skenario yang hanya mendukung IPv4*******
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   DNSResolver *resolver = [DNSResolver share];
   //setAccountId:@"******": Ganti konten tanda bintang dengan Account ID dari halaman Konfigurasi Akses di Konsol.
   //andAccessKeyId:@"********": Ganti konten tanda bintang dengan ID AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
   //andAccesskeySecret:@"********": Ganti konten tanda bintang dengan Rahasia AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
   [resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
   // Menentukan apakah akan menggunakan cache. Nilai default adalah YES.
   resolver.cacheEnable = YES;
   // Pra-muat domain yang mungkin perlu di-resolve nanti. Ini pra-resolve informasi IPv4 domain.
   [resolver preloadIpv4Domains:@[@"domain1", @"domain2", @"domain3"] complete:^{
       // Semua domain telah dipra-muat.
   }];
   return YES;
}

2. Untuk skenario yang perlu mendukung IPv6

//********Untuk skenario yang perlu mendukung IPv6*******
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   DNSResolver *resolver = [DNSResolver share];
   //setAccountId:@"******": Ganti konten tanda bintang dengan Account ID dari halaman Konfigurasi Akses di Konsol.
   //andAccessKeyId:@"********": Ganti konten tanda bintang dengan ID AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
   //andAccesskeySecret:@"********": Ganti konten tanda bintang dengan Rahasia AccessKey dari kunci yang Anda buat di halaman Konfigurasi Akses di Konsol.
   [resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
   // Menentukan apakah akan menggunakan cache. Nilai default adalah YES.
   resolver.cacheEnable = YES;
   // Menentukan apakah akan menggunakan jaringan IPv6 untuk meng-resolve nama domain. Nilai default adalah NO.
   resolver.ipv6Enable = YES;
   // Menentukan apakah akan mengaktifkan probing alamat IP. Nilai default adalah NO.
   resolver.speedTestEnable = YES;
   // Pra-muat domain yang mungkin perlu di-resolve nanti. Ini secara otomatis mendeteksi lingkungan jaringan (IPv4-only, IPv6-only, atau dual-stack) untuk meng-resolve alamat IP yang sesuai dengan jaringan saat ini.
   [resolver preloadDomains:@[@"domain1", @"domain2", @"domain3"] complete:^{
       // Semua domain telah dipra-muat.
   }];
   return YES;
}

2. Izinkan respons kedaluwarsa

Saat melakukan resolusi, prioritaskan penggunaan cache dan izinkan pengembalian alamat IP kedaluwarsa. Sebelum memulai permintaan jaringan, ambil terlebih dahulu alamat IP dari cache dan izinkan penggunaan catatan cache kedaluwarsa namun masih valid (andExpiredIPEnabled:YES). Dengan cara ini, meskipun TTL telah lewat, hasil tetap dapat dikembalikan segera selama cache belum dihapus, mencapai resolusi tanpa menunggu.

1. Untuk skenario yang hanya mendukung IPv4

    //********Untuk skenario yang hanya mendukung IPv4*******
      __weak typeof(self) ws = self;
    // Prioritaskan pengambilan IP dari cache (ExpiredIPEnabled adalah YES, mengizinkan pengembalian catatan kedaluwarsa namun tersedia).
    NSArray<NSString *> *cachedIPs = [[DNSResolver share] getIpv4ByCacheWithDomain:domain andExpiredIPEnabled:YES];
    if (cachedIPs && cachedIPs.count > 0) {
        NSString *ip = cachedIPs.firstObject;
        NSLog(@"Cache hit cepat. Domain %@ di-resolve ke IP: %@", domain, ip);
        [self requestWithIP:ip domain:domain]; // Gunakan IP untuk koneksi langsung.
    } else {
        // Jika cache tidak ditemukan, mulai resolusi asinkron.
        [[DNSResolver share] getIpv4DataWithDomain:domain complete:^(NSArray<NSString *> *resolvedIPs) {
            if (resolvedIPs && resolvedIPs.count > 0) {
                NSString *ip = resolvedIPs.firstObject;
                NSLog(@"Resolusi asinkron selesai. Domain %@ di-resolve ke IP: %@", domain, ip);
                [ws requestWithIP:ip domain:domain]; // Gunakan IP untuk koneksi langsung.
            } else {
                NSLog(@"Resolusi nama domain gagal. Kembali ke nama domain asli.");
                [ws requestWithIP:domain domain:domain]; // Fallback: Gunakan nama domain asli.
            }
        }];
    }

2. Untuk skenario yang perlu mendukung IPv6

    //********Untuk skenario yang perlu mendukung IPv6*******
      __weak typeof(self) ws = self;
    // Prioritaskan pengambilan IP dari cache (ExpiredIPEnabled adalah YES, mengizinkan pengembalian catatan kedaluwarsa namun tersedia).
    NSArray<NSString *> *cachedIPs = [[DNSResolver share] getIpsByCacheWithDomain:domain andExpiredIPEnabled:YES];
    if (cachedIPs && cachedIPs.count > 0) {
        NSString *ip = cachedIPs.firstObject;
        NSLog(@"Cache hit cepat. Domain %@ di-resolve ke IP: %@", domain, ip);
        [self requestWithIP:ip domain:domain]; // Gunakan IP untuk koneksi langsung.
    } else {
        // Jika cache tidak ditemukan, mulai resolusi asinkron.
        [[DNSResolver share] getIpsDataWithDomain:domain complete:^(NSArray<NSString *> *resolvedIPs) {
            if (resolvedIPs && resolvedIPs.count > 0) {
                NSString *ip = resolvedIPs.firstObject;
                NSLog(@"Resolusi asinkron selesai. Domain %@ di-resolve ke IP: %@", domain, ip);
                [ws requestWithIP:ip domain:domain]; // Gunakan IP untuk koneksi langsung.
            } else {
                NSLog(@"Resolusi nama domain gagal. Kembali ke nama domain asli.");
                [ws requestWithIP:domain domain:domain]; // Fallback: Gunakan nama domain asli.
            }
        }];
    }

Catatan

1. pdns-sdk-ios.framework mendukung versi iOS minimum 9.0.

2. Saat membuat permintaan menggunakan protokol HTTP, Anda perlu mengatur App Transport Security Settings->Allow Arbitrary Loads ke YES di Info.plist.

3. Setelah Anda mendapatkan alamat IP suatu nama domain melalui HTTPDNS, klien dapat menggunakan alamat IP ini untuk mengirim permintaan layanan. Bidang Host dalam Header permintaan HTTP harus diatur ke nama domain asli.

   Contoh:

   // ip adalah alamat IP yang di-resolve dari nama domain asli.
   NSURL *url = [NSURL URLWithString:[NSString stringWithFormat:@"https://%@", ip]];
   NSMutableURLRequest *mutableReq = [NSMutableURLRequest requestWithURL:url cachePolicy:NSURLRequestUseProtocolCachePolicy timeoutInterval: 10];
   // Atur host.
   [mutableReq setValue:@"original_domain_name" forHTTPHeaderField:@"host"];

4. Untuk memastikan layanan Anda berjalan dengan benar, jika SDK gagal mendapatkan alamat IP untuk suatu nama domain, gunakan nama domain asli sebagai fallback untuk permintaan tersebut. Kode berikut memberikan contoh:

   NSArray *array = [[DNSResolver share] getIpsByCacheWithDomain:@"original_domain_name" andExpiredIPEnabled:YES];
   if (array && array.count >0 && array.firstObject.length > 0) {
       // Ganti host di URL dengan alamat IP untuk permintaan API.
       
   }else{
       // Tambahkan penanganan fallback (gunakan URL asli untuk permintaan API).
   }

5. Jika terdapat proxy HTTP perantara, baris permintaan dalam permintaan yang diinisiasi klien menggunakan URL jalur mutlak. Jika Anda mengaktifkan HTTPDNS dan menggunakan URL berbasis IP untuk akses, proxy perantara mengidentifikasi informasi IP Anda dan meneruskannya sebagai informasi host asli ke server target. Dalam kasus ini, server target tidak dapat memproses permintaan HTTP yang tidak berisi informasi host asli. Kami merekomendasikan agar Anda memeriksa apakah proxy jaringan diaktifkan pada perangkat saat ini. Jika proxy diaktifkan, jangan gunakan HTTPDNS untuk resolusi nama domain.

DNS On-premises

Mulai dari v2.3.0, iOS SDK HTTPDNS mendukung DNS on-premises untuk penyebaran privat.

Mode DNS on-premises cocok untuk skenario dengan persyaratan tinggi terhadap kepatuhan data dan kebijakan resolusi kustom, seperti keuangan, pemerintahan, dan perusahaan internet besar. SDK mendukung empat mode penyebaran khas untuk secara fleksibel beradaptasi dengan arsitektur bisnis berbeda: DNS cloud publik saja, DNS on-premises saja, dan mode hybrid primary/backup di mana DNS cloud publik dan DNS on-premises saling menjadi cadangan.

Fitur inti

• Dukungan penyebaran privat: Mendukung konfigurasi endpoint server DNS on-premises menggunakan alamat IPv4 atau IPv6, atau nama domain host.

• Otentikasi dua arah: Menggunakan accessKeyId dan accessKeySecret spesifik pelanggan untuk menandatangani permintaan, memastikan keamanan komunikasi.

• Circuit breaking dan Pemeriksaan kesehatan: Secara otomatis memutus sirkuit jika node DNS on-premises gagal tiga kali berturut-turut atau lebih. Kemudian memeriksa ketersediaan node setiap menit menggunakan healthCheckDomain yang ditentukan. Node secara otomatis diaktifkan kembali setelah pulih.

• Kontrol validasi sertifikat: Mendukung pengaktifan atau penonaktifan validasi sertifikat TLS. Kami sangat menyarankan mengaktifkannya di lingkungan produksi.

• Failover cerdas: Secara otomatis beralih ke DNS cadangan saat DNS primer (cloud publik atau on-premises) gagal menyelesaikan permintaan dan mencapai ambang batas tertentu. Hal ini memastikan Ketersediaan tinggi untuk resolusi.

• Kompatibilitas API mulus: Cara memanggil API resolusi tetap sama baik Anda menggunakan DNS cloud publik maupun DNS on-premises. Anda tidak perlu mengubah logika bisnis Anda.

Konfigurasi

DNSResolver *resolver = [DNSResolver share];
[resolver setAccountId:@"******" 
        andAccessKeyId:@"********" 
    andAccesskeySecret:@"********"];

DNSResolver *resolver = [DNSResolver share];
[resolver setFusionDNSWithIPv4:@[@"1.1.X.X", @"2.2.X.X"]
                            IPv6:nil
                           Host:nil
                           Port:@"443"
              HealthCheckDomain:@"check.example.com"
                    accessKeyId:@"your_fusion_ak"
                accesskeySecret:@"your_fusion_sk"];
// Opsional: Nonaktifkan validasi sertifikat (hanya untuk lingkungan pengujian).
// [resolver setEnableCertificateValidation:NO];

DNSResolver *resolver = [DNSResolver share];

// Primer: DNS cloud publik
[resolver setAccountId:@"******" 
        andAccessKeyId:@"********" 
    andAccesskeySecret:@"********"];
    
// Cadangan: DNS on-premises
[resolver setFusionDNSWithIPv4:@[@"1.1.X.X", @"2.2.X.X"]
                            IPv6:nil
                           Host:nil
                           Port:@"443"
              HealthCheckDomain:@"check.example.com"
                    accessKeyId:@"your_fusion_ak"
                accesskeySecret:@"your_fusion_sk"];
// Opsional: Nonaktifkan validasi sertifikat (hanya untuk lingkungan pengujian).
// [resolver setEnableCertificateValidation:NO];

DNSResolver *resolver = [DNSResolver share];

// Primer: DNS on-premises
[resolver setFusionDNSWithIPv4:@[@"1.1.X.X", @"2.2.X.X"]
                            IPv6:nil
                           Host:nil
                           Port:@"443"
              HealthCheckDomain:@"check.example.com"
                    accessKeyId:@"your_fusion_ak"
                accesskeySecret:@"your_fusion_sk"];
// Opsional: Nonaktifkan validasi sertifikat (hanya untuk lingkungan pengujian).
// [resolver setEnableCertificateValidation:NO];

// Cadangan: DNS cloud publik
[resolver setAccountId:@"******" 
        andAccessKeyId:@"********" 
    andAccesskeySecret:@"********"];

API layanan baru

Untuk mendukung penyebaran privat dan pemulihan bencana Ketersediaan tinggi untuk DNS on-premises, SDK menambahkan tiga API inti berikut. API ini digunakan untuk mengonfigurasi layanan DNS on-premises, mengontrol kebijakan keamanan, dan menerapkan failover primer/cadangan otomatis.

/** Ini terkait dengan DNS on-premises untuk penyebaran privat. Jangan panggil metode ini jika Anda hanya menggunakan DNS publik.
 *
 * Mengatur alamat server DNS on-premises dan informasi otentikasi.
 * Pelanggan meneruskan alamat server DNS privat dan kredensial otentikasi melalui API ini.
 * SDK akan menggunakan informasi ini untuk memulai permintaan.
 * @param ipv4 Array alamat IPv4 (bisa nil).
 * @param ipv6 Array alamat IPv6 (bisa nil).
 * @param host Array nama domain host (bisa nil).
 * @param port Port layanan (seperti @"443". Jika nil, nilai default digunakan).
 * @param healthCheckDomain Nama domain untuk pemeriksaan kesehatan setelah circuit break. Jika layanan resolusi gagal lebih dari 3 kali berturut-turut, circuit break terjadi, dan alamat IP layanan memasuki status healthCheck. Permintaan berikutnya tidak akan menggunakan layanan ini. Timer memeriksa healthCheckDomain ini setiap menit untuk memastikan layanan tersedia. Jika pemeriksaan berhasil, status layanan dipulihkan ke alive dan dapat digunakan untuk permintaan mendatang.
 * @param accessKeyId accessKeyId privat pelanggan (untuk otentikasi).
 * @param accesskeySecret accesskeySecret privat pelanggan (untuk otentikasi).
 */
- (void)setFusionDNSWithIPv4:(NSArray<NSString *> * _Nullable)ipv4
                        IPv6:(NSArray<NSString *> * _Nullable)ipv6
                        Host:(NSArray<NSString *> * _Nullable)host
                        Port:(NSString * _Nullable)port
           HealthCheckDomain:(NSString * _Nonnull)healthCheckDomain
                 accessKeyId:(NSString * _Nonnull)accessKeyId
             accesskeySecret:(NSString * _Nonnull)accesskeySecret;

/** Ini terkait dengan DNS on-premises untuk penyebaran privat. Jangan panggil metode ini jika Anda hanya menggunakan DNS publik.
 *
 * Menentukan apakah akan mengaktifkan validasi sertifikat untuk DNS on-premises (default adalah YES). Jika server tidak dikonfigurasi dengan Sertifikat nama domain dan sertifikat IP, Anda dapat mengatur ini ke NO untuk pengujian. Untuk lingkungan produksi, kami sangat menyarankan mengatur ini ke YES untuk menghindari risiko keamanan.
 * @param enable YES untuk mengaktifkan (default), NO untuk menonaktifkan.
 */
- (void)setEnableCertificateValidation:(BOOL)enable;

/** Saat DNS cloud publik dan DNS on-premises keduanya dikonfigurasi, ini mengatur jumlah kegagalan DNS primer sebelum secara otomatis failover ke DNS cadangan. Jika hanya satu jenis DNS yang dikonfigurasi, jangan panggil metode ini.
 *
 * Mengatur jumlah kegagalan DNS primer sebelum secara otomatis failover ke DNS cadangan. Jika hanya satu jenis DNS yang dikonfigurasi, jangan panggil metode ini.
 * @param fallbackThreshold Jumlah kegagalan (default adalah 4 saat DNS cloud publik sebagai primer, 2 saat DNS on-premises sebagai primer).
 * Rentang valid adalah [0-4]. Nilai 0 berarti failover terjadi segera. Maksimum adalah 4.
 */
- (void)setFallbackThreshold:(NSInteger)fallbackThreshold;

FAQ

FAQ terkait SDK/API