データのバックフィル

データのバックフィルは過去のイベントをプロジェクトにロードするため、過去のユーザーアクティビティは現在のデータと一緒に表示されます。 バッチイベントアップロードAPIを使用して履歴データをAmplitudeにインポートできます。

考慮事項

データをバックフィリングする前に、これらの考慮事項を確認してください。

• 過去のデータをライブプロダクションプロジェクトにバックフィルするのではなく、別のAmplitudeプロジェクトに保存することを検討してください。 履歴データを別々に保管することでアップロードが容易になり、ライブAmplitudeデータをクリーンに保ち、現在と将来のデータに集中できます。 通常、履歴データを頻繁に確認する必要はありませんが、それでも利用できるようにしておく必要があります。過去のユーザープロパティ値は、バックフィル時に現在の有効値を上書きします。 Amplitudeは古いプロパティ値を新しいライブイベントに同期します。 ユーザープロパティの同期をスキップするには、イベントペイロードに以下を追加してください。"$skip_user_properties_sync": true
• 過去のデータと現在のデータをリンクするには、過去のデータとライブデータを同じプロジェクトで組み合わせます。各データセットからユーザーを接続するには、各セットで一致するAmplitudeユーザーIDが必要です。
• 新しいユーザー数は変更される可能性があります。 Amplitudeは、特定のユーザーについて認識した最も古いイベントのタイムスタンプに基づいて新しいユーザーを定義します。 Amplitudeがユーザーを2021年6月1日に新規ユーザーとして記録し、ユーザーのデータを2021年2月1日からバックフィルした場合、Amplitudeはユーザーを2021年2月1日に新規ユーザーとして定義します。
• バックフィルはアプリデータを危険にさらす可能性があります。 現在のユーザーIDとバックフィルされたユーザーIDの間に不一致が存在する場合、Amplitudeは2つの異なるユーザーIDを2つの異なるユーザーとして解釈します。 その結果、Amplitudeはユーザーを二重にカウントしています。 Amplitudeは記録後にデータを削除できないため、データ問題を防ぐために新しいプロジェクトを作成する必要がある場合があります。
• Amplitudeは、デバイスIDとユーザーIDフィールドを使用してAmplitude IDを計算します。 詳細については、「ユニークユーザーの追跡」を参照してください。
• バックフィル内のイベントは、月間のイベント数にカウントされます。

制限事項

データをバックフィルする際は、これらの制限に留意してください。

• 1日あたりの制限：Amplitudeをイベントスパムから保護するため、各プロジェクトにはデバイスIDごと（およびユーザーIDごと）に50万イベントの1日あたりの取り込み制限が適用されます。この制限値は、1 時間間隔の 24 時間のローリング ウィンドウを使用しています。 ユーザーまたはデバイスは、過去24時間以内に任意の時点で最大50万件のイベントを送信できます。この制限に達した場合、応答に exceeded_daily_quota_users や exceeded_daily_quota_devices が表示されます。詳細については、バッチ イベント アップロードを参照してください。
• バッチ制限: 1秒あたり100バッチ、1秒あたり1000イベントのアップロード制限が適用されます。イベントを一括してアップロードすることもできますが、Amplitudeは1バッチあたり10件以下のイベントを送信することを推奨しています。 単一のデバイス ID に対して毎秒 10 件を超えるイベントを送信する場合、Amplitude はアップロードを抑制します。 スロットリングの詳細については、「バッチ イベント アップロード」を参照してください。 取り込みワーカーに過負荷をかけることを避けるために、AmplitudeではバックフィルイベントのアップロードをデバイスIDごとに1秒間に300イベントに制限することを推奨しています。履歴データを繰り返し処理し、データをできるだけ早く並行して送信する場合、バックフィルは 1 秒あたり 300 イベントを超えることがあります。

バックフィルのベストプラクティス

• バッチ API のドキュメントを確認してください。 エクスポート API を使用して履歴データをエクスポートし、そのデータをバックフィルに使用したい場合は、エクスポートされたフィールドの形式がインポートに必要なフィールドと同じではないことに注意してください。 たとえば、Export API は $insert_id を使用しますが、HTTP API および Batch API は $ を含まない insert_id という形式を使用します。
• 送信するフィールドを決定し、履歴データをAmplitudeフィールドにマッピングします。 Amplitudeは、 insert_id フィールドを使用してイベントを重複排除することを強く推奨しています。
• インポートを取り消す方法はないため、Amplitudeでテストプロジェクトを作成して、バックフィルからサンプルデータを送信してください。 本番プロジェクトへの最終的なアップロード前に、Amplitudeテストプロジェクトで数日分のデータを使用して複数のテストを実行してください。

Amplitudeは大量のデータをバックフィルするためにこのアプローチを推奨しています：

1. イベントのセットを重複しないサブセットに分割します (たとえば、device_id によって分割します)。
2. イベントのセットごとに1人のワーカーに次の手順を実行してもらいます。
   1. システムから多くのイベントを読み取ります。
   2. これらのイベントを device_id または user_id に基づくリクエストに分割します。
   3. リクエストを同時または並行してAmplitudeに送信します。

