DEV Community

Cover image for كيفية استخدام واجهات برمجة تطبيقات Cloudflare
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

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

#api #automation #cloud #tutorial

الخلاصة

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

جرّب Apidog اليوم

مقدمة

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

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

أمثلة استخدام Cloudflare API:

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

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

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

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

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

المصادقة

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

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

الأفضلية للرموز المميزة لأنها محددة الصلاحيات. في حال الاختراق يكون الأثر محدودًا.

خطوات إنشاء رمز مميز:

  1. انتقل إلى لوحة تحكم Cloudflare ← ملفي الشخصي ← رموز API المميزة
  2. أنشئ رمزًا جديدًا
  3. اختر قالبًا (تعديل DNS، نشر Workers، إلخ) أو عرّف الصلاحيات يدويًا
  4. حدد النطاقات المستهدفة
  5. انسخ الرمز المميز

الاستخدام:

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

الطريقة الثانية: مفتاح 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"
Enter fullscreen mode Exit fullscreen mode

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

كل استجابة من Cloudflare API تتبع البنية التالية:

{
  "result": { ... },
  "success": true,
  "errors": [],
  "messages": []
}
Enter fullscreen mode Exit fullscreen mode

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

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

كل مجال في Cloudflare يسمى Zone.

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

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

استجابة نموذجية:

{
  "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
}
Enter fullscreen mode Exit fullscreen mode

إنشاء نطاق 

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"
  }'
Enter fullscreen mode Exit fullscreen mode

تفاصيل نطاق 

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

إدارة سجلات DNS

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

قائمة السجلات 

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

إنشاء سجل جديد 

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
  }'
Enter fullscreen mode Exit fullscreen mode

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

  • A: عنوان IPv4
  • AAAA: عنوان IPv6
  • CNAME: اسم مستعار
  • MX: خادم البريد
  • TXT: نصوص (SPF، DKIM)
  • NS: خوادم الأسماء

تحديث سجل 

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
  }'
Enter fullscreen mode Exit fullscreen mode

حذف سجل 

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

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"
Enter fullscreen mode Exit fullscreen mode

تحميل 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
Enter fullscreen mode Exit fullscreen mode

مثال 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)
  }
}
Enter fullscreen mode Exit fullscreen mode

ربط Worker بمسار 

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"
  }'
Enter fullscreen mode Exit fullscreen mode

إنشاء مساحة اسم Worker KV 

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"
  }'
Enter fullscreen mode Exit fullscreen mode

الأمان و 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"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

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

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"
  }'
Enter fullscreen mode Exit fullscreen mode

تحديد المعدل 

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
    }
  }'
Enter fullscreen mode Exit fullscreen mode

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

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

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

استجابة:

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

تفعيل 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"
  }'
Enter fullscreen mode Exit fullscreen mode

الاختبار باستخدام Apidog

أي تغيير في إعدادات Cloudflare يؤثر على الإنتاج. اختبر كل شيء برمجياً أولاً.

صورة

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

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

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
})
Enter fullscreen mode Exit fullscreen mode

3. اختبار عمليات نشر Worker

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

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

اختبر Cloudflare API باستخدام Apidog - مجانًا.

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

403 ممنوع

  • السبب: الرمز المميز يفتقر إلى الإذن المطلوب.
  • الإصلاح: تحقق من أذونات الرمز المميز. تعديلات DNS تحتاج Zone:DNS:Edit. Workers تحتاج Account:Workers:Edit.

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

  • السبب: معرف النطاق غير صحيح أو الرمز المميز لا يملك صلاحية عليه.
  • الإصلاح: تحقق من معرف النطاق وتأكد من أن الرمز المميز يغطي هذا النطاق.

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

  • السبب: يوجد سجل DNS بنفس الاسم والنوع.
  • الإصلاح: استخدم PUT للتحديث أو احذف السجل أولاً.

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

  • السبب: عدد الطلبات تجاوز الحد (الافتراضي 1200 طلب / 5 دقائق).
  • الإصلاح: نفذ التراجع (backoff) والعمليات الدُفعية (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) // انتظر دقيقة
        await updateRecord(record) // أعد المحاولة
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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

الميزة 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 API أكثر توحيدًا من خدمات AWS المجزأة. Workers توفر مرونة أكبر من Lambda@Edge.

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

  • SaaS متعدد المستأجرين: منصة تقوم بإنشاء نطاقات Cloudflare تلقائيًا عند إضافة العملاء لنطاقاتهم. Workers توجه الطلبات، وسجلات DNS تنشأ تلقائيًا عبر API، وشهادات SSL تُوفَر تلقائيًا.
  • Blue-green deployments: فريق يستخدم تحديث سجلات DNS لنقل حركة المرور بين بيئات الإنتاج. التغيير يتم عبر API وينتشر فورًا.
  • أتمتة الاستجابة لهجمات DDoS: فريق يراقب التحليلات عبر API، وعند ظهور نمط هجوم، تُضاف قواعد جدار حماية تلقائيًا عبر API لحظر العناوين الضارة.

الخلاصة

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

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

ما الفرق بين النطاق (zone) والمجال (domain)؟

النطاق (zone) هو تمثيل Cloudflare للمجال. عند إضافة مجال جديد، يتم إنشاء zone خاص به ويُستخدم معرفه في استدعاءات API.

كيف أجد معرف النطاق؟

لوحة تحكم Cloudflare ← اختر النطاق ← نظرة عامة ← قسم API.

هل يمكن استخدام Cloudflare API مجانًا؟

نعم، معظم الميزات متاحة في الخطة المجانية. بعض الوظائف المتقدمة تتطلب خطة مدفوعة.

كم يستغرق تغييرات DNS؟

التغييرات عبر API فورية في نظام Cloudflare. الانتشار العالمي يعتمد على TTL وغالبًا يستغرق دقائق.

ما هو حد المعدل؟

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

هل يمكن إدارة حسابات متعددة برمز واحد؟

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

ما الفرق بين Workers و Lambda؟

Workers تعمل على أكثر من 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"]
  }'
Enter fullscreen mode Exit fullscreen mode

Top comments (0)