INTEGRITY Dokumentace

Vytvoření kompletní datové pipeline

V tomto návodu se naučíte sestavit kompletní datový pipeline pomocí Cloudflare Pipelines, R2 Data Catalog a R2 SQL. Součástí je také ukázkový skript v Pythonu, který vytváří data o finančních transakcích a odesílá je do vašeho Pipeline. Tato data pak lze dotazovat pomocí R2 SQL nebo libovolného dotazovacího nástroje kompatibilního s Apache Iceberg.

Tento návod ukazuje, jak:

Předpoklady

  1. Zaregistrujte si účet Cloudflare ↗.
  2. Nainstalujte Node.js ↗.
  3. Nainstalujte Python 3.8+ ↗ pro skript generující data.

1. Nastavte ověřování

Pro práci se službami Cloudflare budete potřebovat tokeny API.

  1. V dashboardu Cloudflare přejděte na API tokeny stránce.

    Přejděte na API tokeny účtu ↗
  2. Vyberte Create Token.

  3. Vyberte Začínáme vedle Create Custom Token.

  4. Zadejte název svého API tokenu.

  5. V části Oprávnění, vyberte:

    • Workers Pipelines s oprávněními Read, Send a Edit
    • Workers R2 Data Catalog s oprávněními Read a Edit
    • Workers R2 SQL s oprávněním Read
    • Workers R2 Storage s oprávněními Read a Edit
  6. Volitelně můžete k tomuto tokenu přidat TTL.

  7. Vyberte Pokračovat k souhrnu.

  8. Klikněte na Create Token

  9. Všimněte si Hodnota tokenu.

Exportujte nový token jako proměnnou prostředí:

export WRANGLER_R2_SQL_AUTH_TOKEN= #paste your token here

Pokud používáte Wrangler poprvé, nezapomeňte se přihlásit.

npx wrangler login

2. Vytvořte R2 bucket a povolte R2 Data Catalog

Vytvořte bucket R2:

npx wrangler r2 bucket create fraud-pipeline
  1. V dashboardu Cloudflare přejděte na Objektové úložiště R2 stránce.

    Přejděte na Přehled ↗
  2. Vyberte Vytvořit bucket.

  3. Zadejte název bucketu: fraud-pipeline

  4. Vyberte Vytvořit bucket.

Povolte katalog ve svém R2 bucketu:

npx wrangler r2 bucket catalog enable fraud-pipeline

Při spuštění tohoto příkazu si poznamenejte hodnoty „Warehouse“ a „Catalog URI“. Budete je později potřebovat.

  1. V dashboardu Cloudflare přejděte na Objektové úložiště R2 stránce.

    Přejděte na Přehled ↗
  2. Vyberte bucket: fraud-pipeline.

  3. Přepněte na Nastavení kartu a přejděte dolů na R2 Data Catalog, a vyberte Povolit.

  4. Po zapnutí si poznamenejte Catalog URI a Název warehouse.

export WAREHOUSE= #Paste your warehouse here

(Volitelné) Povolte kompaktaci ve svém R2 Data Catalog

R2 Data Catalog za vás může tabulky automaticky kompaktovat. V produkčních scénářích streamování událostí běžně vzniká mnoho malých souborů, proto se doporučuje kompaktaci povolit. Tento tutoriál ale ukazuje jen ukázkový případ použití, takže tento krok je volitelný.

npx wrangler r2 bucket catalog compaction enable fraud-pipeline --token $WRANGLER_R2_SQL_AUTH_TOKEN
  1. V dashboardu Cloudflare přejděte na Objektové úložiště R2 stránce.

    Přejděte na Přehled ↗
  2. Vyberte bucket: fraud-pipeline.

  3. Přepněte na Nastavení kartu a přejděte dolů na R2 Data Catalog, klikněte na ikonu úprav a vyberte Povolit.

  4. Můžete zvolit cílovou velikost souboru nebo ponechat výchozí hodnotu. Klikněte na Uložit.

3. Nastavte infrastrukturu pipeline

3.1. Vytvořte Pipeline stream

Nejprve vytvořte soubor schématu s názvem raw_transactions_schema.json s následujícím json schéma:

{
	"fields": [
		{ "name": "transaction_id", "type": "string", "required": true },
		{ "name": "user_id", "type": "int64", "required": true },
		{ "name": "amount", "type": "float64", "required": false },
		{ "name": "transaction_timestamp", "type": "string", "required": false },
		{ "name": "location", "type": "string", "required": false },
		{ "name": "merchant_category", "type": "string", "required": false },
		{ "name": "is_fraud", "type": "bool", "required": false }
	]
}

Vytvořte stream pro příjem příchozích událostí detekce podvodů:

npx wrangler pipelines streams create raw_events_stream \
  --schema-file raw_transactions_schema.json \
  --http-enabled true \
  --http-auth false
# The http ingest endpoint from the output (see example below)
export STREAM_ENDPOINT= #the http ingest endpoint from the output (see example below)

Výstup by měl vypadat takto:

🌀 Creating stream 'raw_events_stream'...
✨ Successfully created stream 'raw_events_stream' with id 'stream_id'.

Creation Summary:
General:
  Name:  raw_events_stream

HTTP Ingest:
  Enabled:         Yes
  Authentication:  Yes
  Endpoint:        https://stream_id.ingest.cloudflare.com
  CORS Origins:    None

Input Schema:
┌───────────────────────┬────────┬────────────┬──────────┐
│ Field Name            │ Type   │ Unit/Items │ Required │
├───────────────────────┼────────┼────────────┼──────────┤
│ transaction_id        │ string │            │ Yes      │
├───────────────────────┼────────┼────────────┼──────────┤
│ user_id               │ int64  │            │ Yes      │
├───────────────────────┼────────┼────────────┼──────────┤
│ amount                │float64 │            │ No       │
├───────────────────────┼────────┼────────────┼──────────┤
│ transaction_timestamp │ string │            │ No       │
├───────────────────────┼────────┼────────────┼──────────┤
│ location              │ string │            │ No       │
├───────────────────────┼────────┼────────────┼──────────┤
│ merchant_category     │ string │            │ No       │
├───────────────────────┼────────┼────────────┼──────────┤
│ is_fraud              │ bool   │            │ No       │
└───────────────────────┴────────┴────────────┴──────────┘

3.2. Vytvořte datový sink

Vytvořte sink, který zapisuje data do vašeho R2 bucketu jako tabulky Apache Iceberg:

npx wrangler pipelines sinks create raw_events_sink \
  --type "r2-data-catalog" \
  --bucket "fraud-pipeline" \
  --roll-interval 30 \
  --namespace "fraud_detection" \
  --table "transactions" \
  --catalog-token $WRANGLER_R2_SQL_AUTH_TOKEN

3.3. Vytvořte pipeline

Propojte svůj stream se sinkem pomocí SQL:

npx wrangler pipelines create raw_events_pipeline \
  --sql "INSERT INTO raw_events_sink SELECT * FROM raw_events_stream"
  1. V Cloudflare dashboardu přejděte na Pipelines > Pipelines.

    Přejděte na Pipelines ↗
  2. Vyberte Create Pipeline.

  3. Připojení ke streamu:

    • Název pipeline: raw_events
    • Povolit HTTP endpoint pro odesílání dat: Povoleno
    • HTTP ověřování: Disabled (výchozí)
    • Vyberte Next
  4. Define Input Schema:

    • Vyberte JSON editor

    • Vložte schéma:

      {
      	"fields": [
      		{ "name": "transaction_id", "type": "string", "required": true },
      		{ "name": "user_id", "type": "int64", "required": true },
      		{ "name": "amount", "type": "float64", "required": false },
      		{
      			"name": "transaction_timestamp",
      			"type": "string",
      			"required": false
      		},
      		{ "name": "location", "type": "string", "required": false },
      		{ "name": "merchant_category", "type": "string", "required": false },
      		{ "name": "is_fraud", "type": "bool", "required": false }
      	]
      }
    • Vyberte Next

  5. Define Sink:

    • Vyberte svůj bucket R2: fraud-pipeline
    • Typ úložiště: R2 Data Catalog
    • Namespace: fraud_detection
    • Název tabulky: transactions
    • Pokročilá nastavení: Změna Maximum Time Interval na 30 seconds
    • Vyberte Next
  6. Přihlašovací údaje:

    • Zakázat Automaticky vytvořit API token účtu pro váš sink
    • Zadejte Catalog Token z kroku 1
    • Vyberte Next
  7. Pipeline Definition:

    • Ponechte výchozí SQL dotaz:
      INSERT INTO raw_events_sink SELECT * FROM raw_events_stream;
    • Vyberte Create Pipeline
  8. Po vytvoření pipeline si poznamenejte ID streamu pro další krok.

