始める

1. データセットに名前を付けてWorkerに追加する

次の内容をwrangler.tomlファイルに追加して、Workers Analytics Engineデータセットへのバインディングを作成します。データセットはSQLのテーブルのようなもので、行と列は一貫した意味を持つ必要があります。

[[analytics_engine_datasets]]
binding = "<BINDING_NAME>"
dataset = "<DATASET_NAME>"

2. Workerからデータポイントを書く

作成したバインディングで公開されているwriteDataPoint()メソッドを呼び出すことで、Workerにデータポイントを書き込むことができます。

async fetch(request, env) {
  env.WEATHER.writeDataPoint({
    'blobs': ["シアトル", "アメリカ", "pro_sensor_9000"], // 市、州
    'doubles': [25, 0.5],
    'indexes': ["a3cd45"]
  });
  return new Response("OK!");
}

データポイントは、次の要素で構成される構造化イベントです：

Blobs (文字列) — グループ化およびフィルタリングに使用される次元。別のメトリクスシステムではラベルと呼ばれることもあります。
Doubles (数値) — データポイントに記録したい数値の値。
Indexes — (文字列) — サンプリングキーとして使用されます。

上記の例では、空気質サンプルを収集していると仮定します。書き込まれた各データポイントは、天候センサーからの読み取りを表します。blobsは市、州、センサーのモデルを定義し、後でクエリをフィルタリングできる次元です。doublesは数値の温度と気圧の読み取りを定義します。そして、indexは顧客のIDです。追加のデータをデータポイントに加えるために、ジオロケーションなどの受信リクエストに関するコンテキストを含めることを検討してください。

現在、writeDataPoint() APIは順序付きの値の配列を受け入れます。これは、フィールドを一貫した順序で提供する必要があることを意味します。indexesフィールドは配列を受け入れますが、現在は単一のインデックスのみを提供する必要があります。複数のインデックスを提供しようとすると、データポイントは記録されません。

3. SQL APIを使用してデータをクエリする

書き込んだデータを2つの方法でクエリできます：

SQL API — 独自のクエリを作成し、Grafanaなどの外部ツールと統合するのに最適です。
GraphQL API — Cloudflareダッシュボードを支える同じAPIです。

この例では、SQL APIを使用します。

APIトークンを作成する

Account Analytics Read権限を持つAPIトークン ↗を作成します。

最初のクエリを書く

次のクエリは、温度がゼロを超えたときに最も高い平均湿度の読み取りを持つ上位10都市を返します：

SELECT
  blob1 AS city,
  SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity
FROM WEATHER
WHERE double1 > 0
GROUP BY city
ORDER BY avg_humidity DESC
LIMIT 10

このクエリは、SQL APIにHTTPリクエストを送信することで実行できます：

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SELECT blob1 AS city, SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity FROM WEATHER WHERE double1 > 0 GROUP BY city ORDER BY avg_humidity DESC LIMIT 10"

サポートされているSQL機能の完全なリストについては、Workers Analytics Engine SQLリファレンスを参照してください。

時系列データの取り扱い

Workers Analytics Engineは、Grafanaなどのツールを使用して視覚化できる時系列分析を強化するために最適化されています。ランタイムから書き込まれたすべてのイベントには、自動的にtimestampフィールドが追加されます。ほとんどの時系列は丸められ、その後GROUP BYでtimestampを使用することが期待されます。例えば：

SELECT
  intDiv(toUInt32(timestamp), 300) * 300 AS t,
  blob1 AS city,
  SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity
FROM WEATHER
WHERE
  timestamp >= NOW() - INTERVAL '1' DAY
  AND double1 > 0
GROUP BY t, city
ORDER BY t, avg_humidity DESC

このクエリは、最初にtimestampフィールドを最も近い5分に丸めます。次に、そのフィールドと市でグループ化し、5分間の各市の平均湿度を計算します。

Workers Analytics Engineに対して効率的なGrafanaクエリを作成する方法の詳細については、GrafanaからWorkers Analytics Engineをクエリするを参照してください。

さらなる読み物

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings