Cloudflare API Nutzung: Eine Anleitung

Kurzgesagt

Cloudflare APIs ermöglichen die programmgesteuerte Verwaltung von DNS, Zonen, Workers, Sicherheit und Analysen. Authentifizieren Sie sich mit API-Tokens (empfohlen) oder globalen Schlüsseln, rufen Sie api.cloudflare.com/client/v4 auf und behandeln Sie Ratenbegrenzungen elegant. Verwenden Sie für Tests Apidog, um DNS-Änderungen zu validieren, Worker-Bereitstellungen zu testen und die Konfiguration über verschiedene Umgebungen hinweg zu automatisieren.

Einführung

Cloudflare steht vor Millionen von Websites. Es verwaltet DNS, CDN, DDoS-Schutz, WAF, serverlose Workers-Funktionen und mehr. Die Verwaltung all dessen über das Dashboard funktioniert für kleine Setups. Aber in großem Umfang benötigen Sie Automatisierung.

Die Cloudflare API deckt alles ab, was das Dashboard leistet. Sie können Zonen erstellen, DNS-Einträge aktualisieren, Seitenregeln konfigurieren, Workers bereitstellen, SSL-Einstellungen verwalten und Analysedaten abrufen. Alles programmgesteuert.

Entwickler nutzen die Cloudflare API für:

Infrastruktur als Code (Terraform, Pulumi)
CI/CD-Pipeline-Integration
Multi-Zonen-Verwaltung
Automatisierte DNS-Updates
Worker-Bereitstellungen

💡

Wenn Sie auf Cloudflare aufbauen, hilft Ihnen Apidog beim Testen von API-Aufrufen, Validieren von Antworten und Dokumentieren Ihrer Integration. Sie können Zonenkonfigurationen als wiederverwendbare Anfragen speichern und mit Ihrem Team teilen.

button

Testen Sie Cloudflare APIs mit Apidog - kostenlos

Am Ende dieses Leitfadens werden Sie in der Lage sein:

Sich mit Cloudflare API-Tokens zu authentifizieren
Zonen und DNS-Einträge zu verwalten
Workers bereitzustellen und zu verwalten
Sicherheitseinstellungen zu konfigurieren
Analysen und Protokolle abzurufen

Authentifizierung

Cloudflare bietet zwei Authentifizierungsmethoden an. Verwenden Sie API-Tokens, nicht globale Schlüssel.

Methode 1: API-Tokens (empfohlen)

API-Tokens sind auf bestimmte Berechtigungen beschränkt. Wenn ein Token kompromittiert wird, ist der Schaden begrenzt.

Token erstellen:

Gehen Sie zu Cloudflare Dashboard → Mein Profil → API-Tokens
Token erstellen
Wählen Sie eine Vorlage (DNS-Zone bearbeiten, Workers-Bereitstellung usw.) oder benutzerdefiniert
Legen Sie bestimmte Zonen oder alle Zonen fest
Token kopieren

Token verwenden:

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

Methode 2: Globaler API-Schlüssel (nicht empfohlen)

Der globale Schlüssel hat vollen Kontozugriff. Vermeiden Sie dessen Verwendung.

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"

Antwortformat

Alle Cloudflare API-Antworten folgen dieser Struktur:

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

Überprüfen Sie immer success, bevor Sie result verarbeiten.

Zonenverwaltung

Zonen repräsentieren Domains in Cloudflare.

Zonen auflisten

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

Antwort:

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

Eine Zone erstellen

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

Zonendetails abrufen

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

DNS-Einträge verwalten

DNS-Einträge ordnen Domainnamen IP-Adressen und Diensten zu.

DNS-Einträge auflisten

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

Einen DNS-Eintrag erstellen

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

Eintragstypen:

A - IPv4-Adresse
AAAA - IPv6-Adresse
CNAME - Alias zu einer anderen Domain
MX - Mailserver
TXT - Texteinträge (SPF, DKIM, Verifizierung)
NS - Nameserver

Einen DNS-Eintrag aktualisieren

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

Einen DNS-Eintrag löschen

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 führen JavaScript am Edge aus, nah an den Benutzern.

Workers auflisten

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

Einen Worker hochladen

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-Beispiel:

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

Eine Route binden

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

Von Workers aus zugängliche Daten speichern:

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

Sicherheit und WAF

Seitenregeln

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

Firewall-Regeln

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

Ratenbegrenzung

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

Analysen und Protokolle

Zonenanalysen

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

Antwort:

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

Zonenprotokolle (Logpush)

Aktivieren Sie Logpush, um Protokolle an Ihren Speicher zu senden:

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

Testen mit Apidog

Cloudflare-Änderungen wirken sich auf den Produktionsdatenverkehr aus. Gründlich testen.

1. Umgebungseinrichtung

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

2. Antworten validieren

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-Bereitstellungen testen

Speichern Sie Worker-Skripte als Dateien in Apidog und testen Sie Uploads:

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

Testen Sie Cloudflare APIs mit Apidog - kostenlos

Häufige Fehler und Behebungen

403 Verboten

Ursache: Dem Token fehlen die erforderlichen Berechtigungen.

