Cara Menggunakan API Cloudflare

TL;DR

API Cloudflare memungkinkan Anda mengelola DNS, zona, Workers, keamanan, dan analitik secara terprogram. Otentikasi dengan token API (direkomendasikan) atau kunci global, panggil api.cloudflare.com/client/v4, dan tangani batas laju dengan baik. Untuk pengujian, gunakan Apidog untuk memvalidasi perubahan DNS, menguji penyebaran Worker, dan mengotomatiskan konfigurasi di berbagai lingkungan.

Pendahuluan

Cloudflare berada di depan jutaan situs web. Ia menangani DNS, CDN, perlindungan DDoS, WAF, fungsi serverless Workers, dan lainnya. Mengelola semua itu melalui dasbor berfungsi untuk pengaturan kecil. Namun dalam skala besar, Anda membutuhkan otomatisasi.

API Cloudflare mencakup semua yang dilakukan dasbor. Anda dapat membuat zona, memperbarui catatan DNS, mengonfigurasi aturan halaman, menyebarkan Workers, mengelola pengaturan SSL, dan menarik analitik. Semuanya secara terprogram.

Pengembang menggunakan API Cloudflare untuk:

Infrastruktur sebagai kode (Terraform, Pulumi)
Integrasi pipeline CI/CD
Manajemen multi-zona
Pembaruan DNS otomatis
Penyebaran Worker

💡

Jika Anda membangun di Cloudflare, Apidog membantu Anda menguji panggilan API, memvalidasi respons, dan mendokumentasikan integrasi Anda. Anda dapat menyimpan konfigurasi zona sebagai permintaan yang dapat digunakan kembali dan membagikannya dengan tim Anda.

button

Uji API Cloudflare dengan Apidog - gratis

Di akhir panduan ini, Anda akan dapat:

Otentikasi dengan token API Cloudflare
Mengelola zona dan catatan DNS
Menyebarkan dan mengelola Workers
Mengonfigurasi pengaturan keamanan
Menarik analitik dan log

Otentikasi

Cloudflare menawarkan dua metode otentikasi. Gunakan token API, bukan kunci global.

Metode 1: Token API (direkomendasikan)

Token API dicakup ke izin tertentu. Jika token disusupi, kerusakannya terbatas.

Buat token:

Buka Dasbor Cloudflare → Profil Saya → Token API
Buat Token
Pilih template (Edit DNS zona, penyebaran Workers, dll.) atau kustom
Atur zona tertentu atau semua zona
Salin token

Gunakan token:

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Metode 2: Kunci API Global (tidak direkomendasikan)

Kunci global memiliki akses akun penuh. Hindari menggunakannya.

curl -X GET "https://api.cloudflare.com/client/v4/user" \
  -H "X-Auth-Email: your-email@example.com" \
  -H "X-Auth-Key: YOUR_GLOBAL_API_KEY"

Format respons

Semua respons API Cloudflare mengikuti struktur ini:

{
  "result": { ... },
  "success": true,
  "errors": [],
  "messages": []
}

Selalu periksa success sebelum memproses result.

Manajemen zona

Zona mewakili domain di Cloudflare.

Daftar zona

curl -X GET "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Respons:

{
  "result": [
    {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com",
      "status": "active",
      "paused": false,
      "type": "full",
      "development_mode": 0,
      "name_servers": [
        "ns1.cloudflare.com",
        "ns2.cloudflare.com"
      ],
      "original_name_servers": [
        "ns1.example.com"
      ],
      "original_registrar": null
    }
  ],
  "success": true
}

Buat zona

curl -X POST "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "newdomain.com",
    "account": {
      "id": "ACCOUNT_ID"
    },
    "type": "full"
  }'

Dapatkan detail zona

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Manajemen catatan DNS

Catatan DNS memetakan nama domain ke alamat IP dan layanan.

Daftar catatan DNS

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Buat catatan DNS

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "www",
    "content": "192.0.2.1",
    "ttl": 3600,
    "proxied": true
  }'

Tipe catatan:

A - Alamat IPv4
AAAA - Alamat IPv6
CNAME - Alias ke domain lain
MX - Server email
TXT - Catatan teks (SPF, DKIM, verifikasi)
NS - Server nama

Perbarui catatan DNS

curl -X PUT "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/RECORD_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "www",
    "content": "192.0.2.2",
    "ttl": 3600,
    "proxied": true
  }'

