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をクリックします。
これでメーターは使用量イベントを受信して集計できる状態になりました。

ProductでのMeterのリンク

メーターを作成したら、従量課金を有効にするためにProductへリンクする必要があります。このプロセスにより、メーターの使用量データと顧客への請求に使用する料金ルールが関連付けられます。 メーターをProductにリンクすると、使用量の追跡と請求が連携されます:
  • Productは料金ルールと請求動作を定義します
  • Meterは請求計算に使用する使用量データを提供します
  • 複雑な請求シナリオでは、1つのProductに複数のMeterをリンクできます

Product設定のプロセス

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

Choose Usage-Based Billing Product Type

Productの作成または編集ページに移動し、料金タイプとしてUsage Based Billingを選択します。
2

Select Associated Meter

Associated Metersをクリックして、メーター選択パネルを開きます。このパネルでは、このProductの使用量を追跡するMeterを設定できます。
3

Add Your Meter

メーター選択パネルで:
  1. Add Metersをクリックして使用可能なメーターを表示します
  2. ドロップダウンリストから作成したメーターを選択します
  3. 選択したメーターがProduct設定に表示されます
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単位
  • 単位あたりの料金:$0.50
  • 顧客の使用量:250単位
  • 計算:(250 - 100) × $0.50 = $75.00を請求
無料しきい値は、フリーミアムモデル、トライアル期間、またはプランに含まれる基本利用枠を顧客に提供する場合に適しています。
無料しきい値は各請求サイクルに適用されるため、顧客には毎月、または設定した請求スケジュールに応じて新しい利用枠が付与されます。
6

Save Configuration

メーターと料金設定を確認し、Save Changesをクリックして設定を確定します。
これでProductは従量課金用に設定され、測定した消費量に基づいて顧客に自動請求されます。
次に行われること:
  • メーターに送信された使用量イベントが追跡・集計されます
  • 料金ルールが請求計算に自動適用されます
  • 各請求サイクル中の実際の消費量に基づいて顧客に請求されます
1つのProductあたり最大50個のMeterを追加できるため、API呼び出し、ストレージ、コンピューティング時間、カスタムメトリクスなど、複数の観点にわたる高度な使用量追跡が可能です。

使用量イベントの送信

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

イベント構造

各使用量イベントには、次の必須フィールドを含める必要があります:
string
必須
このイベントを一意に識別する識別子。すべてのイベント間で一意である必要があります。
string
必須
この使用量の帰属先となるDodo Paymentsの顧客ID。
string
必須
メーター設定と一致するイベント名。イベント名によって適切なメーターがトリガーされます。
string
イベント発生時刻のISO 8601タイムスタンプ。指定しない場合は現在のUTCタイムスタンプがデフォルトになります。過去1時間以内かつ未来5分以内である必要があり、この範囲外のタイムスタンプは拒否されます。
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リクエストを送信するのではなく、イベントをバッファリングしてバッチでフラッシュします。
5xxと429のみをリトライし、その他の4xxはリトライしません。 サーバーエラー(5xx)とレート制限(429)では、指数バックオフを使用してリトライします。400/422のバリデーションエラーはリトライしないでください。ペイロードの形式が正しくないため、毎回失敗します。修正して再送信してください。リトライ後も失敗するイベントはキューに入れ、失われないようにします。
タイムスタンプを意図的に設定します。 リアルタイムイベントではtimestampを省略すると、現在のUTCタイムスタンプがデフォルトで使用されます。遅延イベントやバッチイベントでは、正しい請求期間に使用量が反映されるよう、ISO 8601形式で明示的に設定します。許容範囲は狭く、1時間を超えて過去のイベント、または5分を超えて未来のイベントは拒否されます。過去データのバックフィルには対応していないため、バッファリングしたイベントは1時間以内にフラッシュしてください。
集計対象のメタデータは文字列ではなく数値として送信します。 メーターのOver Property(Sum、Max、Last)で参照されるプロパティは、数値型である必要があります。{ "tokens": 150 }であり、{ "tokens": "150" }ではありません。文字列値は集計されません。

従量課金の分析

包括的な分析ダッシュボードで従量課金データを監視・分析できます。顧客の消費パターン、メーターのパフォーマンス、請求の傾向を追跡して、料金戦略を最適化し、使用状況を把握します。

概要分析

Overviewタブでは、従量課金のパフォーマンスを包括的に確認できます:

アクティビティメトリクス

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

メーター数量チャート

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

イベント分析

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

イベント情報の表示

イベントテーブルには、個々の使用量イベントについて次の列が表示されます:
  • Event Name:使用量イベントを生成した具体的なアクションまたはトリガー
  • Event ID:各イベントインスタンスの一意の識別子
  • Customer ID:イベントに関連付けられた顧客
  • Timestamp:イベントが発生した時刻
このビューでは顧客全体の個々の使用量イベントを追跡・監視でき、請求計算と使用パターンを透明性のある形で確認できます。

顧客分析

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

利用可能なデータ列

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

テーブルの機能

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

集計の例

さまざまな集計タイプの動作を示す実用的な例を紹介します:

集計タイプについて

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

実装例

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

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

特定のエンドポイントへのAPI呼び出しのみをカウントする:フィルター設定:
  • プロパティ:endpoint
  • 比較演算子:equals
  • 値:/v1/orders
サンプルイベント:
結果:フィルター条件に一致するイベントがカウントされます。異なるエンドポイントのイベントは無視されます。

トラブルシューティング

従量課金の実装に関する一般的な問題を解決し、正確な追跡と請求を実現します。

一般的な問題

従量課金に関する問題の多くは、次のカテゴリに分類されます:
  • イベントの配信および処理の問題
  • メーター設定の問題
  • データ型と形式のエラー
  • 顧客IDと認証の問題

デバッグ手順

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

解決策と修正方法

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

関連APIリファレンス

Create Meter

顧客の消費量を追跡するための使用量メーターの作成と設定に関するAPIリファレンス。

Ingest Usage Events

請求計算のために設定済みのメーターへ使用量イベントを送信するためのAPIリファレンス。
最終更新日 2026年9月26日