Behebung: Überprüfen Sie die Token-Berechtigungen im Cloudflare-Dashboard. DNS-Bearbeitungen benötigen Zone:DNS:Edit. Workers benötigen Account:Workers:Edit.

1003: Ungültige oder fehlende Zone

Ursache: Die Zonen-ID existiert nicht oder der Token kann nicht darauf zugreifen.

Behebung: Überprüfen Sie die Zonen-ID in der URL und stellen Sie sicher, dass der Token-Bereich diese Zone einschließt.

81057: Eintrag existiert bereits

Ursache: Ein DNS-Eintrag mit demselben Namen und Typ existiert bereits.

Behebung: Verwenden Sie PUT zum Aktualisieren anstelle von POST zum Erstellen, oder löschen Sie den Eintrag zuerst.

Ratenbegrenzung überschritten

Ursache: Zu viele Anfragen (Standard 1200/5 Minuten).

Behebung: Implementieren Sie Backoff- und Batch-Operationen.

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

Alternativen und Vergleiche

Funktion	Cloudflare	AWS Route 53	Fastly
DNS API	✓	✓	✓
CDN API	✓	CloudFront API	✓
Edge-Funktionen	Workers	Lambda@Edge	Compute@Edge
WAF API	✓	AWS WAF	✓
Kostenloser Tarif	Großzügig	Pay-per-Use	Begrenzt
Antwortformat	JSON	XML/JSON	JSON

Die API von Cloudflare ist einheitlicher als die fragmentierten Dienste von AWS. Workers bieten mehr Flexibilität als Lambda@Edge.

Anwendungsfälle in der Praxis

Multi-Tenant SaaS. Eine Plattform erstellt automatisch Cloudflare-Zonen, wenn Kunden benutzerdefinierte Domains hinzufügen. Workers übernehmen das Routing, DNS-Einträge werden über die API erstellt und SSL-Zertifikate automatisch bereitgestellt.

Blue-Green-Deployments. Ein Entwicklungsteam verwendet DNS-Eintragsaktualisierungen, um den Datenverkehr zwischen Umgebungen umzuschalten. Die API aktualisiert A-Einträge während der Bereitstellung, mit sofortiger Verbreitung über das Cloudflare-Netzwerk.

DDoS-Reaktionsautomatisierung. Ein Sicherheitsteam überwacht den Datenverkehr über die Analytics-API. Wenn Angriffsmuster auftreten, werden Firewall-Regeln über die API hinzugefügt, um bösartige IPs zu blockieren, was die Reaktionszeit von Stunden auf Sekunden reduziert.

Zusammenfassung

Das haben Sie gelernt:

Sich mit API-Tokens für bereichsbezogenen Zugriff zu authentifizieren
Zonen und DNS-Einträge programmgesteuert zu verwalten
Workers für Edge Computing bereitzustellen
Sicherheit mit Firewall-Regeln und Ratenbegrenzung zu konfigurieren
Analysen abzurufen und Protokollversand zu konfigurieren
Mit Apidog zu testen, bevor die Änderungen in Produktion gehen

button

FAQ

Was ist der Unterschied zwischen einer Zone und einer Domain? Eine Zone ist die Cloudflare-Darstellung einer Domain. Wenn Sie eine Domain zu Cloudflare hinzufügen, erstellen Sie eine Zone. Die Zonen-ID wird in API-Aufrufen für diese Domain verwendet.

Wie finde ich meine Zonen-ID? Gehen Sie zum Cloudflare Dashboard → wählen Sie Ihre Domain → Übersicht → scrollen Sie zum API-Bereich. Die Zonen-ID wird dort angezeigt.

Kann ich die Cloudflare API ohne einen kostenpflichtigen Plan nutzen? Ja. Die meisten API-Funktionen funktionieren mit kostenlosen Plänen. Workers haben einen großzügigen kostenlosen Tarif. Einige erweiterte Funktionen (erweiterte WAF-Regeln, Logpush) erfordern kostenpflichtige Pläne.

Wie lange dauern DNS-Änderungen? Änderungen über die API sind im Cloudflare-System sofort wirksam. Die Verbreitung auf die Cloudflare-Nameserver dauert Sekunden. Die globale Verbreitung hängt von TTL und rekursiven Resolvern ab, typischerweise Minuten.

Was ist die Ratenbegrenzung? Standard: 1200 Anfragen pro 5 Minuten pro Token. Überprüfen Sie den Header X-RateLimit-Remaining. Enterprise-Pläne haben höhere Limits.

Kann ich mehrere Konten mit einem Token verwalten? Nein. Tokens sind auf ein Konto beschränkt. Für mehrere Konten erstellen Sie separate Tokens oder verwenden Sie Tokens auf Benutzerebene mit Zugriff auf mehrere Konten.

Wie unterscheiden sich Workers von Lambda? Workers laufen an den Edge-Standorten von Cloudflare (über 300 Städte), nicht in bestimmten Regionen. Kaltstarts sind minimal. Sie sind ideal für die Bearbeitung von Anfragen/Antworten, nicht für lang laufende Prozesse.

Kann ich die API verwenden, um den Cache zu leeren? Ja:

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