Začínáme

Tento návod vás provede:

Vytváření prvního R2 bucket a povolením jeho datový katalog.
Vytvoření API token potřebná k tomu, aby se Pipelines mohly ověřit vůči vašemu datovému katalogu.
Vytvoření prvního pipelinu s jednoduchým schématem e-shopu, který zapisuje do Apache Iceberg ↗ tabulku spravovanou službou R2 Data Catalog.
Odeslání ukázkových e-commerce dat přes HTTP endpoint.
Ověřování dat ve vašem bucketu a jejich dotazování pomocí R2 SQL.

Předpoklady

Zaregistrujte si účet Cloudflare ↗.
Nainstalujte Node.js ↗.

Správce verzí Node.js

Použijte správce verzí Node, jako je Volta ↗ nebo nvm ↗ abyste se vyhnuli problémům s oprávněními a mohli měnit verze Node.js. Wrangler, o kterém se dozvíte dále v této příručce, vyžaduje verzi Node 16.17.0 nebo novější.

1. Vytvořte R2 bucket

Pokud ještě nejste přihlášeni, spusťte:
```
npx wrangler login
```

Vytvořte bucket R2:

npx wrangler r2 bucket create pipelines-tutorial

V dashboardu Cloudflare přejděte na Objektové úložiště R2 stránce.
Přejděte na Přehled ↗
Vyberte Vytvořit bucket.
Zadejte název bucketu: pipelines-tutorial
Vyberte Vytvořit bucket.

2. Povolte R2 Data Catalog

Povolte katalog ve svém R2 bucketu:

npx wrangler r2 bucket catalog enable pipelines-tutorial

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

V dashboardu Cloudflare přejděte na Objektové úložiště R2 stránce.
Přejděte na Přehled ↗
Vyberte bucket: pipelines-tutorial.
Přepněte na Nastavení kartu a přejděte dolů na R2 Data Catalog, a vyberte Povolit.
Po zapnutí si poznamenejte Catalog URI a Název warehouse.

3. Vytvořte API token

Pipelines se musí k R2 Data Catalog ověřit pomocí Token R2 API s oprávněními pro katalog a R2.

V dashboardu Cloudflare přejděte na Objektové úložiště R2 stránce.
Přejděte na Přehled ↗
Vyberte Správa API tokenů.
Vyberte Vytvoření API tokenu účtu.
Zadejte název pro váš API token.
V části Oprávnění, vyberte Admin Read & Write oprávnění.
Vyberte Create Account API Token.
Všimněte si Hodnota tokenu.

4. Vytvořte pipeline

Nejprve vytvořte soubor schématu, který definuje strukturu vašich e-commerce dat:

Vytvořit schema.json:

{
	"fields": [
		{
			"name": "user_id",
			"type": "string",
			"required": true
		},
		{
			"name": "event_type",
			"type": "string",
			"required": true
		},
		{
			"name": "product_id",
			"type": "string",
			"required": false
		},
		{
			"name": "amount",
			"type": "float64",
			"required": false
		}
	]
}

Pomocí interaktivního nastavení vytvořte pipeline, která zapisuje do R2 Data Catalog:

npx wrangler pipelines setup

Postupujte podle výzev:

Název pipeline: Zadejte ecommerce
Konfigurace streamu:
- Povolit HTTP endpoint: yes
- Vyžadovat ověření: no (pro jednoduchost)
- Nakonfigurujte vlastní CORS origins: no
- Definice schématu: Load from file
- Cesta k souboru schématu: schema.json (nebo cesta k vašemu souboru)
Konfigurace sinku:
- Typ cíle: Data Catalog Table
- Název R2 bucketu: pipelines-tutorial
- Namespace: default
- Název tabulky: ecommerce
- Catalog API token: Zadejte token z kroku 3
- Komprese: zstd
- Rotace souboru při dosažení velikosti (MB): 100
- Rotace souboru při dosažení času (s): 10 (aby byla data v tomto tutoriálu viditelná rychleji)
Transformace SQL: Vyberte Use simple ingestion query k použití:
```
INSERT INTO ecommerce_sink SELECT * FROM ecommerce_stream
```

