# Enregistrer l’utilisation pour la facturation à l’aide d’Amazon S3 Découvrez comment enregistrer des événements d’utilisation en masse à l’aide d’un compartiment de stockage Amazon S3. Vous devez enregistrer l’utilisation dans Stripe pour facturer à vos clients les montants corrects à chaque période de facturation. Pour enregistrer l’utilisation, vous pouvez envoyer des événements de mesure de l’utilisation à Stripe à partir de votre compartiment de stockage Amazon S3. Stripe analyse, valide et transforme les données d’utilisation en événements de mesure. Une fois les événements chargés avec succès, vous pouvez les voir sur votre facture d’abonnement. ## Before you begin Assurez-vous de disposer des éléments suivants : - Accès du compte administrateur au [Dashboard Stripe](https://dashboard.stripe.com/dashboard) - Accès du compte AWS à la [console de gestion AWS](https://console.aws.amazon.com/) et à votre compartiment S3 ## Importer les événements de mesure de l’utilisation Vous pouvez charger les événements de mesure de l’utilisation sous la forme d’un fichier CSV, JSON ou JSON Lines. > #### Vous avez besoin d'aide pour un autre format de fichier ? > > Si vous souhaitez charger des fichiers avec une structure différente ou dans un format personnalisé, [contactez-nous](mailto:user-data-acquisition-platform@stripe.com). ### Format du fichier et champs Assurez-vous que votre fichier respecte le format de fichier en exemple : #### CSV ![Exemple de format de fichier CSV](https://b.stripecdn.com/docs-statics-srv/assets/udap_ubb_csv_format.e5c12ef6a48b407ae9c0cf6c3b873aeb.png) Format de fichier CSV #### JSON ```json [ { "identifier": "26ac9e54-6a13-4b2e-90b0-fedae80bb8f7", "timestamp": 1692852080, "event_name": "ai_search_api", "payload": { "value": 200, "stripe_customer_id": "cus_123" } }, { "timestamp": 1692852080, "event_name": "ai_search_api", "payload": { "value": 500, "stripe_customer_id": "cus_123" } } ] ``` #### JSON Lines ```jsonline {"identifier":"123456","timestamp":1692852080,"event_name":"ai_search_api","payload":{"value":200,"stripe_customer_id":"cus_123"}} {"timestamp":1692852080,"event_name":"ai_search_api","payload":{"value":500,"stripe_customer_id":"cus_123"}} ``` Suivez le modèle de [l’événement de mesure](https://docs.stripe.com/api/billing/meter-event/object.md) lorsque vous incluez les champs suivants dans votre fichier : | Champ | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `identifier` | Un identifiant unique de l’événement. Si vous n’en fournissez pas, Stripe peut générer l’identifiant unique. Nous vous recommandons d’utiliser un identifiant global unique. | | `timestamp` | L’heure à laquelle l’événement s’est produit, mesurée en secondes depuis l’époque Unix. | | `event_name` | Le nom de l’événement de mesure. | | `payload_columns` | L’ensemble des colonnes contenant les noms de clé pour les clients et les valeurs d’utilisation numériques : - `payload_stripe_customer_id` : L’[ID client](https://docs.stripe.com/api/customers/object.md#customer_object-id) pour lequel l’événement est créé. - `payload_value` : La valeur d’utilisation numérique de l’événement de mesure. Par défaut, le nom de la colonne est `payload_value`. Si vous avez indiqué un nom de champ différent lors de la création de l’événement de mesure, vous devez mettre à jour le nom de la colonne pour qu’il corresponde à la valeur de la clé. Par exemple, si vous indiquez des tokens dans `value_settings`, modifiez le nom de la colonne en conséquence : `payload_tokens`. | ## Préparer vos fichiers dans Amazon S3 Vous pouvez valider la configuration de votre connexion à l’aide de données bien formatées dans votre compartiment S3. Le processus de configuration affiche les fichiers disponibles et effectue une synchronisation initiale lors de la configuration de la connexion. 1. Accédez à votre [console Amazon S3](https://s3.console.aws.amazon.com/). 1. Assurez-vous de stocker vos fichiers dans un compartiment S3 désigné, organisé en fonction de vos préférences d’importation. Si nécessaire, suivez les [instructions AWS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html) pour créer un compartiment S3. Pour une récupération réussie, Stripe exige que les noms de fichiers respectent les [conventions d’appelation des objets S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html) et que les fichiers aient une taille maximale de 1 Go. 1. Notez bien le nom et la région du compartiment, car vous en aurez besoin lors des étapes suivantes. 1. Gardez votre [console de gestion AWS](https://console.aws.amazon.com) ouverte pour configurer un rôle IAM ultérieurement. ## Configurer le connecteur Amazon S3 pour importer des fichiers Tout d’abord, utilisez le Dashboard Stripe pour ajouter le connecteur Amazon S3. 1. Dans le Dashboard Stripe, sous l’onglet **Gestion des données** > [Connecteurs](https://dashboard.stripe.com/data-management/connectors), cliquez sur **Ajouter un connecteur**. 1. Dans la boîte de dialogue **Choisir un connecteur**, sélectionnez **Amazon S3**. 1. Dans la boîte de dialogue **Exigences**, saisissez un nom unique pour le **Nom du connecteur**, puis cliquez sur **Suivant**. 1. Suivez les étapes de la boîte de dialogue **Autorisations**. Ensuite, configurez les autorisations appropriées pour le connecteur Amazon S3. 1. Dans la console de gestion AWS, accédez à la [console IAM](https://console.aws.amazon.com/iam/). 1. Créez une politique d’autorisation personnalisée : - Dans le volet de navigation, cliquez sur **Politiques** > **Créer une politique**. - Sélectionnez **JSON**, puis remplacez le texte de la politique existante en copiant et collant le bloc de code fourni dans le Dashboard Stripe. - Dans la section `Resource` du bloc de code de **l’éditeur de politique**, remplacez `USER_TARGET_BUCKET` par le nom de compartiment que vous souhaitez utiliser. - Cliquez sur **Suivant**. - Sous **Détails de la politique**, ajoutez un nom. Vous pouvez également ajouter des balises. - Cliquez sur **Créer une politique**. 1. Créez un rôle : - Dans le volet de navigation, cliquez sur **Rôles** > **Créer un rôle**. - Sélectionnez **Politique d’autorisation personnalisée**, puis copiez et collez le bloc de code fourni dans le Dashboard Stripe. - Cliquez sur **Suivant**. - Recherchez et sélectionnez la politique d’autorisation nouvellement créée pour l’activer, puis cliquez sur **Suivant**. - Copiez et collez le nom de rôle fourni, puis cliquez sur **Créer un rôle** pour créer un nom de rôle. Ensuite, assurez-vous d’établir une connexion entre Stripe et votre compartiment Amazon S3. 1. Dans la console de gestion AWS, procédez comme suit : - Indiquez [l’ID de votre compte AWS](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-identifiers.html#FindAccountId). - Indiquez le nom et la région du compartiment. - Si vous utilisez des dossiers pour organiser vos fichiers dans votre compartiment Amazon S3, indiquez un dossier dans le compartiment ci-dessus. Nous récupérons uniquement les données du dossier indiqué, et non de l’ensemble du compartiment. 1. Une fois que vous avez configuré un nouveau connecteur, l’aperçu du fichier confirme que vos informations d’identification connectent Stripe au compartiment et au dossier Amazon S3 attendus. Stripe récupère toutes les données modifiées au cours des 90 derniers jours. Cela se produit toutes les 5 minutes pour les objets dont la date `LastModified` est postérieure à la dernière synchronisation. 1. Prévisualisez les fichiers disponibles dans le compartiment Amazon S3 connecté : - Les noms de fichiers doivent comporter moins de 255 caractères et inclure l’extension appropriée, par exemple `.csv`, `.json` ou `.jsonl`. - Les importations initiales et récurrentes ont un format de fichier prédéfini : - Les fichiers JSON ont un **modèle de transaction d’événement de mesure pour facturation - JSON**. - Les fichiers JSON Lines ont un **modèle de transaction d’événement de mesure pour facturation - JSONLINE**. - Les fichiers CSV ont un **modèle de transaction d’événement de mesure pour facturation - CSV**. 1. Pour créer une connexion de données active et lancer l’importation de données, cliquez sur **Terminé**. Une fois que vous avez chargé un fichier sur le connecteur Amazon S3, les événements d’utilisation sont mis à jour dans les 5 minutes. Cela peut prendre plus de temps si votre compartiment contient un grand nombre de fichiers non traités. Vous pouvez vérifier l’état et les détails des fichiers traités dans l’onglet [Ensemble de fichiers importés](https://dashboard.stripe.com/data-management/import-set) du Dashboard Stripe. ## Limites de débit Vous pouvez charger autant de fichiers et d’enregistrements que vous le souhaitez dans votre compartiment Amazon S3. Chargez un fichier toutes les 10 secondes ou lorsque le fichier en cours atteint le million d’enregistrements, selon la première éventualité. Après le chargement, vous pouvez ajouter des événements dans un nouveau fichier. Évitez de créer des fichiers vides, tels que : - Fichiers CSV qui contiennent uniquement la ligne d’en-tête - Fichiers JSON qui contiennent uniquement [](crochets vides) - Fichiers JSON Lines qui contiennent uniquement {}(accolades vides) Bien qu’Amazon S3 accepte les fichiers à octets non nuls, ils augmentent le nombre d’objets et de fichiers, ce qui peut entraîner des retards dans l’interrogation des fichiers. [Contactez le service commercial](https://stripe.com/contact/sales) si vous devez traiter 100 000 événements par seconde. Amazon S3 interroge un maximum de 50 fichiers ou jusqu’à 10 Go de données et traite vos données chargées à une cadence de 10 000 événements par seconde. Si vous téléchargez des fichiers volumineux ou un volume élevé de fichiers, Stripe interroge et traite les données pour maintenir ce débit. Par exemple, si vous téléchargez 100 fichiers contenant chacun 100 000 enregistrements par jour, le traitement de l’ensemble du jeu de données (10 millions d’événements) peut prendre environ 17 minutes. ## Signaler et gérer les erreurs Stripe interroge les fichiers que vous chargez dans le compartiment Amazon S3, puis traite ces fichiers de manière asynchrone. Si nous détectons des erreurs pendant le traitement, Stripe vous en informe par des [événements](https://dashboard.stripe.com/events). ### Problèmes de format Des erreurs de format de fichier ou d’enregistrement non valides se produisent lorsque le contenu du fichier téléchargé présente des problèmes de formatage ou de données. Vous pouvez vous abonner à ces événements à l’aide d’un [endpoint de webhook](https://dashboard.stripe.com/webhooks). En fonction du type d’événement, vous pouvez implémenter votre propre logique pour gérer ces erreurs. | Event | Description | Type de charge utile | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | | `data_management.import_set.failed` | Stripe crée un événement [data_management.import_set.failed](https://docs.stripe.com/api/events/types.md#event_types-data_management.import_set.failed) lorsque le traitement échoue pour un fichier entier. Par exemple, en cas d’omission d’une colonne obligatoire, telle que `event_name`. Vous pouvez trouver la raison de l’échec dans le paramètre `failed_reason` de l’événement et corriger le fichier avant de le télécharger à nouveau. | `Snapshot` | | `data_management.import_set.succeeded` | Stripe crée un événement [data_management.import_set.succeeded](https://docs.stripe.com/api/events/types.md#event_types-data_management.import_set.succeeded) lorsque des enregistrements individuels échouent dans un fichier partiellement traité. Par exemple, en cas d’omisson d’une valeur pour un champ obligatoire, tel que `stripe_customer_id` ou `event_name`. Vous pouvez trouver les détails des enregistrements ayant échoué dans le paramètre `status` de l’événement. Un état `succeeded_with_errors` indique qu’au moins un enregistrement a échoué en raison d’une mise en forme non valide. L’état `result.errors` indique le nombre d’enregistrements qui ont échoué et l’identification `file_id` du fichier contenant les enregistrements qui ont échoué. Utilisez l’API [Files](https://docs.stripe.com/file-upload.md#download-file-contents) pour télécharger la liste complète des enregistrements ayant échoué et les descriptions détaillées des erreurs. | `Snapshot` | ### Problèmes liés aux données Le traitement des fichiers dont la mise en forme est correcte peut échouer en raison de données non valides, telles que des valeurs incorrectes pour `event_name` ou `stripe_customer_id`. Pour obtenir des informations détaillées sur ces échecs, vous pouvez vous abonner aux événements suivants à l’aide d’un [endpoint de webhook](https://dashboard.stripe.com/webhooks). | Event | Description | Type de charge utile | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------- | | `v1.billing.meter.error_report_triggered` | Cet événement se produit quand une mesure compte des événements d’usage non valide. | `thin` | | `v1.billing.meter.no_meter_found` | Cet événement se produit quand des événements d’usage comptent des ID de mesure manquants ou non valide. | `thin` | ### Exemples de charges utiles #### Exemple d'événement de rapport d'erreur Voici un exemple de charge utile pour un événement `v1.billing.meter.error_report_triggered`. ```json { "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": [ { "code": "meter_event_no_customer_defined", "error_count": 1, "sample_errors": [ { "error_message": "Customer mapping key stripe_customer_id not found in payload.", "request": { "id": "", "idempotency_key": "37c741d8-1f7e-4adc-af16-afdca1d73b37" } } ] } ] }, "validation_end": "2024-08-28T20:54:10.000Z", "validation_start": "2024-08-28T20:54:00.000Z" }, "reason": null, "related_object": { "id": "mtr_test_61R2GlpFXJ4R3L5DN41Fb82guyGVEUmO", "type": "billing.meter", "url": "/v1/billing/meters/mtr_test_61R2GlpFXJ4R3L5DN41Fb82guyGVEUmO" }, "type": "v1.billing.meter.error_report_triggered" } ``` #### Exemple d’événement d’erreur pour un dispositif de mesure incorrect Voici un exemple de charge utile pour un événement `v1.billing.meter.no_meter_found`. ```json { "created": "2024-10-01T20:42:52.203Z", "id": "evt_test_61REarcdWIsXleUiz16REahOMTSQbAhSD0fdnF9JAUdk", "object": "v2.core.event", "context": null, "type": "v1.billing.meter.no_meter_found", "data": { "developer_message_summary": "There is 1 invalid event", "reason": { "error_count": 1, "error_types": [ { "code": "no_meter", "error_count": 1, "sample_errors": [ { "error_message": "No meter was found matching event_name d2aa8cb3-3f00-44a4-b98f-3fbd1d0e93b1.", "request": { "identifier": "df5d4002-515b-4090-8fe2-a1b1f6f5b945" } } ] } ] }, "validation_end": "2024-10-01T20:42:50.000Z", "validation_start": "2024-10-01T20:42:40.000Z" }, "livemode": false, "reason": null, "related_object": {} } ``` ### Codes d’erreur `reason.error_types.code` : indique la catégorie d’erreur déclenchée. Les codes d’erreur possibles sont les suivants : - `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` (pris en charge uniquement pour le type d’événement `v1.billing.meter.no_meter_found`) ### Écouter les événements Vous pouvez écouter des événements en configurant une [destination d’événement](https://docs.stripe.com/event-destinations.md). 1. Ouvrez l’onglet [Destinations d’événements](https://dashboard.stripe.com/webhooks) dans Workbench, puis cliquez sur **Créer une nouvelle destination**. Vous pouvez également utiliser ce [modèle](https://dashboard.stripe.com/webhooks/create?payload_style=thin&events=v1.billing.meter.error_report_triggered%2Cv1.billing.meter.no_meter_found) pour configurer une nouvelle destination dans Workbench avec ces deux types d’événements présélectionnés. 1. Cliquez sur **Afficher les options avancées**, puis sélectionnez le style de charge utile **Léger**. 1. Sélectionnez`v1.billing.meter.error_report_triggered` et `v1.billing.meter.no_meter_found` dans la liste des événements. 1. Créez un gestionnaire pour traiter l’événement. #### Python ```python import os from stripe import StripeClient from stripe.events import V1BillingMeterErrorReportTriggeredEvent from flask import Flask, request, jsonify app = Flask(__name__) api_key = os.environ.get('STRIPE_API_KEY') webhook_secret = os.environ.get('WEBHOOK_SECRET') client = StripeClient(api_key) @app.route('/webhook', methods=['POST']) def webhook(): webhook_body = request.data sig_header = request.headers.get('Stripe-Signature') try: thin_event = client.parse_thin_event(webhook_body, sig_header, webhook_secret) # Fetch the event data to understand the failure event = client.v2.core.events.retrieve(thin_event.id) if isinstance(event, V1BillingMeterErrorReportTriggeredEvent): meter = event.fetch_related_object() meter_id = meter.id # Record the failures and alert your team # Add your logic here return jsonify(success=True), 200 except Exception as e: return jsonify(error=str(e)), 400 if __name__ == '__main__': app.run(port=4242) ``` 1. Testez votre gestionnaire en configurant un [écouteur local](https://docs.stripe.com/cli/listen) avec [l’interface de ligne de commande Stripe](https://docs.stripe.com/stripe-cli.md) pour envoyer des événements à votre ordinateur local à des fins de test avant de déployer le gestionnaire en production. Utilisez l’indicateur `--forward-thin-to` pour préciser l’URL vers laquelle transférer les événements `thin` et l’indicateur `--thin-events` pour préciser les événements légers à transférer à votre application. Vous pouvez transférer tous les événements légers marqués d’un astérisque (`*`) ou un sous-ensemble d’événements. ```sh $ stripe listen --forward-thin-to localhost:4242/webhooks --thin-events "*" ``` 1. Déclenchez des événements de test dans votre gestionnaire. Utilisez la [fonction de déclenchement](https://docs.stripe.com/cli/trigger) pour exécuter les commandes suivantes, qui simulent les événements respectifs dans votre compte à des fins de test. ```sh $ stripe trigger v1.billing.meter.error_report_triggered --api-key $ stripe trigger v1.billing.meter.no_meter_found --api-key ``` 1. Si vous traitez des événements avec un endpoint de webhook, [vérifiez les signatures de webhook](https://docs.stripe.com/webhooks.md#verify-official-libraries) pour sécuriser votre endpoint et vous assurer que toutes les requêtes proviennent de Stripe. 1. Corrigez les événements non valides et enregistrez-les dans un nouveau fichier. Ensuite, chargez le fichier dans votre compartiment Amazon S3 pour qu’il soit traité.