コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン

Amazon S3 を使用した請求の使用状況の記録

Amazon S3 ストレージバケットを使用して使用量イベントを一括で記録する方法をご紹介します。

ページをコピー

各請求期間で顧客に正しい金額を請求するには、使用量を Stripe に記録する必要があります。使用量を記録するには、Amazon S3 ストレージバケットから Stripe にメーター使用量イベントを送信します。Stripe は使用量データを解析・検証し、メーターイベントに変換します。

イベントが正常にアップロードされると、サブスクリプションの請求書に表示されます。

はじめに

次のものがあることを確認してください。

メーター使用量イベントのアップロード

メーター使用量イベントは、CSV、JSON、または JSON Lines ファイルでアップロードできます。

異なるファイル形式のサポートが必要な場合

異なる構造やカスタムの形式のファイルのアップロードをご希望の場合は、お問い合わせください。

ファイル形式とフィールド

ファイルがサンプルファイル形式に従っていることを確認します。

CSV ファイル形式の例

CSV ファイル形式

Meter Event (メーターイベント) のスキーマに従って、ファイルに次のフィールドを含めます。

フィールド説明
identifierイベントの一意の識別子。指定しない場合は、Stripe が一意の識別子を生成します。グローバルな一意の識別子を使用することをお勧めします。
timestampイベントが発生した時刻 (Unix エポックからの秒数)。
event_nameメーターイベントの名前。

payload_columns

顧客および使用量の数値のキー名を含む列のセット:

  • payload_stripe_customer_id: イベントの作成対象となる顧客 ID。
  • payload_value: メーターイベントの使用量の数値。デフォルトでは、列名が payload_value になっています。メーターイベントの作成時に別のフィールド名を指定した場合は、キー値と一致するように列名を更新する必要があります。たとえば、value_settings でトークンを指定する場合は、列名を payload_tokens に更新します。

Amazon S3 でファイルを準備する

S3 バケット内の適切な形式のデータを使用して、接続設定を検証できます。構成プロセスでは使用可能なファイルが表示され、接続の構成時に最初の同期が実行されます。

  1. Amazon S3 コンソールに移動します。

  2. ファイルは、インポート設定に従って整理された指定の S3 バケットに保存してください。必要に応じて、AWS ガイドラインに従って S3 バケットを作成します。

    正常に取得するには、ファイル名がS3 オブジェクトの命名規則に準拠し、ファイルが最大 1 GB である必要があります。

  3. バケット名とリージョンは、今後のステップで必要になるため、覚えておいてください。

  4. AWS 管理コンソールを開いたままにして、後で IAM ロールを設定します。

ファイルをインポートするように Amazon S3 コネクターを設定する

まず、Stripe ダッシュボードを使用して Amazon S3 コネクターを追加します。

  1. Stripe ダッシュボードのデータ管理 > コネクタータブで、コネクターの追加をクリックします。
  2. コネクターの選択ダイアログで Amazon S3 を選択します。
  3. 要件ダイアログでコネクター名に一意の名前を入力し、次へをクリックします。
  4. 権限ダイアログの手順を完了します。

次に、Amazon S3 コネクターに適切なアクセス許可を設定します。

  1. AWS 管理コンソールから IAM コンソールに移動します。
  2. 以下の手順でカスタムの信頼ポリシーを作成します。
    • ナビゲーションウィンドウで、ポリシー > ポリシーの作成をクリックします。
    • JSON を選択し、Stripe ダッシュボードに表示されるコードブロックをコピー & ペーストして、既存のポリシーテキストと置き換えます。
    • ポリシーエディタコードブロックの Resource セクションで、USER_TARGET_BUCKET を目的のバケット名に置き換えます。
    • 次へをクリックします。
    • ポリシーの詳細でポリシー名を追加します。必要に応じて、タグを追加します。
    • ポリシーの作成をクリックします。
  3. 以下の手順でロールを作成します。
    • ナビゲーションウィンドウで、ロール > ロールの作成をクリックします。
    • カスタムの信頼ポリシーを選択し、Stripe ダッシュボードに表示されるコードブロックをコピーして貼り付けます。
    • 次へをクリックします。
    • 新しく作成したアクセス許可ポリシーを見つけて選択し、有効にした後、次へをクリックします。
    • 指定されたロール名をコピーして貼り付け、ロールの作成をクリックしてロール名を作成します。

