Cloudflare API の使い方

要約 (TL;DR)

Cloudflare APIを使用すると、DNS、ゾーン、Workers、セキュリティ、分析などをプログラムで管理できます。APIトークン（推奨）またはグローバルキーで認証し、api.cloudflare.com/client/v4を呼び出し、レート制限に適切に対処してください。テストには、Apidogを使用してDNS変更を検証し、Workerのデプロイをテストし、環境間の設定を自動化できます。

はじめに

Cloudflareは何百万ものウェブサイトの前に存在しています。DNS、CDN、DDoS保護、WAF、Workersサーバーレス機能などを扱っています。ダッシュボードを通じてすべてを管理するのは、小規模な設定ではうまくいきます。しかし、大規模な場合は自動化が必要です。

Cloudflare APIは、ダッシュボードが提供するすべての機能をカバーしています。ゾーンの作成、DNSレコードの更新、ページルールの設定、Workersのデプロイ、SSL設定の管理、分析データの取得など、すべてプログラムで行うことができます。

開発者はCloudflareのAPIを以下の目的で使用しています。

コードとしてのインフラ (Terraform、Pulumi)
CI/CDパイプラインとの統合
複数ゾーンの管理
自動DNS更新
Workerのデプロイ

💡

Cloudflare上で構築している場合、ApidogはAPI呼び出しのテスト、レスポンスの検証、統合のドキュメント化に役立ちます。ゾーン構成を再利用可能なリクエストとして保存し、チームと共有できます。

button

ApidogでCloudflare APIをテスト — 無料

このガイドを読み終えるまでに、次のことができるようになります。

Cloudflare APIトークンで認証する
ゾーンとDNSレコードを管理する
Workersをデプロイおよび管理する
セキュリティ設定を構成する
分析とログを取得する

認証

Cloudflareは2つの認証方法を提供しています。APIトークンを使用し、グローバルキーは使用しないでください。

方法1：APIトークン（推奨）

APIトークンは特定の権限にスコープが設定されています。トークンが侵害された場合でも、被害は限定的です。

トークンの作成:

Cloudflareダッシュボード → マイプロフィール → APIトークンに移動
トークンを作成
テンプレート（ゾーンDNSの編集、Workersのデプロイなど）またはカスタムを選択
特定のゾーンまたはすべてのゾーンを設定
トークンをコピー

トークンの使用:

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

方法2：グローバル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": []
}

resultを処理する前に、常にsuccessを確認してください。

ゾーン管理

ゾーンは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を実行します。

Workerのリスト表示

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ネームスペース

Workerからアクセス可能なデータを保存します。

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の変更は本番トラフィックに影響を与えます。徹底的にテストしてください。

Apidogのテストインターフェースのスクリーンショット。テストケース、リクエスト、レスポンスの検証、コード例が表示されている。

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

ApidogでCloudflare APIをテスト — 無料

一般的なエラーと修正

403 Forbidden

原因: トークンに必要な権限がありません。

修正: Cloudflareダッシュボードでトークンの権限を確認します。DNS編集にはZone:DNS:Editが必要です。WorkersにはAccount:Workers:Editが必要です。

1003: 無効または不足しているゾーン

原因: ゾーンIDが存在しないか、トークンがアクセスできません。

修正: URL内のゾーンIDを確認し、トークンのスコープにこのゾーンが含まれているかを確認します。

81057: レコードがすでに存在します

原因: 同じ名前とタイプのDNSレコードがすでに存在します。

修正: 作成するためにPOSTを使用する代わりに、更新するためにPUTを使用するか、まず削除します。

レート制限超過

原因: リクエストが多すぎます（デフォルトは5分間に1200回）。

修正: バックオフとバッチ操作を実装します。

async function updateRecords(records) {
  for (const record of records) {
    try {
      await updateRecord(record)
      await sleep(100) // レート制限バッファ
    } catch (error) {
      if (error.status === 429) {
        await sleep(60000) // 1分待機
        await updateRecord(record) // 再試行
      }
    }
  }
}

代替案と比較

機能	Cloudflare	AWS Route 53	Fastly
DNS API	✓	✓	✓
CDN API	✓	CloudFront API	✓
エッジ関数	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証明書は自動的にプロビジョニングされます。

ブルーグリーンデプロイメント。 エンジニアリングチームは、DNSレコードの更新を使用して環境間のトラフィックを切り替えます。APIはデプロイ中にAレコードを更新し、Cloudflareネットワークを介して即座に伝播されます。

DDoS対策の自動化。 セキュリティチームは、分析APIを介してトラフィックを監視します。攻撃パターンが検出されると、APIを介してファイアウォールルールが追加され、悪意のあるIPアドレスがブロックされ、対応時間が数時間から数秒に短縮されます。

まとめ

学んだことは次のとおりです。

スコープ付きアクセス用のAPIトークンで認証する
ゾーンとDNSレコードをプログラムで管理する
エッジコンピューティングのためにWorkersをデプロイする
ファイアウォールルールとレート制限でセキュリティを構成する
分析を取得し、ログ転送を構成する
本番環境に適用する前にApidogでテストする

button

よくある質問 (FAQ)

ゾーンとドメインの違いは何ですか？ゾーンはCloudflareにおけるドメインの表現です。ドメインをCloudflareに追加すると、ゾーンが作成されます。そのドメインに対するAPI呼び出しではゾーンIDが使用されます。

ゾーンIDはどこで確認できますか？Cloudflareダッシュボード → ドメインを選択 → 概要 → APIセクションまでスクロールしてください。そこにゾーンIDが表示されています。

有料プランなしでCloudflare APIを使用できますか？はい。ほとんどのAPI機能は無料プランで動作します。Workersには寛大な無料枠があります。一部の高度な機能（高度なWAFルール、Logpush）には有料プランが必要です。

DNS変更にはどのくらいの時間がかかりますか？API経由での変更はCloudflareシステム内で即座に行われます。Cloudflareネームサーバーへの伝播は数秒です。グローバルな伝播はTTLと再帰リゾルバーに依存し、通常は数分です。

レート制限はありますか？デフォルト: トークンあたり5分間に1200リクエストです。X-RateLimit-Remainingヘッダーを確認してください。エンタープライズプランでは上限が高くなります。

1つのトークンで複数のアカウントを管理できますか？いいえ。トークンは1つのアカウントにスコープが設定されています。複数のアカウントを管理するには、個別のトークンを作成するか、複数のアカウントにアクセスできるユーザーレベルのトークンを使用します。

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