Zeichnen Sie die Nutzung für die Abrechnung mit Amazon S3 auf

Erfahren Sie, wie Sie Nutzungsereignisse in großen Mengen mit einem Amazon S3 Storage Bucket aufzeichnen.

Sie müssen die Nutzung in Stripe aufzeichnen, um Ihren Kundinnen/Kunden in jedem Abrechnungszeitraum korrekte Beträge in Rechnung zu stellen. Um die Nutzung aufzuzeichnen, können Sie Zählernutzungsereignisse von Ihrem Amazon S3-Speicher-Bucket an Stripe senden. Stripe analysiert, validiert und wandelt die Nutzungsdaten in Zählerereignisse um.

Nachdem die Ereignisse erfolgreich hochgeladen wurden, können Sie sie auf Ihrer Abonnementrechnung sehen.

Bevor Sie loslegen

Sie müssen über Folgendes verfügen:

Admin-Kontozugriff auf das Stripe-Dashboard
AWS-Kontozugriff auf die AWS Management Console und Ihren S3-Bucket

Zählernutzungsereignisse hochladen

Sie können Ihre Zählernutzungsereignisse als CSV-, JSON- oder JSON Lines-Datei hochladen.

Benötigen Sie Unterstützung für ein anderes Dateiformat?

Wenn Sie Dateien mit einer anderen Struktur oder in einem nutzerdefinierten Format hochladen möchten, kontaktieren Sie uns.

Dateiformat und Felder

Stellen Sie sicher, dass Ihre Datei dem Beispieldateiformat entspricht:

CSV-Dateiformat

Folgen Sie dem Zählerereignis--Schema, wenn Sie die folgenden Felder in Ihre Datei aufnehmen:

Feld	Beschreibung
`identifier`	Eine eindeutige Kennung für das Ereignis. Wenn Sie keine angeben, kann Stripe die eindeutige Kennung generieren. Es wird empfohlen, eine global eindeutige Kennung zu verwenden.
`timestamp`	Der Zeitpunkt, zu dem das Ereignis aufgetreten ist, gemessen in Sekunden seit der Unix-Epoche.
`event_name`	Der Name des Zählerereignisses.
`payload_columns`	Die Spalten, die Schlüsselnamen für Kunden- und numerische Nutzungswerte enthalten: `payload_stripe_customer_id`: Die Kunden-ID, für die das Ereignis erstellt wird. `payload_value`: Der numerische Nutzungswert des Zählerereignisses. Standardmäßig lautet der Spaltenname `payload_value`. Wenn Sie beim Erstellen des Zählerereignisses einen anderen Feldnamen angegeben haben, müssen Sie den Spaltennamen so aktualisieren, dass er mit dem Schlüsselwert übereinstimmt. Wenn Sie z. B. Token in `value_settings` angeben, ändern Sie den Spaltennamen in `payload_tokens`.

Vorbereiten Ihrer Dateien in Amazon S3

Sie können Ihre Verbindungskonfiguration mit ordnungsgemäß formatierten Daten in Ihrem S3-Bucket validieren. Der Konfigurationsvorgang zeigt die verfügbaren Dateien an und führt beim Konfigurieren der Verbindung eine erste Synchronisierung durch.

Navigieren Sie zu Ihrer Amazon S3-Konsole.
Speichern Sie Ihre Dateien in einem dafür vorgesehenen S3-Bucket, der gemäß Ihren Importpräferenzen organisiert ist. Befolgen Sie bei Bedarf die AWS-Richtlinien, um einen S3-Bucket zu erstellen.
Für einen erfolgreichen Abruf verlangt Stripe dass die Dateinamen den S3-Objektbenennungskonventionen entsprechen und die Dateigröße maximal 1 GB beträgt.
Merken Sie sich den Bucket-Namen und die Region, da Sie sie für zukünftige Schritte benötigen.
Lassen Sie Ihre AWS Management Console geöffnet, um später eine IAM-Rolle zu konfigurieren.

Konfigurieren von Amazon S3 Connector zum Importieren von Dateien

Verwenden Sie zunächst das Stripe-Dashboard, um den Amazon S3 Connector hinzuzufügen.

Klicken Sie im Stripe-Dashboard auf der Registerkarte Datenverwaltung > Konnektoren auf Konnektor hinzufügen.
Wählen Sie im Dialogfeld Choose connector(Konnektor auswählen) die Option Amazon S3.
Geben Sie im Dialogfeld Anforderungen einen eindeutigen Namen für Connectorname ein und klicken Sie dann auf Weiter.
Führen Sie die Schritte im Dialogfeld Berechtigungen aus.

Konfigurieren Sie als Nächstes die entsprechenden Berechtigungen für Amazon S3 Connector.

Navigieren Sie in der AWS Management Console zur IAM-Konsole.
Erstellen Sie eine nutzerdefinierte Vertrauensrichtlinie:
- Klicken Sie im Navigationsbereich auf Richtlinien > Richtlinie erstellen.
- Wählen Sie JSON aus und ersetzen Sie den vorhandenen Richtlinientext, indem Sie den im Stripe-Dashboard bereitgestellten Codeblock kopieren und einfügen.
- Ersetzen Sie im Abschnitt Resource des Codeblocks Richtlinieneditor USER_TARGET_BUCKET durch den gewünschten Bucket-Namen.
- Klicken Sie auf Weiter.
- Fügen Sie unter Richtliniendetails einen Richtliniennamen hinzu. Fügen Sie optional beliebige Tags hinzu.
- Klicken Sie auf Richtlinie erstellen.
Erstellen Sie eine Rolle:
- Klicken Sie im Navigationsbereich auf Rollen > Rolle erstellen.
- Wählen Sie Benutzerdefinierte Vertrauensrichtlinie aus, kopieren Sie den im Stripe-Dashboard bereitgestellten Codeblock und fügen Sie ihn ein.
- Klicken Sie auf Weiter.
- Suchen Sie die neu erstellte Berechtigungsrichtlinie und wählen Sie sie aus, um sie zu aktivieren, und klicken Sie dann auf Weiter.
- Kopieren Sie den vorhandenen Rollennamen, fügen Sie ihn ein und klicken Sie dann auf Rolle erstellen erstellen, um einen Rollennamen zu erstellen.

Stellen Sie dann sicher, dass eine Verbindung zwischen Stripe und Ihrem Amazon S3-Bucket hergestellt wird.

Führen Sie in der AWS Management Console die folgenden Schritte aus:
- Geben Sie Ihre AWS-Konto-ID an.
- Geben Sie den Bucket-Namen und die Region an.
- Wenn Sie Ordner verwenden, um Ihre Dateien in Ihrem Amazon S3-Bucket zu verwalten, geben Sie einen Ordner im obigen Bucket an. Wir rufen nur Daten aus dem angegebenen Ordner ab, nicht aus dem gesamten Bucket.
Nachdem Sie einen neuen Connector eingerichtet haben, wird in der Dateivorschau überprüft, ob Ihre Anmeldedaten Stripe mit dem erwarteten Amazon S3-Bucket und -Ordner verbinden. Stripe ruft alle Daten ab, die in den letzten 90 Tagen geändert wurden. Dies geschieht alle 5 Minuten für Objekte, deren Datum LastModified nach der letzten Synchronisierung liegt.
Vorschau der im verbundenen Amazon S3-Bucket verfügbaren Dateien:
- Dateinamen müssen weniger als 255 Zeichen lang sein und die entsprechende Erweiterung enthalten, z. B .csv, .json oder .jsonl.
- Erstimporte und wiederkehrende Importe weisen ein erwartetes Dateiformat auf:
  - JSON-Dateien verfügen über Billing Meter Event Transaction Template - JSON.
  - JSON Lines-Dateien verfügen über Billing Meter Event Transaction Template - JSONLINE.
  - CSV-Dateien verfügen über Billing Meter Event Transaction Template - CSV.
Um eine aktive Datenverbindung zu erstellen und den Datenimport zu initiieren, klicken Sie auf Fertig.

Nachdem Sie eine Datei in den Amazon S3 Connector hochgeladen haben, werden die Nutzungsereignisse innerhalb von 5 Minuten aktualisiert. Dies kann länger dauern, wenn Ihr Bucket viele unverarbeitete Dateien enthält.

Sie können den Status und die Details der verarbeiteten Dateien auf der Registerkarte Importsatz im Stripe-Dashboard überprüfen.

Ratenbegrenzungen

Sie können eine beliebige Anzahl von Dateien und Datensätzen in Ihren Amazon S3-Bucket hochladen. Laden Sie alle 10 Sekunden oder wenn die aktuelle Datei eine Million Datensätze erreicht, eine Datei hoch, je nachdem, was zuerst eintritt. Nach dem Upload können Sie Ereignisse in einer neuen Datei hinzufügen.

Vermeiden Sie es, leere Dateien zu erstellen, z. B.:

CSV-Dateien, die nur die Kopfzeile enthalten
JSON-Dateien, die nur [](leere eckige Klammern) enthalten
JSON Lines-Dateien, die nur {}(leere geschweifte Klammern) enthalten

Amazon S3 akzeptiert zwar Dateien mit Bytes ungleich Null, aber sie erhöhen die Objekt- und Dateizahl, was zu Verzögerungen bei der Abfrage von Dateien führen kann.

Amazon S3 fragt maximal 50 Dateien oder bis zu 10 GB Daten ab und verarbeitet Ihre hochgeladenen Daten mit einer Rate von 10.000 Ereignissen pro Sekunde. Wenn Sie große Dateien oder eine große Anzahl von Dateien hochladen, werden die Daten von Stripe abgefragt und verarbeitet, um diese Durchsatzrate beizubehalten.

Wenn Sie beispielsweise täglich 100 Dateien mit jeweils 100.000 Datensätzen hochladen, kann die Verarbeitung des gesamten Datensatzes (10 Millionen Ereignisse) etwa 17 Minuten dauern.

Fehler melden und beheben

Stripe fragt die Dateien ab, die Sie in den Amazon S3-Bucket hochladen, und verarbeitet diese Dateien dann asynchron. Wenn wir bei der Verarbeitung Fehler feststellen, benachrichtigt Stripe Sie mithilfe von Ereignissen.

Formatprobleme

Ungültige Datei- oder Datensatzformatfehler treten auf, wenn der Inhalt der hochgeladenen Datei Formatierungs- oder Datenprobleme enthält.

Sie können diese Ereignisse über einen Webhook-Endpoint abonnieren. Je nach Ereignistyp können Sie Ihre eigene Logik implementieren, um diese Fehler zu beheben.

Ereignis Beschreibung Nutzlasttyp

data_management.import_set.failed Stripe erstellt ein Ereignis des Typs data_management.import_set.failed, wenn die Verarbeitung für eine vollständige Datei fehlschlägt. Wenn Sie beispielsweise eine Pflichtspalte auslassen, wie zum Beispiel event_name. Den Grund für den Fehler finden Sie im Parameter failed_reason des Ereignisses. Beheben Sie ihn, bevor Sie den Upload erneut durchführen. Snapshot

Ereignis	Beschreibung	Nutzlasttyp
`data_management.import_set.failed`	Stripe erstellt ein Ereignis des Typs data_management.import_set.failed, wenn die Verarbeitung für eine vollständige Datei fehlschlägt. Wenn Sie beispielsweise eine Pflichtspalte auslassen, wie zum Beispiel `event_name`. Den Grund für den Fehler finden Sie im Parameter `failed_reason` des Ereignisses. Beheben Sie ihn, bevor Sie den Upload erneut durchführen.	`Snapshot`
`data_management.import_set.succeeded`	Stripe erstellt ein Ereignis des Typs data_management.import_set.succeeded, wenn einzelne Datensätze in einer teilweise verarbeiteten Datei fehlerhaft sind. Wenn Sie beispielsweise den Wert für ein Pflichtfeld auslassen, wie beispielsweise `stripe_customer_id` oder `event_name`. Details zu den fehlerhaften Datensätzen finden Sie im `status`-Parameter des Ereignisses. Der Status `succeeded_with_errors` gibt an, dass mindestens ein Datensatz aufgrund einer ungültigen Formatierung fehlerhaft ist. `result.errors` gibt die Anzahl der Datensätze an, die fehlerhaft sind, und die `file_id` der Datei, die die fehlerhaften Datensätze enthält. Verwenden Sie die Files API, um eine vollständige Liste der fehlerhaften Datensätze und detaillierte Fehlerbeschreibungen herunterzuladen.	`Snapshot`

data_management.import_set.succeeded

Stripe erstellt ein Ereignis des Typs data_management.import_set.succeeded, wenn einzelne Datensätze in einer teilweise verarbeiteten Datei fehlerhaft sind. Wenn Sie beispielsweise den Wert für ein Pflichtfeld auslassen, wie beispielsweise stripe_customer_id oder event_name.

Details zu den fehlerhaften Datensätzen finden Sie im status-Parameter des Ereignisses. Der Status succeeded_with_errors gibt an, dass mindestens ein Datensatz aufgrund einer ungültigen Formatierung fehlerhaft ist. result.errors gibt die Anzahl der Datensätze an, die fehlerhaft sind, und die file_id der Datei, die die fehlerhaften Datensätze enthält.

