Analyse und Abfrage des ZählerverbrauchsPrivate Vorschau

Erfahren Sie, wie Sie Daten zur Nutzung des Zählers abfragen und analysieren können.

Verwenden Sie die Meter Usage Analytics API, um die Zählernutzungsdaten Ihrer Kundinnen und Kunden abzufragen und zu analysieren. Damit können Sie die Dashboards für benutzerdefinierte Nutzung erstellen, Berichte generieren und Verbrauchsmuster über Ihre Zähler hinweg ermitteln.

Abfrage von Nutzungsdaten

Die Zählernutzungsanalyse-API liefert aggregierte Nutzungsdaten für eine/n Kunden/Kundin innerhalb eines bestimmten Zeitintervalls. Sie können die Daten nach Zeiträumen abfragen, nach Zählerdimensionen filtern und mehrere Zähler gleichzeitig abfragen.

Nutzung für einen einzelnen Zähler abrufen

Rufen Sie Nutzungsdaten für eine/n bestimmte/n Kunden/Kundin und Zähler über einen bestimmten Zeitraum ab:

Rufen Sie die Nutzung für einen Zähler gefiltert und gruppiert nach Zählerdimension ab

Abfrage von Nutzungsdaten, die nach Premiumstufe gefiltert und nach Modell gruppiert sind:

Nutzung über mehrere Zähler abrufen

Abfrage der Nutzung über mehrere Zähler mit verschiedenen Filtern und Gruppierungen:

Dashboards zur Nutzung erstellen

Sie können die API-Daten verwenden, um Visualisierungen zu erstellen, wie z.B. gestapelte Diagramme, die die Nutzung über verschiedene Dimensionen hinweg zeigen. Das folgende Beispiel zeigt, wie Sie Daten für ein Diagramm strukturieren können, das die API Nutzung nach Modell zeigt:

Eine Beispielantwort auf diese Anfrage sieht so aus:

Antwort ansehen

{
  "data": [
    {
      "bucket_start_time": 1735689600,
      "bucket_end_time": 1735776000,
      "bucket_value": 1500,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "bucket_start_time": 1735689600,
      "bucket_end_time": 1735776000,
      "bucket_value": 800,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-3.5-turbo"
      }
    },
    {
      "bucket_start_time": 1735776000,
      "bucket_end_time": 1735862400,
      "bucket_value": 2100,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "bucket_start_time": 1735776000,
      "bucket_end_time": 1735862400,
      "bucket_value": 950,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-3.5-turbo"
      }
    }
  ]
}

Verwenden Sie diesen Beispielcode, um Daten aus der API in Ihrem Backend zu ziehen und sie den Nutzern/innen als gestapeltes Balkendiagramm in Ihrem Frontend anzuzeigen.

Ihr Backend

// 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;

Ihr Frontend

// 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'
});

Ratenbegrenzungen

Die Zählernutzungsanalyse-API hat eine eigene Begrenzung von 100 Anfragen pro Sekunde und Konto, die von den allgemeinen API-Begrenzungen von Stripe getrennt ist. Wenn Sie diesen Wert überschreiten, gibt die API den Status 429 Too Many Requests zurück.

Best Practices

Umgang mit Datenaktualität

Nutzungsdaten können eine leichte Verzögerung aufweisen. Sie können das Feld data_refreshed_at in der Antwort verwenden, um die Aktualität der Daten zu verstehen. Berücksichtigen Sie diese Latenz auch bei der Erstellung von Dashboards oder Warnmeldungen in Echtzeit.

Passen Sie Ihre Abfragen an

Befolgen Sie diese Best Practices:

Verwenden Sie geeignete value_grouping_window-Werte, um ein Gleichgewicht zwischen Granularität und Leistung herzustellen.
Wenden Sie dimension_filters an, um das Datenvolumen zu reduzieren, wenn Sie nur bestimmte Segmente benötigen.
Fragen Sie mehrere Zähler in einer einzigen Anfrage ab, wenn Sie verwandte Nutzungsmuster analysieren.

Begrenzungen der Datengröße

Um übermäßig große Antworten zu vermeiden, gelten die folgenden Grenzwerte pro Zähler:

Maximal 2 dimension_group_by_keys
Maximal 10 Dimensionsfilter
Maximal 3 tenant_filters

Umgang mit Fehlern

Die API gibt standardmäßige HTTP-Status-Codes und strukturierte Fehlerantworten zurück:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_time_range",
    "message": "Param start_time should not be greater than end_time"
  }
}