HTTPDNS:API layanan penjadwalan

1. Pendahuluan

API penjadwalan merupakan komponen inti dalam arsitektur high availability (HA) HTTPDNS. API ini secara cerdas mengalokasikan node layanan resolusi terbaik berdasarkan lokasi dan kondisi jaringan klien. Gunakan API penjadwalan untuk memperoleh daftar alamat IP layanan yang sehat dan berada di dekat Anda guna mendukung resolusi nama domain berkinerja tinggi.

Topik ini menjelaskan cara menggunakan API penjadwalan, termasuk formatnya, parameter, mekanisme keamanan, serta penanganan respons. Bagian utamanya meliputi:

• Format API: Menjelaskan format dasar API penjadwalan dan cara menyusun URL-nya.

• Deskripsi parameter: Menjabarkan parameter API penjadwalan, termasuk parameter yang diperlukan dan opsional.

• Penandatanganan permintaan: Menjelaskan mekanisme penandatanganan permintaan untuk meningkatkan keamanan permintaan penjadwalan.

• Deskripsi respons API: Menjelaskan format respons API dan mekanisme penanganan kesalahan.

• Mekanisme pembaruan IP layanan: Memberikan strategi dan praktik terbaik untuk pembaruan IP layanan.

2. Format API

API penjadwalan mendukung akses melalui HTTP atau HTTPS. Format API-nya adalah sebagai berikut:

• URL layanan: http(s)://{startup_endpoint}/{account_id}/ss? + {request_parameters}

• Metode permintaan: GET

3. Deskripsi parameter

Gunakan parameter permintaan untuk mengontrol kebijakan penjadwalan dan mekanisme keamanan. Anda dapat mengatur parameter ini untuk mengaktifkan fitur seperti penjadwalan dasar dan autentikasi signature.

3.1. Daftar parameter

3.2. Contoh parameter permintaan

• Permintaan untuk wilayah tertentu

GET https://{startup_endpoint}/{account_id}/ss?region=cn&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

• Permintaan berbasis kedekatan

GET https://{startup_endpoint}/{account_id}/ss?region=global&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

4. Penandatanganan permintaan (opsional)

Aktifkan penandatanganan permintaan untuk meningkatkan keamanan permintaan penjadwalan. Mekanisme ini mencegah perubahan pada permintaan.

4.1. Algoritma signature

• Algoritma: HMAC-MD5

• Kunci: Kunci penandatanganan. Anda dapat memperoleh kunci tersebut dari Developer Configurations.

• Input: String yang disusun dalam format `{n}-{secret}-{t}`.

• Output: String heksadesimal 32 digit dalam huruf kecil.

4.2. Langkah-langkah penandatanganan

1. Hasilkan bilangan acak n: String heksadesimal sepanjang 8 hingga 16 digit.

2. Peroleh timestamp t yang valid: Waktu saat ini ditambah periode validitas dalam detik. Disarankan periode validitas antara 30 hingga 300 detik.

3. Susun string signature: Gabungkan komponen-komponen dalam format {n}-{secret}-{t}.

4. Hitung signature: Gunakan algoritma HMAC-MD5 untuk menghitung nilai signature.

4.3. Contoh penandatanganan

Asumsikan hal berikut:

• Bilangan acak n = abcdef2345

• SecretKey = 123456

• Timestamp t = 1632912372

• Wilayah region = cn

Proses perhitungan signature:

String to sign = "abcdef2345-123456-1632912372"
s = HMAC-MD5("123456", "abcdef2345-123456-1632912372")
  = "de7be63a9f19cf11e9d455d7d4f23cb4"

Permintaan akhir:

GET https://{startup_endpoint}/{account_id}/ss?region=cn&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

5. Deskripsi respons API

Respons API penjadwalan berisi daftar alamat IP layanan dan metadata terkait. Bagian ini menjelaskan struktur data untuk respons sukses, definisi bidang, serta cara menangani kesalahan.

5.1. Format respons

Jika permintaan berhasil, kode status respons HTTP adalah 200. Respons berformat JSON:

{
  "service_ip": [
    "203.107.1.xx",
    "106.xxx.1.xx"
  ],
  "service_ipv6": [
    "64:ff9b::xxx:121",
    "64:ff9b::xxx:122"
  ]
}

5.2. Deskripsi bidang respons

5.3. Respons kesalahan

Jika permintaan gagal, kode status respons HTTP adalah 4xx atau 5xx. Respons berformat JSON:

{
  "code": "MissingArgument"
}

Kode kesalahan umum:

6. Ringkasan

Topik ini menjelaskan penggunaan dan detail teknis API layanan penjadwalan HTTPDNS, termasuk aspek-aspek penting seperti format API, pengaturan parameter, mekanisme keamanan, dan penanganan respons. Anda dapat menggunakan API penjadwalan untuk memperoleh daftar IP layanan resolusi optimal. Setelah memperoleh daftar IP tersebut, Anda dapat melakukan resolusi nama domain. Untuk informasi selengkapnya, lihat Domain Name Resolution Interface.