Verwenden Sie die Files API, um eine vollständige Liste der fehlerhaften Datensätze und detaillierte Fehlerbeschreibungen herunterzuladen.

Snapshot

Datenprobleme

Bei Dateien mit korrekter Formatierung kann die Verarbeitung fehlschlagen, wenn die Daten in der Datei ungültig sind, z. B. falsche Werte für event_name oder stripe_customer_id.

Ausführliche Informationen zu diesen Fehlern erhalten Sie, indem Sie die folgenden Ereignisse mithilfe eines Webhook-Endpoints abonnieren.

Ereignis	Beschreibung	Nutzlasttyp
`v1.billing.meter.error_report_triggered`	Dieses Ereignis tritt auf, wenn ein Zähler ungültige Nutzungsereignisse aufweist.	`thin`
`v1.billing.meter.no_meter_found`	Dieses Ereignis tritt auf, wenn Nutzungsereignisse fehlende oder ungültige Zähler-IDs aufweisen.	`thin`

Achtung

Um ein Ereignisziel zu erstellen, das Thin-Ereignisse abonniert, aktivieren Sie Workbench in Ihren Entwicklereinstellungen.

Beispiel-Nutzlasten

Im Folgenden finden Sie eine Beispielnutzlast für ein v1.billing.meter.error_report_triggered-Ereignis.

{
  "id": "evt_test_65R2GpwDsnmpzihMjdT16R2GDhI4SQdXJGRbvn7JA8mPEm",
  "object": "v2.core.event",
  "created": "2024-08-28T20:54:12.051Z",
  "data": {
    "developer_message_summary": "There is 1 invalid event",
    "reason": {
      "error_count": 1,
      "error_types": [
        {

Fehlercodes

Der reason.error_types.code stellt die Fehlerkategorisierung bereit, die den Fehler ausgelöst hat. Mögliche Fehlercodes sind:

meter_event_customer_not_found
meter_event_no_customer_defined
meter_event_dimension_count_too_high
archived_meter
timestamp_too_far_in_past
timestamp_in_future
meter_event_value_not_found
meter_event_invalid_value
no_meter: (wird nur für den Ereignistyp v1.billing.meter.no_meter_found unterstützt)

Ereignisse überwachen

Sie können Ereignisse überwachen, indem Sie ein Ereignisziel einrichten.

Klicken Sie auf der Registerkarte Ereignisziele in Workbench auf Neues Ziel erstellen. Verwenden Sie alternativ diese Vorlage, um ein neues Ziel in Workbench mit diesen beiden vorgewählten Ereignistypen zu konfigurieren.
Klicken Sie auf ** Erweiterte Optionen anzeigen ** und wählen Sie dann Thin als Nutzlaststil.
Wählen Sie v1.billing.meter.error_report_triggered und v1.billing.meter.no_meter_found aus der Ereignisliste.

Erstellen Sie einen Handler, um das Ereignis zu verarbeiten.

Testen Sie Ihren Handler, indem Sie einen lokalen Listener mit derStripe-CLI konfigurieren, um Ereignisse zu Testzwecken an Ihren lokalen Computer zu senden, bevor Sie den Handler in der Produktionsumgebung bereitstellen. Verwenden Sie das Flag --forward-thin-to, um anzugeben, an welche URL die thin-Ereignisse weitergeleitet werden sollen, und das Flag --thin-events, um anzugeben, welche Thin-Ereignisse an Ihre Anwendung weitergeleitet werden sollen. Sie können alle Thin-Ereignisse mit einem Sternchen (*) oder eine Teilmenge von Thin-Ereignissen weiterleiten.
```
$ stripe listen --forward-thin-to localhost:4242/webhooks --thin-events "*"
```
Lösen Sie Testereignisse für Ihren Handler aus. Verwenden Sie die Trigger-Funktion, um die folgenden Befehle auszuführen, die die jeweiligen Ereignisse in Ihrem Konto zum Testen simulieren.
```
$ stripe trigger v1.billing.meter.error_report_triggered --api-key <your-secret-key>
$ stripe trigger v1.billing.meter.no_meter_found --api-key <your-secret-key>
```
Wenn Sie Ereignisse mit einem Webhook-Endpoint verarbeiten, überprüfen Sie die Webhook-Signaturen, um Ihren Endpoint zu sichern und zu überprüfen, ob alle Anforderungen von Stripe stammen.
Korrigieren Sie die ungültigen Ereignisse und speichern Sie sie in einer neuen Datei. Laden Sie dann die Datei zur Verarbeitung in Ihren Amazon S3-Bucket hoch.