次に、Stripe と Amazon S3 バケット間の接続を確立します。

  1. AWS 管理コンソールで以下の操作を実行します。
    • AWS アカウント ID を入力します。
    • バケット名とリージョンを入力します。
    • フォルダを使用して Amazon S3 バケット内のファイルを整理する場合は、上記のバケット内のフォルダを指定します。バケット全体ではなく、指定されたフォルダからのみデータを取得することが可能です。
  2. 新しいコネクターを設定すると、ファイルのプレビューで認証情報が Stripe と所定の Amazon S3 バケットおよびフォルダに接続されていることが検証されます。Stripe は、過去 90 日間に変更されたすべてのデータを取得します。これは、LastModified の日付が最後の同期より後のオブジェクトに対して 5 分ごとに行われます。
  3. 接続される Amazon S3 バケットで利用可能なファイルをプレビュー:
    • ファイル名は 255 文字未満で、.csv、.json、.jsonl などの適切な拡張子を含める必要があります。
    • 初回インポートと定期インポートには、所定のファイル形式が用意されます。
      • JSON ファイルには Billing Meter Event Transaction Template - JSON が含まれています。
      • JSON Lines ファイルには Billing Meter Event Transaction Template - JSONLINE が含まれています。
      • CSV ファイルには Billing Meter Event Transaction Template - CSV が含まれています。
  4. アクティブなデータ接続を作成し、データのインポートを開始するには、完了をクリックします。

Amazon S3 コネクターにファイルをアップロードすると、使用量イベントが 5 分以内に更新されます。バケットに未処理のファイルが多く含まれている場合は、この処理に時間がかかることがあります。

処理されたファイルのステータスや詳細は、Stripe ダッシュボードのインポート設定タブで確認できます。

レート制限

任意の数のファイルとレコードを Amazon S3 バケットにアップロードできます。10 秒ごと、または現在のファイルが 100 万レコードに達したときのいずれか早い方でファイルをアップロードします。アップロード後、新しいファイルにイベントを追加できます。

以下のような空ファイルは作成しないようにしてください。

  • ヘッダー行のみを含む CSV ファイル
  • のみを含む JSON ファイル
  • {}(空の中括弧) のみを含む JSON Lines ファイル

Amazon S3 は 0 バイト以外のファイルに対応していますが、オブジェクトとファイルの数が増えるため、ファイルのポーリングに遅延が生じる可能性があります。

Amazon S3 は、最大 50 個のファイルまたは最大 10 GB のデータをポーリングし、アップロードされたデータのイベントを1 万件 / 毎秒の割合で処理します。大きなファイルや大量のファイルをアップロードする場合、Stripe はデータをポーリングして処理し、このスループットレートを維持します。

たとえば、10 万件のレコードを含む 100 個のファイルを毎日アップロードする場合、データセット全体 (1,000 万件のイベント) を処理するのに約 17 分かかります。

エラーの報告と処理

Stripe は、Amazon S3 バケットにアップロードしたファイルをポーリングし、これらのファイルを非同期で処理します。処理中にエラーが検出された場合、Stripe はイベントで通知します。

フォーマットエラー

無効なファイルまたはレコードフォーマットによるエラーは、アップロードされたファイルにフォーマットまたはデータに関する問題がある場合に発生します。

これらのイベントは、Webhook エンドポイントを使用してサブスクライブできます。イベントの種類に基づいて、これらのエラーを処理する独自のロジックを実装できます。

