Cloudflare GraphQL API 완전정복

WAF 로그부터 DDoS, 트래픽까지 실시간 분석을 내 손안에!

Cloudflare를 사용하는 실무자라면 꼭 알아야 할 고급 기능, 바로 Cloudflare GraphQL Analytics API입니다.
기존 REST API의 한계를 넘어, 유연하고 실시간성 높은 데이터 분석이 가능한 이 API는
보안 운영, 모니터링, 트래픽 분석에 있어 엄청난 생산성을 제공합니다.

---

🧠 GraphQL이란?

GraphQL은 Facebook이 개발한 **API 질의 언어(Query Language)**로,
REST 방식처럼 여러 Endpoint를 호출하는 대신 한 번의 요청으로 원하는 데이터만 정확히 조회할 수 있게 해줍니다.

🔍 REST vs GraphQL

구분REST APIGraphQL API

요청 방식	여러 URL 호출	단일 Endpoint (/graphql)
응답 데이터	고정된 구조	필요한 필드만 선택
확장성	Endpoint 증가 부담	스키마 중심 확장 가능

 

---

🌐 Cloudflare GraphQL API란?

Cloudflare는 자체적으로 구축한 GraphQL API를 통해
WAF 로그, Firewall 이벤트, DNS 요청, Load Balancer 상태, DDoS 방어 기록 등
다양한 보안 및 트래픽 데이터를 실시간으로 쿼리할 수 있게 제공합니다.

📌 특징 요약

• 단일 Endpoint: https://api.cloudflare.com/client/v4/graphql
• Bearer Token 인증 방식
• 데이터 분석용 API (읽기 전용)
• 쿼리 구조는 JSON 형태로 POST 전송
• 최대 7일치 데이터 조회 가능
• Account 또는 Zone 단위 지정 가능

---

🧪 기본 쿼리 예시

✅ 1. WAF 로그 조회

query {
  viewer {
    zones(filter: {zoneTag: "your_zone_id"}) {
      firewallEventsAdaptive(limit: 10) {
        action
        clientIP
        userAgent
        datetime
        source
        ruleId
      }
    }
  }
}

🔐 Tip: your_zone_id는 실제 사용하는 도메인의 Zone ID로 바꿔야 합니다.

---

✅ 2. 트래픽 통계 요약

query {
  viewer {
    zones(filter: {zoneTag: "your_zone_id"}) {
      httpRequests1dGroups(limit: 7, filter: {date_gt: "2025-06-01"}) {
        sum {
          bytes
          requests
        }
        dimensions {
          date
        }
      }
    }
  }
}

---

🧩 실무에서 이렇게 씁니다

☑️ 보안 운영팀

• 차단된 WAF Rule ID별 통계 추출
• IP별 Firewall 액션 분석

☑️ DevOps/SRE

• 특정 리전의 응답 속도 변화 추적
• DNS 에러 비율 모니터링

☑️ 대시보드 자동화

• Python + requests로 주기적 쿼리
• Grafana, Metabase 등 BI 도구와 연동

---

💡 Python에서 사용하는 간단 예시

 

import requests

url = "https://api.cloudflare.com/client/v4/graphql"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
query = """
query {
  viewer {
    zones(filter: {zoneTag: "YOUR_ZONE_ID"}) {
      firewallEventsAdaptive(limit: 5) {
        action
        clientIP
        datetime
      }
    }
  }
}
"""

response = requests.post(url, json={"query": query}, headers=headers)
print(response.json())

---

📘 참고 링크

• 공식 문서: https://developers.cloudflare.com/graphql
• 스키마 탐색기: Cloudflare GraphQL Explorer (로그인 필요)
• 토큰 생성: https://dash.cloudflare.com/profile/api-tokens