4. Vygenerujte ukázková data pro detekci podvodů

Vytvořte skript v Pythonu, který vygeneruje realistická transakční data se vzory podvodů:

fraud_data_generator.py
import requests
import json
import uuid
import random
import time
import os
from datetime import datetime, timezone, timedelta

# Configuration - exported from the prior steps
STREAM_ENDPOINT = os.environ["STREAM_ENDPOINT"]# From the stream you created
API_TOKEN = os.environ["WRANGLER_R2_SQL_AUTH_TOKEN"] #the same one created earlier
EVENTS_TO_SEND = 1000 # Feel free to adjust this

def generate_transaction():
    """Generate some random transactions with occasional fraud"""

    # User IDs
    high_risk_users = [1001, 1002, 1003, 1004, 1005]
    normal_users = list(range(1006, 2000))

    user_id = random.choice(high_risk_users + normal_users)
    is_high_risk_user = user_id in high_risk_users

    # Generate amounts
    if random.random() < 0.05:
        amount = round(random.uniform(5000, 50000), 2)
    elif random.random() < 0.03:
        amount = round(random.uniform(0.01, 1.00), 2)
    else:
        amount = round(random.uniform(10, 500), 2)

    # Locations
    normal_locations = ["NEW_YORK", "LOS_ANGELES", "CHICAGO", "MIAMI", "SEATTLE", "SAN FRANCISCO"]
    high_risk_locations = ["UNKNOWN_LOCATION", "VPN_EXIT", "MARS", "BAT_CAVE"]

    if is_high_risk_user and random.random() < 0.3:
        location = random.choice(high_risk_locations)
    else:
        location = random.choice(normal_locations)

    # Merchant categories
    normal_merchants = ["GROCERY", "GAS_STATION", "RESTAURANT", "RETAIL"]
    high_risk_merchants = ["GAMBLING", "CRYPTO", "MONEY_TRANSFER", "GIFT_CARDS"]

    if random.random() < 0.1:  # 10% high-risk merchants
        merchant_category = random.choice(high_risk_merchants)
    else:
        merchant_category = random.choice(normal_merchants)

    # Series of checks to either increase fraud score by a certain margin
    fraud_score = 0
    if amount > 2000: fraud_score += 0.4
    if amount < 1: fraud_score += 0.3
    if location in high_risk_locations: fraud_score += 0.5
    if merchant_category in high_risk_merchants: fraud_score += 0.3
    if is_high_risk_user: fraud_score += 0.2

    # Compare the fraud scores
    is_fraud = random.random() < min(fraud_score * 0.3, 0.8)

    # Generate timestamps (some fraud happens at unusual hours)
    base_time = datetime.now(timezone.utc)
    if is_fraud and random.random() < 0.4:  # 40% of fraud at night
        hour = random.randint(0, 5)  # Late night/early morning
        transaction_time = base_time.replace(hour=hour)
    else:
        transaction_time = base_time - timedelta(
            hours=random.randint(0, 168)  # Last week
        )

    return {
        "transaction_id": str(uuid.uuid4()),
        "user_id": user_id,
        "amount": amount,
        "transaction_timestamp": transaction_time.isoformat(),
        "location": location,
        "merchant_category": merchant_category,
        "is_fraud": True if is_fraud else False
    }

def send_batch_to_stream(events, batch_size=100):
    """Send events to Cloudflare Stream in batches"""

    headers = {
        "Authorization": f"Bearer {API_TOKEN}",
        "Content-Type": "application/json"
    }

    total_sent = 0
    fraud_count = 0

    for i in range(0, len(events), batch_size):
        batch = events[i:i + batch_size]
        fraud_in_batch = sum(1 for event in batch if event["is_fraud"] == True)

        try:
            response = requests.post(STREAM_ENDPOINT, headers=headers, json=batch)

            if response.status_code in [200, 201]:
                total_sent += len(batch)
                fraud_count += fraud_in_batch
                print(f"Sent batch of {len(batch)} events (Total: {total_sent})")
            else:
                print(f"Failed to send batch: {response.status_code} - {response.text}")

        except Exception as e:
            print(f"Error sending batch: {e}")

        time.sleep(0.1)

    return total_sent, fraud_count

