كيفية استخدام واجهات برمجة تطبيقات Cloudflare

الخلاصة

تسمح لك واجهات برمجة تطبيقات Cloudflare بإدارة DNS والنطاقات وWorkers والأمان والتحليلات برمجيًا. قم بالمصادقة باستخدام رموز API المميزة (موصى بها) أو المفاتيح العامة، وقم باستدعاء api.cloudflare.com/client/v4، وتعامل مع حدود المعدل برشاقة. للاختبار، استخدم Apidog للتحقق من تغييرات DNS، واختبار عمليات نشر Worker، وأتمتة التكوين عبر البيئات المختلفة.

مقدمة

تقف Cloudflare أمام ملايين مواقع الويب. تتولى مسؤولية DNS، وشبكة توصيل المحتوى (CDN)، وحماية من هجمات الحرمان من الخدمات الموزعة (DDoS)، وجدار حماية تطبيقات الويب (WAF)، ووظائف Workers الخالية من الخادم، والمزيد. إدارة كل ذلك من خلال لوحة التحكم تعمل للإعدادات الصغيرة. ولكن على نطاق واسع، تحتاج إلى الأتمتة.

تغطي واجهة برمجة تطبيقات Cloudflare كل ما تفعله لوحة التحكم. يمكنك إنشاء النطاقات، وتحديث سجلات DNS، وتكوين قواعد الصفحات، ونشر Workers، وإدارة إعدادات SSL، وسحب التحليلات. كل ذلك برمجيًا.

يستخدم المطورون واجهة برمجة تطبيقات Cloudflare من أجل:

البنية التحتية كتعليمات برمجية (Terraform، Pulumi)
تكامل خط أنابيب CI/CD
إدارة النطاقات المتعددة
تحديثات DNS المؤتمتة
نشر Workers

💡

إذا كنت تبني على Cloudflare، يساعدك Apidog في اختبار استدعاءات API، والتحقق من الاستجابات، وتوثيق تكاملك. يمكنك حفظ تكوينات النطاقات كطلبات قابلة لإعادة الاستخدام ومشاركتها مع فريقك.

زر

اختبر واجهات برمجة تطبيقات Cloudflare باستخدام Apidog - مجانًا

بنهاية هذا الدليل، ستكون قادرًا على:

المصادقة باستخدام رموز Cloudflare API المميزة
إدارة النطاقات وسجلات DNS
نشر وإدارة Workers
تكوين إعدادات الأمان
سحب التحليلات والسجلات

المصادقة

توفر Cloudflare طريقتين للمصادقة. استخدم رموز API المميزة، وليس المفاتيح العامة.

الطريقة الأولى: رموز API المميزة (موصى بها)

تقتصر رموز API المميزة على أذونات محددة. إذا تم اختراق رمز مميز، يكون الضرر محدودًا.

إنشاء رمز مميز:

انتقل إلى لوحة تحكم Cloudflare ← ملفي الشخصي ← رموز API المميزة
إنشاء رمز مميز
اختر قالبًا (تعديل DNS النطاق، نشر Workers، إلخ) أو مخصصًا
حدد نطاقات معينة أو جميع النطاقات
انسخ الرمز المميز

استخدام الرمز المميز:

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

الطريقة الثانية: مفتاح API العام (غير موصى به)

يتمتع المفتاح العام بوصول كامل إلى الحساب. تجنب استخدامه.

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"

تنسيق الاستجابة

تتبع جميع استجابات Cloudflare API هذا الهيكل:

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

تحقق دائمًا من success قبل معالجة result.

إدارة النطاقات

تمثل النطاقات (Zones) المجالات في Cloudflare.

قائمة النطاقات

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

الاستجابة:

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

إنشاء نطاق

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

الحصول على تفاصيل النطاق

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

إدارة سجلات DNS

تربط سجلات DNS أسماء النطاقات بعناوين IP والخدمات.

قائمة سجلات DNS

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

إنشاء سجل 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
  }'

أنواع السجلات:

A - عنوان IPv4
AAAA - عنوان IPv6
CNAME - اسم مستعار لنطاق آخر
MX - خادم البريد
TXT - سجلات نصية (SPF، DKIM، التحقق)
NS - خادم الاسم

تحديث سجل 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
  }'

حذف سجل 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 بـ JavaScript على الحافة، بالقرب من المستخدمين.

قائمة Workers

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

تحميل 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

مثال على 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)
  }
}

ربط مسار

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

تخزين البيانات التي يمكن الوصول إليها من 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"
  }'

الأمان و WAF

قواعد الصفحات

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

قواعد جدار الحماية

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

تحديد المعدل

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

التحليلات والسجلات

تحليلات النطاق

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

الاستجابة:

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

سجلات النطاق (Logpush)

قم بتمكين Logpush لإرسال السجلات إلى تخزينك:

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

تؤثر تغييرات Cloudflare على حركة المرور الإنتاجية. اختبر بدقة.

1. إعداد البيئة

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

2. التحقق من صحة الاستجابات

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

احفظ نصوص Worker كملفات في Apidog واختبر التحميلات:

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

اختبر واجهات برمجة تطبيقات Cloudflare باستخدام Apidog - مجانًا

الأخطاء الشائعة والإصلاحات

403 ممنوع

السبب: يفتقر الرمز المميز إلى الإذن المطلوب.

