Skip to main content

API Reference - Events Ingestion

使用量イベントを取り込み、イベントの取り込みリクエストとレスポンスをインタラクティブにテストするための完全な API ドキュメントにアクセスできます。

API Reference - Meters Creation

メーターを作成するための完全な API ドキュメントを確認し、メーター作成リクエストとレスポンスをインタラクティブにテストできます。

メーターの作成

メーターは、課金目的で使用量イベントを集計・測定する方法を定義します。 メーターを作成する前に、使用量の追跡戦略を計画します。
  • 追跡する使用量イベントを特定する
  • イベントの集計方法(count、sum など)を決定する
  • 特定のユースケースに必要なフィルタリング要件を定義する

メーター作成の手順

この包括的なガイドに従って、使用量メーターを設定します。
1

Configure Basic Information

メーターの基本的な詳細を設定します。
string
必須
このメーターが追跡する対象を識別できる、明確で説明的な名前を選択します。例: “Tokens”、“API Calls”、“Storage Usage”、“Compute Hours”
string
このメーターが測定する内容を詳しく説明します。例: “顧客が実行した各 POST /v1/orders リクエストをカウント”
string
必須
このメーターをトリガーするイベント識別子を指定します。例: “token”、“api.call”、“storage.usage”、“compute.session”
イベント名は、使用量イベントで送信する値と完全に一致する必要があります。イベント名では大文字と小文字が区別されます。
2

Configure Aggregation Settings

メーターがイベントから使用量を計算する方法を定義します。
string
必須
イベントの集計方法を選択します。
受信したイベント数を単純にカウントします。ユースケース: API 呼び出し、ページビュー、ファイルアップロード計算: イベントの総数
string
集計対象となるイベントメタデータのプロパティ名です。
Sum、Max、Last の集計タイプを使用する場合、このフィールドは必須です。
string
必須
レポートと課金画面に表示する単位ラベルを定義します。例: “calls”、“GB”、“hours”、“tokens”
3

Configure Event Filtering (Optional)

メーターに含めるイベントを制御する条件を設定します。
イベントフィルタリングを使用すると、使用量の計算に含めるイベントを決定する高度なルールを作成できます。テストイベントの除外、ユーザー tier によるフィルタリング、特定のアクションへの絞り込みなどに便利です。
イベントフィルタリングを有効にするイベントフィルタリングを有効にするを切り替えて、条件付きイベント処理を有効にします。フィルターロジックを選択する複数の条件を評価する方法を選択します。
イベントをカウントするには、すべての条件が true である必要があります。複数の厳密な条件を同時に満たすイベントが必要な場合に使用します。例: user_tier = "premium" AND endpoint = "/api/v2/users" を満たす API 呼び出しをカウント
フィルター条件を設定する
1

Add Condition

Add conditionをクリックして、新しいフィルタールールを作成します。
2

Configure Property Key

イベントメタデータのプロパティ名を指定します。
3

Select Comparator

使用可能な演算子から選択します。
  • equals - 完全一致
  • not_equals - 除外フィルター
  • greater_than - 数値比較
  • greater_than_or_equals - 数値比較(指定値を含む)
  • less_than - 数値比較
  • less_than_or_equals - 数値比較(指定値を含む)
  • contains - 文字列に部分文字列を含む
  • does_not_contain - 文字列除外フィルター
4

Set Comparison Value

比較対象の値を設定します。
5

Add Groups

Add Groupを使用して、複雑なロジック用の追加の条件グループを作成します。
条件を正しく機能させるには、フィルタリングするプロパティをイベントメタデータに含める必要があります。必須プロパティがないイベントはカウントから除外されます。
4

Create Meter

メーター設定を確認し、Create Meterをクリックします。
これでメーターは使用量イベントを受信し、集計できる状態になりました。

商品でメーターをリンクする

メーターを作成したら、使用量ベースの課金を有効にするため、商品にリンクする必要があります。この処理により、メーターの使用量データが顧客への課金用の価格ルールに接続されます。 メーターを商品にリンクすると、使用量の追跡と課金が接続されます。
  • 商品は価格ルールと課金動作を定義する
  • メーターは課金計算に使用するデータを提供する
  • 複雑な課金シナリオでは、1 つの商品に複数のメーターをリンクできる

商品設定の手順

商品設定を適切に構成して、使用量データを請求可能な料金に変換します。
1

Choose Usage-Based Billing Product Type

商品作成または編集ページに移動し、商品タイプとしてUsage-Basedを選択します。
2

Select Associated Meter

Associated Meterをクリックして、側面からメーター選択パネルを開きます。このパネルで、この商品で使用量を追跡するメーターを設定できます。
3

Add Your Meter

メーター選択パネルで次の操作を行います。
  1. Add Metersをクリックして、使用可能なメーターを表示する
  2. ドロップダウンリストから作成したメーターを選択する
  3. 選択したメーターが商品の設定に表示される
4

Configure Price Per Unit

メーターで追跡する使用量の各単位の価格を設定します。
number
必須
メーターで測定する各単位に課金する金額を定義します。: 1 単位あたり $0.50 に設定すると、次のようになります。
  • 1,000 単位を消費 = 1,000 × $0.50 = 500.00 を課金
  • 500 単位を消費 = 500 × $0.50 = 250.00 を課金
  • 100 単位を消費 = 100 × $0.50 = 50.00 を課金
5

Set Free Threshold (Optional)

課金開始前の無料使用量を設定します。
number
有料使用量の計算が始まる前に、顧客が無料で利用できる単位数です。仕組み:
  • 無料しきい値: 100 単位
  • 1 単位あたりの価格: $0.50
  • 顧客の使用量: 250 単位
  • 計算: (250 - 100) × 0.50=0.50 = **75.00** を課金
無料しきい値は、フリーミアムモデルやトライアル期間、プランに含まれる基本利用量の提供に適しています。
無料しきい値は各課金サイクルに適用されるため、顧客には毎月、または設定した課金スケジュールに従って新しい無料枠が付与されます。
6

Save Configuration

メーターと価格設定を確認し、Save Changesをクリックして設定を完了します。
これで商品は使用量ベースの課金用に設定され、測定された消費量に基づいて顧客に自動的に課金されます。
次に行われること:
  • メーターに送信された使用量イベントが追跡・集計される
  • 価格ルールが課金計算に自動的に適用される
  • 各課金サイクル中の実際の消費量に基づいて顧客に課金される
1 商品あたり最大 10 個のメーターを追加できるため、API 呼び出し、ストレージ、計算時間、カスタムメトリクスなど、複数の軸にわたる高度な使用量追跡が可能です。

使用量イベントの送信

メーターを設定したら、アプリケーションから使用量イベントを送信して顧客の使用量を追跡できます。

イベント構造

各使用量イベントには、次の必須フィールドを含める必要があります。
string
必須
このイベント固有の一意の識別子です。すべてのイベントで一意である必要があります。
string
必須
この使用量を帰属させる Dodo Payments customer ID です。
string
必須
メーター設定と一致するイベント名です。イベント名によって適切なメーターがトリガーされます。
string
イベントが発生した時刻の ISO 8601 timestamp。指定しない場合は現在の UTC timestamp がデフォルトで使用されます。過去1時間以内から未来5分以内の範囲に収まっている必要があり、この範囲外の timestamp は拒否されます。
object
フィルタリングと集計に使用する追加プロパティです。メーターの “Over Property” またはフィルタリング条件で参照する値を含めます。

使用量イベント API の例

Events API を使用して、設定済みのメーターに使用量イベントを送信します。

信頼性の高い取り込みで知っておくべき重要事項

本番環境で使用状況の追跡を正確かつ堅牢に保つため、次のプラクティスに従ってください。
決定論的で冪等な event_id を使用してください。 event_id はすべてのイベント間で一意である必要があり、冪等性キーとして機能します。再利用された event_id は重複として扱われ、再度カウントされないため、リトライによる二重請求は発生しません。ランダムな値ではなくアクションから ID を導出してください。例: `${customer_id}_${action}_${timestamp}`
1 リクエストあたり最大 1,000 件までイベントをバッチ処理してください。 /events/ingest エンドポイントでは、1 回の呼び出しにつき 最大 1,000 件のイベントという上限が設けられています。これを超えるバッチは拒否されるため、大量のイベントは複数の呼び出しに分割してください。大量のワークロードでは、イベントごとに 1 リクエストを送信するのではなく、イベントをバッファリングしてバッチ単位でフラッシュしてください。
5xx429 はリトライし、4xx は決してリトライしないでください。 サーバーエラー (5xx) およびレート制限 (429) の場合は、指数バックオフを使用してリトライしてください。400/422 の検証エラーは リトライしないでください。ペイロードの形式が不正で、毎回失敗するためです。修正して再送信してください。リトライ後も失敗するイベントはキューに追加し、失われないようにしてください。
timestamp は意図的に設定してください。 リアルタイムイベントでは timestamp を省略すると、現在の UTC timestamp がデフォルトで使用されます。遅延イベントまたはバッチイベントでは、使用量が正しい請求期間に反映されるよう、ISO 8601 形式で明示的に設定してください。ただし、受け入れ可能な範囲は狭く、過去1時間を超えて timestamp が付けられたイベント、または未来5分を超えて timestamp が付けられたイベントは拒否されます。過去データのバックフィルはサポートされていないため、バッファリングされたイベントは1時間以内にフラッシュしてください。
集計対象のメタデータは文字列ではなく数値として送信してください。 Meter の Over Property (Sum、Max、Last) で参照されるプロパティは、{ "tokens": "150" } ではなく { "tokens": 150 } のように、数値型である必要があります。文字列の値は集計されません。

使用量ベースの Billing Analytics

包括的な分析ダッシュボードで、使用量ベースの Billing データを監視・分析できます。顧客の消費パターン、Meter のパフォーマンス、Billing の傾向を追跡し、料金戦略を最適化するとともに、使用状況の傾向を把握してください。

概要分析

Overview タブでは、使用量ベースの Billing パフォーマンスを包括的に確認できます。

アクティビティ指標

さまざまな期間にわたる主要な使用状況統計を追跡できます。
metric
現在の Billing 期間の使用状況を表示し、月ごとの消費パターンを把握できます。
metric
追跡を開始してからの累積使用統計を表示し、長期的な成長を把握できます。
期間セレクターを使用して異なる月の使用状況を比較し、季節的な傾向や成長パターンを特定してください。

Meter 数量チャート

紫のグラデーションで時間経過に伴う使用傾向を示す Meter 数量チャート
Meter 数量チャートでは、次の機能によって時間経過に伴う使用傾向を可視化します。
  • 時系列の可視化: 日、週、月単位で使用パターンを追跡
  • 複数 Meter のサポート: 異なる Meter のデータを同時に表示
  • 傾向分析: 使用量の急増、パターン、成長の軌跡を特定
チャートは使用量と選択した期間に応じて自動的にスケーリングされ、小さな変動から大幅な使用量の変化まで明確に確認できます。

イベント分析

詳細なイベント分析のためにイベント名、ID、ページネーションコントロールを表示するイベントテーブル
Events タブでは、個々の使用イベントを詳細に確認できます。

イベント情報の表示

イベントテーブルには、個々の使用イベントについて次の列が表示されます。
  • イベント名: 使用イベントを生成した具体的なアクションまたはトリガー
  • イベント ID: 各イベントインスタンスの一意の識別子
  • 顧客 ID: イベントに関連付けられた顧客
  • タイムスタンプ: イベントが発生した日時
このビューでは、顧客基盤全体の個々の使用イベントを追跡・監視でき、Billing 計算と使用パターンを透明化できます。

顧客分析

Customers タブでは、次の情報を含む顧客使用データの詳細なテーブルビューを確認できます。

利用可能なデータ列

string
識別に使用する顧客のメールアドレス。
string
顧客のサブスクリプションの一意の識別子。
number
料金が発生する前に顧客のプランに含まれる無料ユニット数。
currency
無料枠を超えた使用量に対するユニットあたりの料金。
timestamp
顧客の直近の使用イベントのタイムスタンプ。
currency
使用量ベースの Billing で顧客に請求された合計金額。
number
顧客が消費したユニットの合計数。
number
無料枠を超え、請求対象となるユニット数。

テーブルの機能

  • 列のフィルタリング: 「Edit Columns」機能を使用して、特定のデータ列を表示または非表示にする
  • リアルタイム更新: 使用量データには最新の消費指標が反映される

集計例

ここでは、さまざまな集計タイプの実用的な例を紹介します。

集計タイプの理解

集計タイプごとに適した Billing シナリオが異なります。使用量をどのように測定・請求したいかに基づいて、適切なタイプを選択してください。

実装例

これらの例では、サンプルイベントと期待される結果を使用して、各集計タイプの実際の利用例を示します。
シナリオ: API リクエストの合計数を追跡Meter Configuration:
  • Event Name: api.call
  • Aggregation Type: Count
  • Measurement Unit: calls
サンプルイベント:
結果: 顧客に 3 回の呼び出しを請求
シナリオ: 転送したバイト数の合計に基づいて請求Meter Configuration:
  • Event Name: data.transfer
  • Aggregation Type: Sum
  • Over Property: bytes
  • Measurement Unit: GB
サンプルイベント:
結果: 合計 1.5 GB の転送量を顧客に請求
シナリオ: 同時接続ユーザー数の最大値に基づいて請求Meter Configuration:
  • Event Name: concurrent.users
  • Aggregation Type: Max
  • Over Property: count
  • Measurement Unit: users
サンプルイベント:
結果: ピーク時の同時接続ユーザー 23 人を顧客に請求

イベントフィルタリングの例

特定のエンドポイントへの API 呼び出しのみをカウントします。Filter Configuration:
  • Property: endpoint
  • Comparator: equals
  • Value: /v1/orders
サンプルイベント:
結果: フィルター条件に一致するイベントがカウントされます。異なるエンドポイントのイベントは無視されます。

トラブルシューティング

使用量ベースの Billing 実装に関する一般的な問題を解決し、正確な追跡と Billing を実現します。

一般的な問題

使用量ベースの Billing に関する問題の多くは、次のカテゴリに分類されます。
  • イベントの配信および処理の問題
  • Meter Configuration の問題
  • データ型およびフォーマットのエラー
  • 顧客 ID および認証の問題

デバッグ手順

使用量ベースの Billing のトラブルシューティングを行う場合:
  1. Events analytics タブでイベントの配信を確認する
  2. Meter Configuration がイベント構造と一致していることを確認する
  3. 顧客 ID と API 認証を検証する
  4. フィルタリング条件と集計設定を確認する

解決策と修正方法

一般的な原因:
  • イベント名が Meter Configuration と完全には一致していない
  • イベントのフィルタリング条件によってイベントが除外されている
  • 顧客 ID が Dodo Payments アカウントに存在しない
  • イベントのタイムスタンプが現在の Billing 期間外である
解決策:
  • イベント名のスペルと大文字・小文字を確認する
  • フィルタリング条件を確認してテストする
  • 顧客 ID が有効かつアクティブであることを確認する
  • イベントのタイムスタンプが新しく、正しい形式であることを確認する
一般的な原因:
  • Over Property の名前がイベントのメタデータキーと一致していない
  • メタデータの値のデータ型が正しくない (文字列と数値の違い)
  • 必須のメタデータプロパティが不足している
解決策:
  • メタデータキーが Over Property の設定と完全に一致していることを確認する
  • イベント内の文字列形式の数値を実際の数値に変換する
  • すべてのイベントに必須プロパティを含める
一般的な原因:
  • フィルタープロパティ名がイベントメタデータと一致していない
  • データ型に対する Comparator が正しくない (文字列と数値の違い)
  • 文字列比較で大文字・小文字が区別されている
解決策:
  • プロパティ名が完全に一致していることを再確認する
  • データ型に適した Comparator を使用する
  • 文字列をフィルタリングする際は大文字・小文字の区別を考慮する

関連 API リファレンス

Create Meter

顧客の消費量を追跡するための使用量 Meter の作成および設定に関する API リファレンス

Ingest Usage Events

Billing 計算のため、設定済みの Meter に使用イベントを送信する API リファレンス
最終更新日 2026年8月17日