Hapus catatan DNS

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/RECORD_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Cloudflare Workers

Workers menjalankan JavaScript di edge, dekat dengan pengguna.

Daftar Workers

curl -X GET "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/workers/scripts" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Unggah Worker

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/workers/scripts/my-worker" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/javascript" \
  --data-binary @worker.js

Contoh Worker:

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)
    
    if (url.pathname === '/api/hello') {
      return new Response(JSON.stringify({ message: 'Hello from the edge!' }), {
        headers: { 'Content-Type': 'application/json' }
      })
    }
    
    return fetch(request)
  }
}

Ikatan rute

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/workers/routes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "example.com/api/*",
    "script": "my-worker"
  }'

Namespace KV Worker

Simpan data yang dapat diakses dari Workers:

curl -X POST "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/storage/kv/namespaces" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "my-kv-namespace"
  }'

Keamanan dan WAF

Aturan halaman

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/pagerules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      {
        "target": "url",
        "constraint": {
          "operator": "matches",
          "value": "example.com/*"
        }
      }
    ],
    "actions": [
      {
        "id": "ssl",
        "value": "flexible"
      },
      {
        "id": "cache_level",
        "value": "aggressive"
      }
    ]
  }'

Aturan firewall

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/firewall/rules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "expression": "ip.geoip.country eq \"CN\"",
      "paused": false
    },
    "action": "block",
    "description": "Block traffic from China"
  }'

Pembatasan laju

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/rate_limits" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "disabled": false,
    "description": "Rate limit API endpoints",
    "match": {
      "request": {
        "methods": ["POST"],
        "url_pattern": "*/api/*"
      }
    },
    "threshold": 100,
    "period": 60,
    "action": {
      "mode": "ban",
      "timeout": 600
    }
  }'

Analitik dan log

Analitik zona

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/analytics/dashboard?since=-1440&continuous=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Respons:

{
  "result": {
    "totals": {
      "requests": {
        "all": 1000000,
        "cached": 800000,
        "uncached": 200000
      },
      "bandwidth": {
        "all": 50000000000,
        "cached": 40000000000
      },
      "threats": {
        "all": 5000
      },
      "pageviews": {
        "all": 250000
      }
    }
  }
}

Log zona (Logpush)

Aktifkan Logpush untuk mengirim log ke penyimpanan Anda:

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/logpush/jobs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Logpush Job",
    "destination_conf": "s3://my-bucket/logs?region=us-east-1",
    "dataset": "http_requests",
    "logpull_options": "fields=ClientIP,ClientRequestPath,EdgeResponseStatus&timestamps=rfc3339"
  }'

Pengujian dengan Apidog

Perubahan Cloudflare memengaruhi lalu lintas produksi. Uji secara menyeluruh.

1. Pengaturan lingkungan

CLOUDFLARE_API_TOKEN: your_token
CLOUDFLARE_ACCOUNT_ID: abc123
ZONE_ID: xyz789
BASE_URL: https://api.cloudflare.com/client/v4

2. Validasi respons

pm.test('Request was successful', () => {
  const response = pm.response.json()
  pm.expect(response.success).to.be.true
  pm.expect(response.errors).to.be.empty
})

pm.test('DNS record created correctly', () => {
  const response = pm.response.json()
  pm.expect(response.result.type).to.eql('A')
  pm.expect(response.result.name).to.eql('www')
  pm.expect(response.result.proxied).to.be.true
})

3. Uji penyebaran Worker

Simpan skrip Worker sebagai file di Apidog dan uji unggahan:

pm.test('Worker uploaded', () => {
  const response = pm.response.json()
  pm.expect(response.result.id).to.eql('my-worker')
})

Uji API Cloudflare dengan Apidog - gratis

Kesalahan umum dan perbaikan

403 Terlarang

Penyebab: Token tidak memiliki izin yang diperlukan.

Perbaikan: Periksa izin token di dasbor Cloudflare. Pengeditan DNS memerlukan Zone:DNS:Edit. Workers memerlukan Account:Workers:Edit.

1003: Zona tidak valid atau tidak ada

Penyebab: ID zona tidak ada atau token tidak dapat mengaksesnya.

Perbaikan: Verifikasi ID zona di URL dan periksa apakah cakupan token mencakup zona ini.

81057: Catatan sudah ada

Penyebab: Catatan DNS dengan nama dan tipe yang sama sudah ada.