الإصلاح: تحقق من أذونات الرمز المميز في لوحة تحكم Cloudflare. تتطلب تعديلات DNS إذن Zone:DNS:Edit. تتطلب Workers إذن Account:Workers:Edit.

1003: نطاق غير صالح أو مفقود

السبب: معرف النطاق غير موجود أو لا يمكن للرمز المميز الوصول إليه.

الإصلاح: تحقق من معرف النطاق في عنوان URL وتأكد من أن نطاق الرمز المميز يتضمن هذا النطاق.

81057: السجل موجود بالفعل

السبب: سجل DNS بنفس الاسم والنوع موجود بالفعل.

الإصلاح: استخدم PUT للتحديث بدلاً من POST للإنشاء، أو احذف السجل أولاً.

تجاوز حد المعدل

السبب: عدد كبير جدًا من الطلبات (الافتراضي 1200 طلب / 5 دقائق).

الإصلاح: نفذ التراجع (backoff) وعمليات الدفعات (batch operations).

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

البدائل والمقارنات

الميزة	Cloudflare	AWS Route 53	Fastly
DNS API	✓	✓	✓
CDN API	✓	CloudFront API	✓
وظائف الحافة (Edge functions)	Workers	Lambda@Edge	Compute@Edge
WAF API	✓	AWS WAF	✓
الخطة المجانية	سخية	الدفع حسب الاستخدام	محدودة
تنسيق الاستجابة	JSON	XML/JSON	JSON

واجهة برمجة تطبيقات Cloudflare أكثر توحيدًا من خدمات AWS المجزأة. توفر Workers مرونة أكبر من Lambda@Edge.

حالات الاستخدام الحقيقية

SaaS متعدد المستأجرين. تقوم منصة بإنشاء نطاقات Cloudflare تلقائيًا عندما يضيف العملاء نطاقات مخصصة. تتولى Workers توجيه الطلبات، ويتم إنشاء سجلات DNS عبر API، ويتم توفير شهادات SSL تلقائيًا.

عمليات النشر الأزرق والأخضر (Blue-green deployments). يستخدم فريق هندسي تحديثات سجلات DNS لتبديل حركة المرور بين البيئات. تقوم واجهة برمجة التطبيقات بتحديث سجلات A أثناء النشر، مع انتشار فوري عبر شبكة Cloudflare.

أتمتة الاستجابة لهجمات DDoS. يراقب فريق أمني حركة المرور عبر واجهة برمجة تطبيقات التحليلات. عندما تظهر أنماط هجومية، تتم إضافة قواعد جدار الحماية عبر API لحظر عناوين IP الضارة، مما يقلل وقت الاستجابة من ساعات إلى ثوانٍ.

الخلاصة

إليك ما تعلمته:

المصادقة باستخدام رموز API المميزة للوصول المحدد النطاق
إدارة النطاقات وسجلات DNS برمجيًا
نشر Workers للحوسبة على الحافة
تكوين الأمان باستخدام قواعد جدار الحماية وتحديد المعدل
سحب التحليلات وتكوين إرسال السجلات
الاختبار باستخدام Apidog قبل التطبيق على الإنتاج

زر

الأسئلة الشائعة

ما الفرق بين النطاق (zone) والمجال (domain)؟النطاق (zone) هو تمثيل Cloudflare للمجال. عندما تضيف مجالًا إلى Cloudflare، فإنك تنشئ نطاقًا (zone). يُستخدم معرف النطاق (zone ID) في استدعاءات API لهذا المجال.

كيف أجد معرف النطاق الخاص بي؟اذهب إلى لوحة تحكم Cloudflare ← حدد نطاقك ← نظرة عامة ← مرر لأسفل إلى قسم API. سيظهر معرف النطاق هناك.

هل يمكنني استخدام Cloudflare API بدون خطة مدفوعة؟نعم. معظم ميزات API تعمل على الخطط المجانية. لدى Workers طبقة مجانية سخية. تتطلب بعض الميزات المتقدمة (قواعد WAF المتقدمة، Logpush) خططًا مدفوعة.

كم يستغرق تغييرات DNS؟التغييرات عبر API فورية في نظام Cloudflare. يستغرق الانتشار إلى خوادم أسماء Cloudflare ثوانٍ. يعتمد الانتشار العالمي على TTL والمحللات المتكررة، وعادة ما يستغرق دقائق.

ما هو حد المعدل؟الافتراضي: 1200 طلب لكل 5 دقائق لكل رمز مميز. تحقق من رأس X-RateLimit-Remaining. الخطط المؤسسية لديها حدود أعلى.

هل يمكنني إدارة حسابات متعددة برمز مميز واحد؟لا. تقتصر الرموز المميزة على حساب واحد. لإدارة حسابات متعددة، أنشئ رموزًا مميزة منفصلة أو استخدم رموزًا مميزة على مستوى المستخدم مع وصول إلى حسابات متعددة.

كيف تختلف Workers عن Lambda؟تعمل Workers في مواقع حافة Cloudflare (أكثر من 300 مدينة)، وليس في مناطق محددة. أوقات البدء الباردة ضئيلة. إنها مثالية لمعالجة الطلبات/الاستجابات، وليست للعمليات طويلة الأمد.

هل يمكنني استخدام API لمسح ذاكرة التخزين المؤقت؟نعم:

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