Cloudflare API'leri Nasıl Kullanılır?

TL;DR

Cloudflare API'leri DNS, bölgeler, Workers, güvenlik ve analitikleri programlı olarak yönetmenizi sağlar. API jetonları (önerilir) veya global anahtarlar ile kimlik doğrulaması yapın, api.cloudflare.com/client/v4 adresini çağırın ve hız sınırlamalarını sorunsuz bir şekilde ele alın. Test için, DNS değişikliklerini doğrulamak, Worker dağıtımlarını test etmek ve ortamlar arası yapılandırmayı otomatikleştirmek için Apidog'u kullanın.

Giriş

Cloudflare milyonlarca web sitesinin önünde yer alır. DNS, CDN, DDoS koruması, WAF, Workers sunucusuz işlevler ve daha fazlasını yönetir. Tüm bunları kontrol paneli aracılığıyla yönetmek küçük kurulumlar için uygundur. Ancak ölçek büyüdüğünde otomasyona ihtiyacınız olur.

Cloudflare API'si kontrol panelinin yaptığı her şeyi kapsar. Bölgeler oluşturabilir, DNS kayıtlarını güncelleyebilir, sayfa kurallarını yapılandırabilir, Workers dağıtabilir, SSL ayarlarını yönetebilir ve analitik verilerini çekebilirsiniz. Hepsi programlı olarak.

Geliştiriciler Cloudflare API'sini şu amaçlarla kullanır:

Kod olarak altyapı (Terraform, Pulumi)
CI/CD ardışık düzen entegrasyonu
Çoklu bölge yönetimi
Otomatik DNS güncellemeleri
Worker dağıtımları

💡

Cloudflare üzerinde geliştirme yapıyorsanız, Apidog API çağrılarını test etmenize, yanıtları doğrulamanıza ve entegrasyonunuzu belgelemenize yardımcı olur. Bölge yapılandırmalarını yeniden kullanılabilir istekler olarak kaydedebilir ve ekibinizle paylaşabilirsiniz.

button

Cloudflare API'lerini Apidog ile test edin - ücretsiz

Bu kılavuzun sonunda şunları yapabileceksiniz:

Cloudflare API jetonları ile kimlik doğrulaması yapma
Bölgeleri ve DNS kayıtlarını yönetme
Workers dağıtma ve yönetme
Güvenlik ayarlarını yapılandırma
Analitik ve günlükleri çekme

Kimlik Doğrulama

Cloudflare iki kimlik doğrulama yöntemi sunar. Global anahtarlar yerine API jetonlarını kullanın.

Yöntem 1: API jetonları (önerilir)

API jetonları belirli izinlerle sınırlıdır. Bir jeton ele geçirilirse, verilen zarar sınırlıdır.

Jeton oluşturma:

Cloudflare Paneli → Profilim → API Jetonları'na gidin
Jeton Oluştur
Bir şablon seçin (Bölge DNS'i düzenle, Workers dağıtımı vb.) veya özel
Belirli bölgeleri veya tüm bölgeleri ayarlayın
Jetonu kopyalayın

Jetonu kullanma:

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

Yöntem 2: Global API anahtarı (önerilmez)

Global anahtarın tüm hesap erişimi vardır. Kullanmaktan kaçının.

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"

Yanıt formatı

Tüm Cloudflare API yanıtları bu yapıyı takip eder:

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

result'ı işlemden geçirmeden önce her zaman success değerini kontrol edin.

Bölge yönetimi

Bölgeler, Cloudflare'deki alan adlarını temsil eder.

Bölgeleri listele

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

Yanıt:

{
  "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
}

Bölge oluştur

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"
  }'

Bölge detaylarını al

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

DNS kayıt yönetimi

DNS kayıtları alan adlarını IP adreslerine ve hizmetlere eşler.

DNS kayıtlarını listele

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

DNS kaydı oluştur

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
  }'

Kayıt türleri:

A - IPv4 adresi
AAAA - IPv6 adresi
CNAME - Başka bir alan adına takma ad
MX - Posta sunucusu
TXT - Metin kayıtları (SPF, DKIM, doğrulama)
NS - Ad sunucusu

Bir DNS kaydını güncelle

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
  }'

Bir DNS kaydını sil

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, kullanıcılara yakın, ağ kenarında JavaScript çalıştırır.

Workers'ı listele

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

Worker yükle

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

Worker örneği:

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)
  }
}

Bir yol bağla

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"
  }'

Worker KV ad alanı

Workers'tan erişilebilir verileri depolayın:

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"
  }'

Güvenlik ve WAF

Sayfa kuralları

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"
      }
    ]
  }'

Güvenlik duvarı kuralları

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"
  }'

Hız sınırlama

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 ve günlükler

Bölge analitikleri

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

Yanıt:

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

Bölge günlükleri (Logpush)

Günlükleri depolama alanınıza göndermek için Logpush'ı etkinleştirin:

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"
  }'

Apidog ile test etme

Cloudflare değişiklikleri üretim trafiğini etkiler. Kapsamlı bir şekilde test edin.

1. Ortam kurulumu

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

2. Yanıtları doğrula

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. Worker dağıtımlarını test et

Worker betiklerini Apidog'da dosya olarak kaydedin ve yüklemeleri test edin:

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