さらに最適化するには、タイムアウトが長いアグレッシブなリトライロジックを追加します。 200 の応答を受信するまで再試行を続けます。 insert_id を送信した場合、Amplitudeは、7日以内に送信された同じ insert_id を持つデータを重複排除します。

ユーザープロパティの同期をスキップする

Amplitudeがイベントをキャプチャするとき、そこには各ユーザープロパティの現在の値が含まれますが、これは時間の経過とともに変化する可能性があります。 Amplitudeはユーザープロパティを含むイベントを受信すると、既存のユーザープロパティを更新し、新しいユーザープロパティを追加します。 この動作を変更するには、イベント ペイロードに "$skip_user_properties_sync": true を追加します。

"$skip_user_properties_sync": trueを含めると、Amplitudeはユーザープロパティのテーブルを完全に無視します。このイベントには、イベントとともに送信されたユーザープロパティのみが含まれます。ユーザープロパティテーブルは更新されません。また、既存のユーザープロパティも表示されません。

{
    "api_key": "API_KEY",
        "events": [
    {
        "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002",
        "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636",
        "device_id": "",
        "event_type": "Button Clicked",
        "user_properties":{
            "subscriptionStatus":"active"
        }
    }
    ]
}

        "events": [
    {
        "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002",
        "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636",
        "device_id": "",
        "event_type": "Button Clicked",
        "user_properties":{
            "city":"New York",
            "subscriptionStatus":"active"
        }
    }
    ]

        "events": [
    {
        "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002",
        "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636",
        "device_id": "",
        "event_type": "Button Clicked",
        "$skip_user_properties_sync": true,
        "user_properties":{
            "subscriptionStatus":"active"
        }
    }
    ]

{
    "api_key": "API_KEY",
        "events": [
    {
        "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002",
        "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636",
        "device_id": "",
        "event_type": "Button Clicked",
        "$skip_user_properties_sync": true,
        "user_properties":{
            "city":"San Francisco"
        }
    }
    ]
}

        "events": [
    {
        "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002",
        "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636",
        "device_id": "",
        "event_type": "Button Clicked",
        "user_properties":{
            "city":"San Francisco"
        }
    }
    ]

タイミング

タイムスタンプが30日以上前のデータを送信した場合、Amplitudeの一部に表示されるまでに最大48時間かかることがあります。[ユーザーアクティビティ] タブを使用して送信中のイベントを確認できます。このタブはイベントの時間に関係なくリアルタイムで更新されるためです。

リソース

• データインポート用のスクリプト例： https://gist.github.com/djih/2a7e7fb2c1d45c8277f7aef64b682ed6
• データ例： https://d24n15hnbwhuhn.cloudfront.net/sample_data.zip

データ取り込みシステム

Amplitudeの取り込みシステムでは、各ユーザーの現在のユーザープロパティが追跡され、ユーザーの受信イベントと同期されます。

Amplitudeにデータを送信する場合、イベントデータを送信するか、identifyコールを送信してユーザーのユーザープロパティを更新します。これらのidentify呼び出しは、ユーザーの現在のユーザープロパティ値を更新し、identify呼び出し後に受信したイベントに関連付けられたユーザープロパティに影響を与えます。

Amplitudeはユーザーのすべてのイベントを同じインジェストワーカーを使用して処理するため、Amplitudeはイベントを受信した順序で処理することを保証します。Datamonsterのすべてのイベントは、単一のインジェスチョンワーカー上で順番にキューイングされます。2つの別々のワーカーがこれらのイベントを並行して処理した場合、順序付けを保証することは困難になります。たとえば、あるワーカーが別のワーカーよりも高速に処理を実行することがあります。

単一のインジェスチョンワーカーがユーザーのイベントを処理するため、ユーザーが短期間に異常に多くのイベントを送信すると、そのワーカーに過負荷がかかる可能性があります。取り込みワーカーに過負荷をかけることを避けるために、AmplitudeではイベントのアップロードをデバイスIDごとに1秒あたり300イベントに制限することを推奨しています。 履歴データを繰り返し処理し、可能な限り高速に並行してデータを送信する場合、バックフィルは1秒あたり300イベントを超えることがあります。Amplitudeは各デバイスIDのイベントレートを追跡し、デバイスIDが送信するイベントの数が多すぎる場合、429のスロットリングHTTPレスポンスコードでイベントを拒否します。 イベントのアップロードに対する応答として429を受信した場合、プロセスは数秒間スリープし、その後成功するまでアップロードの再試行を継続する必要があります。このアプローチにより、バックフィルプロセスでイベントが失われることがありません。 429レスポンスコードの後に再試行しなかった場合、Amplitudeはそのイベントバッチを取り込みません。

既存ユーザーのバックフィル

既存のユーザーがいる場合は、それらをバックフィルして、ユーザーがいつ新規ユーザーになったかを正確にマークします。Amplitudeは、最も古いイベントのタイムスタンプに基づいてユーザーを新規ユーザーにマークします。

既存のユーザーをバックフィルするには、バッチAPIを使用します。プレースホルダーイベントまたは登録イベントを送信します。イベントのタイムスタンプは、ユーザーが最初に作成された実際の時刻です。 たとえば、ユーザーが2022年8月1日にサインアップした場合、送信するイベントのタイムスタンプは2022年8月1日である必要があります。