← Analytics / analytics / analytics-engine

SQL API

Workers Analytics Engine SQL API je HTTP API, které umožňuje spouštět SQL dotazy nad vašimi datovými sadami Workers Analytics Engine.

Toto API je dostupné na adrese https://api.cloudflare.com/client/v4/accounts/<account_id>/analytics_engine/sql.

Ověřování probíhá pomocí bearer tokenu. Authorization: Bearer <token> hlavička musí být uvedena v každém požadavku na rozhraní API.

Pomocí dashboardu vytvořte token s oprávněním číst analytická data vašeho účtu:

1. Navštivte API tokeny ↗ stránku v Cloudflare dashboardu.
2. Vyberte Create Token.
3. Vyberte Create Custom Token.
4. Dokončete Create Custom Token tvar takto:
   • Dejte svému tokenu výstižný název.
   • Pro Oprávnění vybrat Účet | Account Analytics | Čtení
   • Volitelně můžete nastavit omezení účtu a IP adres a TTL.
   • Odešlete a potvrďte formulář pro vytvoření tokenu.
5. Poznamenejte si řetězec tokenu.

Text dotazu odešlete v těle POST požadavek na adresu API. Formát vrácených dat lze vybrat pomocí FORMAT možnost ve vašem dotazu.

K testování API můžete použít cURL následujícím způsobem, přičemž nahradíte <account_id> svým 32znakovým ID účtu (dostupným v dashboardu) a <token> s řetězcem tokenu, který jste vygenerovali výše.

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SELECT 'Hello Workers Analytics Engine' AS message"

Pokud jste už nějaká data publikovali, můžete spuštěním následujícího příkazu ověřit, že byl dataset v databázi vytvořen.

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SHOW TABLES"

Viz Workers Analytics Engine reference SQL, kde najdete úplnou podporovanou syntaxi dotazů.

Pro každý dataset se automaticky vytvoří nová tabulka, jakmile do něj z Workeru začnete zapisovat události.

Tabulka bude obsahovat následující sloupce:

Při velmi vysokých objemech dat Analytics Engine data podvzorkuje, aby si zachoval výkon. Ke vzorkování může dojít při zápisu i při čtení. Vzorkování vychází z indexu vaší datové sady, takže se vzorkují pouze indexy, které přijímají velké množství událostí. Pokud váš worker obsluhuje více zákazníků, můžete například zvážit, aby polem indexu bylo ID zákazníka. To by znamenalo, že pokud jeden zákazník začne odesílat požadavky s vysokou frekvencí, mohou se události od tohoto zákazníka vzorkovat, zatímco data ostatních zákazníků zůstanou nevzorkovaná.

Tento systém vzorkování jsme v Cloudflare testovali celou řadu let a umožnil nám škálovat naše systémy webové analytiky na velmi vysokou propustnost, a přitom stále poskytovat statisticky významné výsledky bez ohledu na objem provozu, který web přijímá.

Míra, s jakou jsou data vzorkována, je zpřístupněna prostřednictvím _sample_interval sloupec. To znamená, že pokud provádíte statistickou analýzu svých dat, možná budete muset tento sloupec zohlednit. Například:

Kromě toho QUANTILEEXACTWEIGHTED funkce je navržena tak, aby se používala se vzorkovacím intervalem jako třetím argumentem.

Aliasy sloupců lze v dotazech použít k pojmenování polí typu blob a double ve vašem datasetu:

SELECT
    timestamp,
    blob1 AS location_id,
    double1 AS inside_temp,
    double2 AS outside_temp
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '1' DAY

Výpočet počtu záznamů pořízených na každém místě za posledních 7 dní. V tomto případě seskupujeme podle pole index, aby bylo možné vypočítat přesný počet i v případě, že data byla vzorkována:

SELECT
    index1 AS location_id,
    SUM(_sample_interval) AS n_readings
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '7' DAY
GROUP BY index1

Výpočet průměrné teploty za posledních 7 dní na každém místě. Zohledňuje se přitom interval vzorkování:

SELECT
    index1 AS location_id,
    SUM(_sample_interval * double1) / SUM(_sample_interval) AS average_temp
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '7' DAY
GROUP BY index1