# 使用量の分析とクエリ 従量使用状況データをクエリおよび分析する方法をご紹介します。 Meter Usage Analytics API を使用して、顧客の使用量データをクエリおよび分析します。これにより、カスタム使用状況ダッシュボードの構築、レポートの生成、メーター全体の消費パターンの決定が可能になります。 この API はパブリックプレビューで利用できます。 でこの API へのアクセスをリクエストできます。 ## 使用状況データをクエリ Meter Usage Analytics API は、指定された期間内の顧客の使用状況の集計データを返します。期間でデータをクエリしたり、メーターのディメンションでフィルタリングしたり、複数のメーターで同時にクエリしたりできます。 > API パラメーターは、2025-09-30.preview リリースで更新されました。リクエストとレスポンスの形式がどのように変更されたかについては、[変更ログ](https://docs.stripe.com/changelog/clover/2025-09-30/update-meter-usage-fields.md) をご覧ください。 ### 単一メーターの使用状況を取得する 特定の顧客と時間範囲の使用状況データを取得する: ```curl curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \ -u "<>:" \ -d starts_at=1735689600 \ -d ends_at=1738368000 \ -d customer={{CUSTOMER_ID}} \ -d "meters[0][meter]"={{METER_ID}} \ -d value_grouping_window=day \ --data-urlencode timezone="America/New_York" ``` ### メーターディメンションでフィルタリングおよびグループ化したメーターの使用状況を取得する プレミアム階層でフィルタリングされ、モデルごとにグループ化されている使用状況データをクエリ: ```curl curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \ -u "<>:" \ -d starts_at=1735689600 \ -d ends_at=1738368000 \ -d customer={{CUSTOMER_ID}} \ -d "meters[0][meter]"={{METER_ID}} \ -d "meters[0][dimension_group_by_keys][0]"=model \ -d "meters[0][dimension_filters][tier]"=premium \ -d value_grouping_window=day ``` ### テナントでフィルタリングされたメーターの使用状況を取得する プレミアム階層でフィルタリングされ、モデルごとにグループ化されている使用状況データをクエリ: ```curl curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \ -u "<>:" \ -d starts_at=1735689600 \ -d ends_at=1738368000 \ -d customer={{CUSTOMER_ID}} \ -d "meters[0][meter]"={{METER_ID}} \ -d "meters[0][tenant_filters][user_id]"=a8238bf39a1 \ -d value_grouping_window=day ``` ### 複数のメーターの使用状況を取得 さまざまなフィルターとグループを使用して、複数のメーターの使用状況をクエリします。 ```curl curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \ -u "<>:" \ -d starts_at=1735689600 \ -d ends_at=1738368000 \ -d customer={{CUSTOMER_ID}} \ -d "meters[0][meter]"={{METER_ID_1}} \ -d "meters[0][dimension_group_by_keys][0]"=model \ -d "meters[0][dimension_group_by_keys][1]"=tier \ -d "meters[1][meter]"={{METER_ID_2}} \ -d "meters[1][dimension_filters][region]"=us-east \ -d value_grouping_window=day ``` ### 使用状況ダッシュボードの構築 API データを使用して、さまざまなディメンションの使用状況を示す積み上げグラフなどの視覚化を作成できます。次の例は、モデル別の API 使用状況を示すグラフのデータを構造化する方法を示しています。 ```curl curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \ -u "<>:" \ -d starts_at=1735689600 \ -d ends_at=1738368000 \ -d customer={{CUSTOMER_ID}} \ -d "meters[0][meter]"={{METER_ID}} \ -d "meters[0][dimension_group_by_keys][0]"=model \ -d value_grouping_window=day ``` このリクエストへの応答の例を次に示します。 **レスポンスを表示** ```json { "data": [ { "starts_at": 1735689600, "ends_at": 1735776000, "value": 1500, "meter": "mtr_1234567890", "dimensions": { "model": "gpt-4" } }, { "starts_at": 1735689600, "ends_at": 1735776000, "value": 800, "meter": "mtr_1234567890", "dimensions": { "model": "gpt-3.5-turbo" } }, { "starts_at": 1735776000, "ends_at": 1735862400, "value": 2100, "meter": "mtr_1234567890", "dimensions": { "model": "gpt-4" } }, { "starts_at": 1735776000, "ends_at": 1735862400, "value": 950, "meter": "mtr_1234567890", "dimensions": { "model": "gpt-3.5-turbo" } } ] } ``` このサンプルコードを使用して、バックエンドの API からデータを引き出し、フロントエンドで積み上げ棒グラフとしてユーザーに表示します。 **バックエンド** ```javascript // Step 1: Extract the data from the Stripe API response const data = stripeApiResponse.data; // Step 2: Create a dictionary to store the processed data const processedData = {}; // Step 3: Iterate through the data and organize it by date and model data.forEach(point => { const date = new Date(point.bucket_start_time * 1000).toISOString().split('T')[0]; const model = point.dimensions.model; const value = point.bucket_value; if (!processedData[date]) { processedData[date] = {}; } processedData[date][model] = value; }); // Step 4: Create a list of unique models and sort them const models = [...new Set(data.map(point => point.dimensions.model))].sort(); // Step 5: Prepare the data for charting const chartData = []; Object.keys(processedData).sort().forEach(date => { const dataPoint = { date }; let cumulativeValue = 0; models.forEach(model => { const value = processedData[date][model] || 0; dataPoint[`${model}_start`] = cumulativeValue; cumulativeValue += value; dataPoint[`${model}_end`] = cumulativeValue; dataPoint[model] = value; // For simple stacked charts }); chartData.push(dataPoint); }); // Return chart data for front end chart library usage return chartData; ``` **フロントエンド** ```javascript // Step 1: Fetch usage chart data from your back end const chartData = await fetch('/api/customer_usage/:customer_id').then(r => r.json()); // Step 2: Extract unique models from the chart data const models = Object.keys(chartData[0]).filter(key => key !== 'date' && !key.endsWith('_start') && !key.endsWith('_end') ); // Step 3: Use the chart data to create your stacked bar chart // Example using D3 or Recharts: createStackedChart({ data: chartData.map(point => ({ date: point.date, 'gpt-4': point['gpt-4'] || 0, 'gpt-3.5-turbo': point['gpt-3.5-turbo'] || 0 })), stackKeys: models, xKey: 'date', title: 'Daily API Usage by Model' }); ``` ### レート制限 Meter Usage Analytics API には、Stripe 全体の API レート制限とは別に、アカウントごとに 1 秒あたり 100 リクエストという独自のレート制限があります。この制限を超えると、API は `429 Too Many Requests` ステータスコードを返します。 ### イベントのタイムスタンプの粒度 Meter Usage Analytics API は、イベントのタイムスタンプを最も近い15分に切り捨てます。たとえば、`event_timestamp` が `08:42:15` のイベントは、分析データベースでは `08:30:00` のタイムスタンプで保管されます。 ## ベストプラクティス ### データの鮮度を処理する 使用状況データには若干の遅延が発生する場合があります。レスポンスの `data_refreshed_at` フィールドを使用して、データの鮮度を把握できます。リアルタイムのダッシュボードやアラートを構築する際には、このレイテンシーも考慮してください。 ### クエリをカスタマイズする 次のベストプラクティスに従います。 - 適切な `value_grouping_window` 値を使用して、細かさとパフォーマンスのバランスを取ります。 - `dimension_filters` を適用して、特定のセグメントのみが必要な場合にデータ量を減らします。 - 関連する使用状況パターンを分析する際に、1 回のリクエストで複数のメーターをクエリ。 ### データサイズの制限 応答が過度に大きくなるのを防ぐために、メーターごとに次の制限が適用されます。 - 最大 5 `meters` (メートル) - 最大 2 つの `dimension_group_by_keys` - 最大 10 個の `dimension_filters` - 最大 3 つの `tenant_filters` ### エラーを処理する API は標準 HTTP ステータスコードと構造化されたエラー応答を返します。 ```json { "error": { "type": "invalid_request_error", "code": "invalid_time_range", "message": "Param start_time should not be greater than end_time" } } ```