イベント説明ペイロードタイプ
data_management.import_set.failedファイル全体の処理が失敗した場合に、Stripeは data_management.import_set.failed イベントを作成します。たとえば、event_name などの必須列を省略した場合がこれに該当します。イベントの failed_reason パ ラメーターで失敗の理由を確認し、再アップロードする前に修正できます。Snapshot

data_management.import_set.succeeded

部分処理されたファイルで個々のレコードが失敗した場合に、Stripe はdata_management.import_set.succeeded イベントを作成します。たとえば、stripe_customer_id や event_name などの必須フィールドの値を省略した場合がこれに該当します。

失敗したレコードの詳細は、イベントの status パラメーターで確認できます。succeeded_with_errors ステータスは、無効なフォーマットが原因で少なくとも 1 つのレコードが失敗したことを示します。result.errors には、失敗したレコードの数と、失敗したレコードを含むファイルの file_id が表示されます。

Files API を使用して、失敗したレコードの完全なリストと詳細なエラーの説明をダウンロードします。

Snapshot

データの問題

正しいフォーマットのファイルは、event_name や stripe_customer_id の値が正しくないなど、ファイル内のデータが無効であるために処理に失敗することがあります。

これらのエラーの詳細を得るために、Webhook エンドポイントを使用して今後のイベントをサブスクライブできます。

イベント説明ペイロードタイプ
v1.billing.meter.error_report_triggeredこのイベントは、従量に無効な使用量イベントが含まれているときに発生します。thin
v1.billing.meter.no_meter_foundこのイベントは、使用量イベントが不足していたり、無効な従量 ID が含まれているときに発生します。thin

警告

thin イベントに登録するイベントの送信先を作成するには、開発者向け設定でワークベンチを有効にします。

サンプルのペイロード

以下は、v1.billing.meter.error_report_triggered イベントのペイロードの例です。

{
  "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": [
        {

エラーコード

reason.error_types.code はエラーを引き起こしたエラーカテゴリーを示します。発生する可能性のあるエラーコードは次のとおりです。

  • 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 (v1.billing.meter.no_meter_found イベントタイプでのみサポートされています)

イベントのリッスン

イベント送信先を設定することで、イベントをリッスンできます。

  1. Workbench のイベントの送信先タブで、新しい送信先を作成するをクリックします。あるいは、このテンプレートを使用して、以下の 2 つのイベントタイプが事前に選択された状態で、Workbench で新しい送信先を設定します。

  2. Show Advanced Settings (詳細設定を表示) をクリックして、Thin ペイロードスタイルを選択します。

  3. イベントのリストから v1.billing.meter.error_report_triggered と v1.billing.meter.no_meter_found を選択します。

  4. イベントを処理するハンドラを作成します。

    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')

  5. ハンドラをテストするには、Stripe CLI でローカルリスナーを構成し、ハンドラを本番環境にデプロイする前にテスト用にローカルマシンにイベントを送信します。--forward-thin-to フラグを使用して、thin イベントの転送先の URL を指定し、--thin-events フラグを使用して、アプリケーションに転送する thin イベントを指定します。アスタリスク (*) を使用することですべての thin イベントを転送したり、thin イベントのサブセットを転送したりすることも可能です。

    $ stripe listen --forward-thin-to localhost:4242/webhooks --thin-events "*"

  6. ハンドラに対してテストイベントをトリガーします。トリガー関数を使用して次のコマンドを実行し、テストアカウントのイベントを個別にシミュレーションします。

    $ 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>

  7. Webhook エンドポイントでイベントを処理している場合は、Webhook の署名を確認してエンドポイントを安全に保護し、すべてのリクエストが Stripe から送信されたものであることを検証します。

  8. 無効なイベントを修正し、新しいファイルに保存します。次に、ファイルを Amazon S3 バケットにアップロードし、処理を行います。

このページはお役に立ちましたか。
はいいいえ
お困りのことがございましたら 、サポートにお問い合わせください。
早期アクセスプログラムにご参加ください。
変更ログをご覧ください。
ご不明な点がございましたら、お問い合わせください。
LLM ですか？llms.txt を読んでください。
Powered by Markdoc