Perbaikan: Gunakan PUT untuk memperbarui alih-alih POST untuk membuat, atau hapus terlebih dahulu.

Batas laju terlampaui

Penyebab: Terlalu banyak permintaan (default 1200/5 menit).

Perbaikan: Terapkan penundaan dan operasi batch.

async function updateRecords(records) {
  for (const record of records) {
    try {
      await updateRecord(record)
      await sleep(100) // Rate limit buffer
    } catch (error) {
      if (error.status === 429) {
        await sleep(60000) // Wait a minute
        await updateRecord(record) // Retry
      }
    }
  }
}

Alternatif dan perbandingan

Fitur	Cloudflare	AWS Route 53	Fastly
API DNS	✓	✓	✓
API CDN	✓	CloudFront API	✓
Fungsi edge	Workers	Lambda@Edge	Compute@Edge
API WAF	✓	AWS WAF	✓
Tingkat gratis	Murah hati	Bayar sesuai penggunaan	Terbatas
Format respons	JSON	XML/JSON	JSON

API Cloudflare lebih terpadu dibandingkan layanan AWS yang terfragmentasi. Workers memberikan fleksibilitas lebih daripada Lambda@Edge.

Kasus penggunaan dunia nyata

SaaS Multi-tenant. Sebuah platform secara otomatis membuat zona Cloudflare ketika pelanggan menambahkan domain kustom. Workers menangani perutean, catatan DNS dibuat melalui API, dan sertifikat SSL disediakan secara otomatis.

Penyebaran blue-green. Sebuah tim teknik menggunakan pembaruan catatan DNS untuk mengalihkan lalu lintas antar lingkungan. API memperbarui catatan A selama penyebaran, dengan propagasi instan melalui jaringan Cloudflare.

Otomatisasi respons DDoS. Sebuah tim keamanan memantau lalu lintas melalui API analitik. Ketika pola serangan muncul, aturan firewall ditambahkan melalui API untuk memblokir IP berbahaya, mengurangi waktu respons dari jam menjadi detik.

Kesimpulan

Berikut adalah apa yang telah Anda pelajari:

Otentikasi dengan token API untuk akses terbatas
Mengelola zona dan catatan DNS secara terprogram
Menyebarkan Workers untuk komputasi edge
Mengonfigurasi keamanan dengan aturan firewall dan pembatasan laju
Menarik analitik dan mengonfigurasi pengiriman log
Uji dengan Apidog sebelum diterapkan ke produksi

button

FAQ

Apa perbedaan antara zona dan domain?Zona adalah representasi Cloudflare dari sebuah domain. Saat Anda menambahkan domain ke Cloudflare, Anda membuat zona. ID zona digunakan dalam panggilan API untuk domain tersebut.

Bagaimana cara menemukan ID zona saya?Buka Dasbor Cloudflare → pilih domain Anda → Ikhtisar → gulir ke bawah ke bagian API. ID zona ditampilkan di sana.

Bisakah saya menggunakan API Cloudflare tanpa paket berbayar?Ya. Sebagian besar fitur API berfungsi di paket gratis. Workers memiliki tingkat gratis yang murah hati. Beberapa fitur lanjutan (aturan WAF lanjutan, Logpush) memerlukan paket berbayar.

Berapa lama waktu yang dibutuhkan perubahan DNS?Perubahan melalui API bersifat instan dalam sistem Cloudflare. Propagasi ke nameserver Cloudflare membutuhkan waktu beberapa detik. Propagasi global bergantung pada TTL dan resolver rekursif, biasanya beberapa menit.

Berapa batas laju?Default: 1200 permintaan per 5 menit per token. Periksa header X-RateLimit-Remaining. Paket Enterprise memiliki batas yang lebih tinggi.

Bisakah saya mengelola beberapa akun dengan satu token?Tidak. Token dicakup untuk satu akun. Untuk beberapa akun, buat token terpisah atau gunakan token tingkat pengguna dengan akses ke beberapa akun.

Bagaimana Workers berbeda dari Lambda?Workers berjalan di lokasi edge Cloudflare (300+ kota), bukan di wilayah tertentu. Waktu mulai dingin (cold starts) minimal. Mereka ideal untuk manipulasi permintaan/respons, bukan proses yang berjalan lama.

Bisakah saya menggunakan API untuk menghapus cache?Ya:

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "files": ["https://example.com/style.css"]
  }'