Bevezetés és kontextus
A munkám során egy Laravel eszközt kellett létrehoznom, amely lehetővé teszi webhelyeink Cloudflare-en tárolt statisztikáinak lekérését. Először a Cloudflare webhelyén kerestem az API dokumentációt, valamint a PHP-kompatibilis könyvtárakat.
A Cloudflare hivatalos PHP SDK-jának tesztelése során gyorsan két dologra jöttem rá: a Cloudflare nem tűnik elkötelezettnek ennek az SDK-nak a hosszú távú fenntartása mellett, és a régi REST végpontok egy részét GraphQL végpontok váltották fel.
Miért blokkolt a GraphQL
Mivel korábban soha nem használtam GraphQL API-t, a dokumentációban kezdtem el keresni a végpontokat, ahogy egy REST API esetében tenném.
Itt kezdtem elveszteni. A jól strukturált REST dokumentációval ellentétben nehéz volt megérteni a mezőneveket, argumentumokat, időszakokat, és különösen az egyes csomagokhoz tartozó engedélyeket és korlátokat.
Telepítettem egy GraphQL klienst (Altair) a lekérdezések közvetlen teszteléséhez.
Ekkor fedeztem fel egy érdekes funkciót: az introspekciót.
Egyszerűsítve, ez lehetővé teszi a kliens számára, hogy lekérje a GraphQL sémát a szerverről, hogy felfedezze az elérhető lekérdezéseket, típusokat, mezőket, argumentumokat és mutációkat.
Az elméletben tökéletes volt. A gyakorlatban félrevezető volt: az introspekció nem ismeri az egyes zónák tényleges engedélyeit, sem az ingyenes, pro, business vagy vállalati csomagokra vonatkozó korlátokat. Az Altair tehát látszólag "érvényes" lekérdezéseket generált, de gyakran túl sok argumentummal vagy olyan mezőkkel, amelyekhez nem volt hozzáférésem.
A jó REST dokumentációval ellentétben a GraphQL gyakran megköveteli, hogy önállóan kiderítsd:
- a szükséges engedély szintet
- a ténylegesen elérhető adatokat
- az elfogadott időszakokat
- az adott csomag szerint használható szűrőket
Ez generálja a következő GraphQL lekérdezést:
query ASingleDatasetExample($zoneTag: string, $start: Time, $end: Time) {
viewer {
zones(filter: { zoneTag: $zoneTag }) {
firewallEventsAdaptiveByTimeGroups {
avg {
sampleInterval
}
confidence(level: "_____") {
count {
estimate
isValid
lower
sampleSize
upper
}
level
}
count
dimensions {
apiGatewayMatchedEndpoint
apiGatewayMatchedHost
attackSignatureCategories
attackSignatureRefs
botDetectionIds
botDetectionTags
botScore
botScoreSrcName
date
datetime
datetimeFifteenMinutes
datetimeFiveMinutes
datetimeHour
datetimeMinute
description
firewallForAiAnyPiiCategory
firewallForAiCustomTopicCategoriesScoresMin
firewallForAiInjectionScore
firewallForAiPiiCategories
firewallForAiUnsafeTopicCategories
fraudAttack
fraudDetectionIds
fraudDetectionTags
fraudEmailRisk
fraudEventType
fraudUserId
httpApplicationVersion
ja3Hash
ja4
jsDetectionPassed
verifiedBotCategory
wafAttackScore
wafAttackScoreClass
wafMlAttackScore
wafMlSqliAttackScore
wafMlXssAttackScore
wafPathTraversalAttackScore
wafRceAttackScore
wafSqliAttackScore
wafXssAttackScore
zoneVersion
}
sum {
botDetectionIdArray
botDetectionIdCountArray
botDetectionTagArray
botDetectionTagCountArray
fraudDetectionIdArray
fraudDetectionIdCountArray
fraudDetectionTagArray
fraudDetectionTagCountArray
}
}
}
}
}
Amiből háromnegyede vállalati adat!
Tesztelhetjük és lépésről lépésre eltávolíthatjuk azokat a mezőket és dimenziókat, amelyekhez nincs hozzáférésünk, hogy egy működő lekérdezést kapjunk.
query ASingleDatasetExample($zoneTag: string, $start: Time, $end: Time) {
viewer {
zones(filter: { zoneTag: $zoneTag }) {
firewallEventsAdaptiveByTimeGroups(
filter: { datetime_gt: $start, datetime_lt: $end }
limit: 2
orderBy: [datetime_DESC]
) {
avg {
sampleInterval
}
count
dimensions {
date
datetime
datetimeFifteenMinutes
datetimeFiveMinutes
datetimeHour
datetimeMinute
description
firewallForAiAnyPiiCategory
firewallForAiCustomTopicCategoriesScoresMin
firewallForAiInjectionScore
firewallForAiPiiCategories
firewallForAiUnsafeTopicCategories
httpApplicationVersion
verifiedBotCategory
zoneVersion
}
}
}
}
}
A Cloudflare MCP felfedezése
Ahogyan a dokumentációban kerestem a korlátokat és kényszereket, rábukkantam a Cloudflare MCP GraphQL oldalára. A README-ben nagyon hasznos példa promtok voltak, például:
Show me HTTP traffic for the last 7 days for example.comShow me which GraphQL datatype I need to use to query firewall events
Azonnal megtetszett az ötlet: ahelyett, hogy órákat töltenék a megfelelő mezők és kombinációk kitalálásával, egy AI eszköz felfedezhette a sémát, és ténylegesen a kontextusommal kompatibilis lekérdezéseket javasolhatott.
Kísérlet a Playgrounddel
Az MCP felfedezésekor láttam, hogy a Cloudflare egy Playgroundot is kínál chat formában. Csatlakoztattam a GraphQL MCP-t, és elkezdetem írni a README-ből származó promtokat.
De katasztrófa következett: a Playground túl instabil volt az esetemben. Amikor megpróbáltam statisztikákat lekérni az egyik tartományomhoz, néha biztonsági hibákat vagy használhatatlan válaszokat kaptam.
Még amikor kifejezetten kértém, hogy használja a Cloudflare MCP-t, az eredmény gyakran körbe-körbe ment: kísérlet HTTP-n keresztül, rossz kontextum értelmezés, vagy lekérdezések, amelyek nem fejeződtek be.
Gyorsan elhagytam ezt az irányt, és áttértem a Claude Code-ra.
Áttérés a Claude Code-ra
A GraphQL MCP hozzáadásához a Claude Code-ban a következővel csatlakoztathatod:
claude mcp add --transport sse cloudflare-graphql https://graphql.mcp.cloudflare.com/sse
Ezután authenticate az MCP beállításaiban.
:::info Ha több napon keresztül használja, rendszeresen ellenőrizze, hogy a kapcsolat továbbra is érvényes-e.
:::
Miután csatlakozott, újra megpróbáltam lekérni az eredetileg keresett adatokat.
És ezúttal működött: megkaptam a megfelelő lekérdezéseket, tesztelve az én csomagommal, a megfelelő mezőkkel és paraméterekkel. A leghasznosabb az volt, hogy végre voltak olyan lekérdezéseim, amelyeket beépíthettem az alkalmazásomba.
Mit tanultam
Az MCP valódi előnye nem csupán a "lekérdezés generálása". Az előny különösen a túl absztrakt GraphQL dokumentáció értelmezésével elvesztegetett idő csökkentése.
Az esetemben segített:
- azonosítani a megfelelő mezőket
- megérteni az én csomagomhoz kapcsolódó kényszereket
- tesztelni a paramétereket az integráció előtt
- elkerülni a túl ambiciózus vagy érvénytelen lekérdezéseket
Tippek a Cloudflare GraphQL API-hoz
Ha megvalósítja ezt az API-t, tartsa szem előtt a korlátait. A Cloudflare dokumentációja szerint a GraphQL Analytics API aggregált adatokhoz készült, és az alapértelmezett korlátok közé tartozik különösen 300 kérés 5 perces ablakban, és maximum 10 zóna egy zóna-hatóságú lekérdezéshez.
Ha több zóna adatait kell lekérnie, a legtisztább megközelítés 10 zóna kötegekben való munka. Ez nagymértékben csökkenti a kérések teljes számát, és elkerüli a korlátok felesleges érintését.
Lekérdezés példa
Miután a logika megértetett, az érdekes rész a kódba integrálás válik. Íme egy példa a GraphQL lekérdezés szerkezetre, amelyet stabilizálni tudtam az MCP-vel végzett tesztek után:
query FirewallByTimeBatch(
$zoneTags: [string!]
$start: Time
$end: Time
) {
viewer {
zones(filter: { zoneTag_in: $zoneTags }) {
zoneTag
firewallEventsAdaptiveByTimeGroups(
filter: {
datetime_geq: $start
datetime_lt: $end
action: "block"
}
limit: 1000
orderBy: [datetimeHour_ASC]
) {
dimensions {
datetimeHour
}
count
}
}
}
}
# variables
{
"zoneTags": [
"abc123",
"abc456"
],
"start": "2026-05-11T02:07:05Z",
"end": "2026-05-11T17:07:05Z"
}
A cél nem a legelegánsabb lekérdezés volt, hanem a megfelelő lekérdezés a tényleges szükségemhez.
Gyakorlati következtetés
A Cloudflare GraphQL API továbbra is hatékony, de a dokumentációja clearly több erőfeszítést igényel, mint egy jól megjelölt REST API. Ha nem biztos a GraphQL-ben, tanácsolom, hogy ne töltson túl sok időt a mezők és kényszerek manuális kitalálásával.
Helyette használja a Cloudflare MCP-t a fejlesztői környezetében. Hagyja az AI-t felfedezni a sémát, tesztelni az engedélyeket az előfizetése szerint, majd generálni a lekérdezéseket, amelyeket beépíthet a projektjébe.
Véleményem szerint ez a leggyorsabb módja annak, hogy a zavaros dokumentációból a ténylegesen használható lekérdezésekhez jusson.