Po dokončení nastavení si poznamenejte URL adresu HTTP endpointu zobrazenou ve výsledném výstupu.

V Cloudflare dashboardu přejděte na Pipelines > Pipelines.
Přejděte na Pipelines ↗
Vyberte Create Pipeline.
Připojení ke streamu:
- Název pipeline: ecommerce
- Povolit HTTP endpoint pro odesílání dat: Povoleno
- HTTP ověřování: Disabled (výchozí)
- Vyberte Next

Define Input Schema:

Vyberte JSON editor

Zkopírujte schéma:

{
	"fields": [
		{
			"name": "user_id",
			"type": "string",
			"required": true
		},
		{
			"name": "event_type",
			"type": "string",
			"required": true
		},
		{
			"name": "product_id",
			"type": "string",
			"required": false
		},
		{
			"name": "amount",
			"type": "f64",
			"required": false
		}
	]
}

Vyberte Next

Define Sink:
- Vyberte svůj bucket R2: pipelines-tutorial
- Typ úložiště: R2 Data Catalog
- Namespace: default
- Název tabulky: ecommerce
- Pokročilá nastavení: Změna Maximum Time Interval na 10 seconds
- Vyberte Next
Přihlašovací údaje:
- Zakázat Automaticky vytvořit API token účtu pro váš sink
- Zadejte Catalog Token z kroku 3
- Vyberte Next
Pipeline Definition:
- Ponechte výchozí SQL dotaz:
```
INSERT INTO ecommerce_sink SELECT * FROM ecommerce_stream;
```
- Vyberte Create Pipeline
Po vytvoření pipeline si poznamenejte ID streamu pro další krok.

5. Odešlete ukázková data

Odešlete e-commerce události do HTTP endpointu vaší pipeline:

curl -X POST https://{stream-id}.ingest.cloudflare.com \
  -H "Content-Type: application/json" \
  -d '[
    {
      "user_id": "user_12345",
      "event_type": "purchase",
      "product_id": "widget-001",
      "amount": 29.99
    },
    {
      "user_id": "user_67890",
      "event_type": "view_product",
      "product_id": "widget-002"
    },
    {
      "user_id": "user_12345",
      "event_type": "add_to_cart",
      "product_id": "widget-003",
      "amount": 15.50
    }
  ]'

Nahraďte {stream-id} se skutečným koncovým bodem streamu z nastavení pipeline.

6. Ověřte data ve svém bucketu

V dashboardu Cloudflare přejděte na Objektové úložiště R2 stránce.
Vyberte svůj bucket: pipelines-tutorial.
Měli byste vidět soubory metadat Iceberg a datové soubory vytvořené vaším pipeline. Poznámka: Pokud v bucketu žádné soubory nevidíte, počkejte několik minut a zkuste to znovu.
Data jsou uspořádána ve formátu Apache Iceberg, přičemž metadata sledují verze tabulky.

7. Dotazujte svá data pomocí R2 SQL

Nastavte prostředí pro používání R2 SQL:

export WRANGLER_R2_SQL_AUTH_TOKEN=YOUR_API_TOKEN

Nebo vytvořte .env soubor pomocí:

WRANGLER_R2_SQL_AUTH_TOKEN=YOUR_API_TOKEN

Kde YOUR_API_TOKEN je token, který jste vytvořili v kroku 3. Další informace o nastavení proměnných prostředí najdete v Systémové proměnné prostředí Wrangler.

Dotaz na vaše data:

npx wrangler r2 sql query "YOUR_WAREHOUSE_NAME" "
SELECT
    user_id,
    event_type,
    product_id,
    amount
FROM default.ecommerce
WHERE event_type = 'purchase'
LIMIT 10"

Nahraďte YOUR_WAREHOUSE_NAME s názvem warehouse z kroku 2.

Tuto tabulku můžete dotazovat také pomocí libovolného enginu, který podporuje Apache Iceberg. Postup připojení dalších enginů k R2 Data Catalog najdete v Připojení k enginům Iceberg.