Apidog ile Cloudflare API'lerini test edin - ücretsiz

Yaygın hatalar ve çözümleri

403 Yasak

Neden: Jetonun gerekli izni yok.

Çözüm: Cloudflare panelinde jeton izinlerini kontrol edin. DNS düzenlemeleri için Bölge:DNS:Düzenleme izni gerekir. Workers için Hesap:Workers:Düzenleme izni gerekir.

1003: Geçersiz veya eksik bölge

Neden: Bölge kimliği mevcut değil veya jeton ona erişemiyor.

Çözüm: URL'deki bölge kimliğini doğrulayın ve jeton kapsamının bu bölgeyi içerdiğini kontrol edin.

81057: Kayıt zaten mevcut

Neden: Aynı ada ve türe sahip bir DNS kaydı mevcut.

Çözüm: Oluşturmak için POST yerine güncellemek için PUT kullanın veya önce silin.

Hız limiti aşıldı

Neden: Çok fazla istek (varsayılan 1200/5 dakika).

Çözüm: Geri çekilme (backoff) ve toplu işlemleri uygulayın.

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
      }
    }
  }
}

Alternatifler ve karşılaştırmalar

Özellik	Cloudflare	AWS Route 53	Fastly
DNS API	✓	✓	✓
CDN API	✓	CloudFront API	✓
Kenar işlevleri	Workers	Lambda@Edge	Compute@Edge
WAF API	✓	AWS WAF	✓
Ücretsiz katman	Cömert	Kullanım başına öde	Sınırlı
Yanıt formatı	JSON	XML/JSON	JSON

Cloudflare'ın API'si, AWS'nin parçalı hizmetlerinden daha birleşiktir. Workers, Lambda@Edge'den daha fazla esneklik sağlar.

Gerçek dünya kullanım senaryoları

Çok kiracılı SaaS. Bir platform, müşteriler özel alan adları eklediğinde otomatik olarak Cloudflare bölgeleri oluşturur. Workers yönlendirmeyi halleder, DNS kayıtları API aracılığıyla oluşturulur ve SSL sertifikaları otomatik olarak sağlanır.

Mavi-yeşil dağıtımlar. Bir mühendislik ekibi, ortamlar arasında trafiği değiştirmek için DNS kayıt güncellemelerini kullanır. API, dağıtım sırasında A kayıtlarını günceller ve Cloudflare'ın ağı üzerinden anında yayılım sağlar.

DDoS yanıt otomasyonu. Bir güvenlik ekibi, analitik API aracılığıyla trafiği izler. Saldırı modelleri ortaya çıktığında, kötü amaçlı IP'leri engellemek için API aracılığıyla güvenlik duvarı kuralları eklenir ve yanıt süresi saatlerden saniyelere düşürülür.

Özet

İşte öğrendikleriniz:

Kapsamlı erişim için API jetonları ile kimlik doğrulama
Bölgeleri ve DNS kayıtlarını programlı olarak yönetme
Uç bilişim için Workers dağıtma
Güvenlik duvarı kuralları ve hız sınırlaması ile güvenliği yapılandırma
Analitikleri çekme ve günlük gönderimini yapılandırma
Üretime uygulamadan önce Apidog ile test etme

button

SSS

Bölge ile alan adı arasındaki fark nedir?Bir bölge, Cloudflare'ın bir alan adını temsilidir. Cloudflare'a bir alan adı eklediğinizde bir bölge oluşturursunuz. Bu alan adı için API çağrılarında bölge kimliği kullanılır.

Bölge kimliğimi nasıl bulurum?Cloudflare Paneli → alan adınızı seçin → Genel Bakış → API bölümüne aşağı kaydırın. Bölge kimliği orada gösterilir.

Ücretli bir plan olmadan Cloudflare API'sini kullanabilir miyim?Evet. Çoğu API özelliği ücretsiz planlarda çalışır. Workers'ın cömert bir ücretsiz katmanı vardır. Bazı gelişmiş özellikler (gelişmiş WAF kuralları, Logpush) ücretli planlar gerektirir.

DNS değişiklikleri ne kadar sürer?API aracılığıyla yapılan değişiklikler Cloudflare sisteminde anında gerçekleşir. Cloudflare ad sunucularına yayılım saniyeler sürer. Global yayılım TTL'e ve özyinelemeli çözümleyicilere bağlıdır, genellikle dakikalar sürer.

Hız limiti nedir?Varsayılan: Jeton başına 5 dakikada 1200 istek. X-RateLimit-Remaining başlığını kontrol edin. Kurumsal planlar daha yüksek limitlere sahiptir.

Tek bir jetonla birden fazla hesabı yönetebilir miyim?Hayır. Jetonlar tek bir hesapla sınırlıdır. Birden fazla hesap için ayrı jetonlar oluşturun veya birden fazla hesaba erişimi olan kullanıcı düzeyinde jetonlar kullanın.

Workers Lambda'dan nasıl farklıdır?Workers, belirli bölgelerde değil, Cloudflare'ın uç konumlarında (300'den fazla şehir) çalışır. Soğuk başlangıçlar minimumdur. İstek/yanıt manipülasyonu için idealdir, uzun süreli işlemler için değil.

API'yi önbelleği temizlemek için kullanabilir miyim?Evet:

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"]
  }'