def main():
    print("Generating fraud detection data...")

    # Generate events
    events = []
    for i in range(EVENTS_TO_SEND):
        events.append(generate_transaction())
        if (i + 1) % 100 == 0:
            print(f"Generated {i + 1} events...")

    fraud_events = sum(1 for event in events if event["is_fraud"] == True)
    print(f"📊 Generated {len(events)} total events ({fraud_events} fraud, {fraud_events/len(events)*100:.1f}%)")

    # Send to stream
    print("Sending data to Pipeline stream...")
    sent, fraud_sent = send_batch_to_stream(events)

    print(f"\nComplete!")
    print(f"   Events sent: {sent:,}")
    print(f"   Fraud events: {fraud_sent:,} ({fraud_sent/sent*100:.1f}%)")
    print(f"   Data is now flowing through your pipeline!")

if __name__ == "__main__":
    main()

Nainstalujte potřebnou závislost pro Python a spusťte skript:

pip install requests
python fraud_data_generator.py

5. Dotazujte data pomocí R2 SQL

Nyní můžete analyzovat data o detekci podvodů pomocí R2 SQL. Zde je několik příkladů dotazů:

5.1. Zobrazte nedávné transakce

npx wrangler r2 sql query "$WAREHOUSE" "
SELECT
    transaction_id,
    user_id,
    amount,
    location,
    merchant_category,
    is_fraud,
    transaction_timestamp
FROM fraud_detection.transactions
WHERE __ingest_ts > '2025-09-24T01:00:00Z'
AND is_fraud = true
LIMIT 10"

5.2. Filtrujte surové transakce do nové tabulky a zvýrazněte transakce s vysokou hodnotou

Vytvořte nový sink, který zapíše filtrovaná data do nové tabulky Apache Iceberg v R2 Data Catalog:

npx wrangler pipelines sinks create fraud_filter_sink \
  --type "r2-data-catalog" \
  --bucket "fraud-pipeline" \
  --roll-interval 30 \
  --namespace "fraud_detection" \
  --table "fraud_transactions" \
  --catalog-token $WRANGLER_R2_SQL_AUTH_TOKEN

Nyní vytvoříte nový SQL dotaz pro zpracování dat z původní raw_events_stream stream a zapisuje pouze označené transakce, které přesahují amount z 1 000.

npx wrangler pipelines create fraud_events_pipeline \
  --sql "INSERT INTO fraud_filter_sink SELECT * FROM raw_events_stream WHERE is_fraud=true and amount > 1000"

Vytvořte dotaz na tabulku a zkontrolujte výsledky:

npx wrangler r2 sql query "$WAREHOUSE" "
SELECT
    transaction_id,
    user_id,
    amount,
    location,
    merchant_category,
    is_fraud,
    transaction_timestamp
FROM fraud_detection.fraud_transactions
LIMIT 10"

Také ověřte, že jsou vyfiltrovány nepodvodné události:

npx wrangler r2 sql query "$WAREHOUSE" "
SELECT
    transaction_id,
    user_id,
    amount,
    location,
    merchant_category,
    is_fraud,
    transaction_timestamp
FROM fraud_detection.fraud_transactions
WHERE is_fraud = false
LIMIT 10"

Měl by se zobrazit následující výstup:

Query executed successfully with no results

Závěr

Úspěšně jste vytvořili ucelený datový pipeline od začátku do konce pomocí datové platformy Cloudflare. V tomto tutoriálu jste se naučili:

  1. Použijte R2 Data Catalog: Využil tabulky Apache Iceberg pro efektivní ukládání dat
  2. Nastavení Cloudflare Pipelines: Vytvořil streamy, sinky a pipelines pro příjem dat
  3. Vygenerovaná ukázková data: Vytvořil transakční data s několika základními vzory podvodů
  4. Dotazujte své tabulky pomocí R2 SQL: Přístup k surovým a zpracovaným datovým tabulkám uloženým v R2 Data Catalog