Amazon S3 インポート

AmplitudeのAmazon S3インポートを使用すると、イベントデータをインポートおよび変更したり、ユーザーまたはグループのプロパティをAWS S3バケットからAmplitudeプロジェクトに同期したりできます。 Amazon S3 インポートを使用して、大量の既存データをバックフィルしたり、既存のデータパイプラインを Amplitude に接続したり、高いスループットが必要でレイテンシーの影響を受けにくい場合に大量のデータを取り込むことができます。

セットアップ時に、Amplitudeがイベントをどのように計測するかを制御するための変換ルールを設定します。 Amazon S3 インポートを設定して有効化すると、Amplitudeの取り込みサービスは継続的にS3バケット内のデータファイルを検出し、イベントを変換して取り込みます。

前提条件

開始する前に、次の前提条件を満たしていることを確認してください。

• データを受け取るためのAmplitudeプロジェクトが作成されていること。そうでない場合は、新しいプロジェクトを作成してください。
  • あなたはAmplitudeプロジェクトの管理者またはマネージャーです。
• S3バケットにはAmplitudeが取り込むためのデータファイルが用意されています。 これらは、コンバータファイルで説明したマッピングに準拠している必要があります。
• インポートするデータには、各行に対して一意かつ不変insert_idである必要があります。これにより、予期しない問題が発生した場合にデータの重複を防止できます。 詳細については、「重複排除（insert_idを使用）」を参照してください。
• ミラー同期にはユーザーIDが必要です。 行にユーザーIDが含まれていない場合、Amplitudeはイベントをドロップします。

ファイル要件

Amplitudeに送信したいファイルは、いくつかの基本的な要件に従っている必要があります：

• ファイルにはイベントが含まれています。イベントは 1 行につき 1 つです。
• イベントの日付順にファイルをアップロードします。
• ファイル名は一意です。
• ファイルサイズは1MBより大きく5GB未満である必要があります。 大規模なイベントを処理するお客様の場合、Amplitudeは最適なパフォーマンスを得るために500MB近くのファイルサイズを推奨しています。
• ファイルは、圧縮または非圧縮の JSON、CSV、または Parquet ファイルです。
• ミューテーションをサポートするミラー同期の場合、次の制約が適用されます。
  • イベントへの変更にはユーザー ID が必要です。 行にユーザーIDが含まれていない場合、Amplitudeはイベントをドロップします。 大量の匿名イベントが発生している場合、Amplitudeはこのモードの使用を推奨しません。
  • Amplitude では、INSERT、UPDATEおよび DELETE のミューテーションタイプが許可されています。 ミューテーションタイプを指定しない場合、プロセスはデフォルトで UPDATE になります。

重複除外機能を使用: insert_id

インジェクション同期の場合のみ、Amplitudeは一意の識別子を使用し、insert_id受信イベントと照合して重複を防止します。同じプロジェクト内で、Amplitudeが過去7日以内に受信した別のイベントと、同じdevice_idおよびinsert_idの値を持つイベントを受信した場合、Amplitudeは最新のイベントを削除します。

Amplitudeでは、重複を防ぐためにイベントごとにカスタムinsert_idを設定することをお勧めします。 カスタム insert_id を設定するには、ランダムな英数字文字列など、固有の値を保持するフィールドをデータセット内に作成します。 ガイド付きコンバータ設定で、フィールドをinsert_idという名前の追加プロパティとしてマップします。

AmplitudeにS3バケットへのアクセス権を付与する

以下の手順に従って、AmplitudeにAWS S3バケットへの読み取りアクセス権を付与してください。

1. 新しい IAM ロールを作成します。例: AmplitudeReadRole。

2. ロールの**「信頼関係」**に移動し、Amplitudeのアカウントを信頼関係ポリシーに追加して、次の例を使用してAmplitudeがロールを引き継ぐことを許可します。

   • external_id: Amplitudeが役割を引き受けるときに使用される固有の識別子です。 サードパーティ製ツールの助けを借りてそれを生成できます。外部 ID の例は vzup2dfp-5gj9-8gxh-5294-sd9wsncks7dc です。

   • Amplitude米国地域の信頼ポリシー：

   plaintext

   コピー

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
         "AWS": ["arn:aws:iam::358203115967:role/k8s_prod_cargo",
                 "arn:aws:iam::358203115967:role/k8s_prod_falcon",
                 "arn:aws:iam::358203115967:role/vacuum_iam_role" ]
         },
         "Action": "sts:AssumeRole",
         "Condition": {
         "StringEquals": {
         "sts:ExternalId": "<external_id>"
           }
         }
       }
     ]
   }
   

   • Amplitude EU地域の信頼ポリシー

   plaintext

   コピー

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
         "AWS": ["arn:aws:iam::202493300829:role/k8s_prod-eu_cargo",
                 "arn:aws:iam::202493300829:role/k8s_prod-eu_falcon",
                 "arn:aws:iam::202493300829:role/vacuum_iam_role" ]
       },
         "Action": "sts:AssumeRole",
         "Condition": {
         "StringEquals": {
         "sts:ExternalId": "<external_id>"
           }
         }
       }
     ]
   }
   

3. 新しいIAMポリシーを作成します (例: AmplitudeS3ReadOnlyAccess)。以下のサンプルコード全体を使用してくださいが、強調表示されているテキストの <> を必ず更新してください。

   • <bucket_name>: データのソースとなる S3 バケット名です。
   • <プレフィックス>: インポートしたいファイルのオプションのプレフィックス (例: filePrefix)。 フォルダの場合、プレフィックスが / で終わっていることを確認してください（例：folder/）。 ルートフォルダの場合、プレフィックスは空のままにしてください。

   例 1：プレフィックスなしの IAM ポリシー：

   json

   コピー

   {
     "Version":"2012-10-17",
     "Statement":[
       {
         "Sid":"AllowListingOfDataFolder",
         "Action":[
           "s3:ListBucket"
         ],
         "Effect":"Allow",
         "Resource":[
           "arn:aws:s3:::<bucket_name>"
         ],
         "Condition":{
           "StringLike":{
             "s3:prefix":[
               "*"
             ]
           }
         }
       },
       {
         "Sid":"AllowAllS3ReadActionsInDataFolder",
         "Effect":"Allow",
         "Action":[
           "s3:GetObject",
           "s3:ListBucket"
         ],
         "Resource":[
           "arn:aws:s3:::<bucket_name>/*"
         ]
       },
       {
         "Sid":"AllowUpdateS3EventNotification",
         "Effect":"Allow",
         "Action":[
           "s3:PutBucketNotification",
           "s3:GetBucketNotification"
         ],
         "Resource":[
           "arn:aws:s3:::<bucket_name>"
         ]
       }
     ]
   }
   

   例 2：プレフィックス付きの IAM ポリシー。フォルダの場合、プレフィックスが folder/ で終わっていることを確認してください。たとえば/:

   json

   コピー

   {
     "Version":"2012-10-17",
     "Statement":[
       {
         "Sid":"AllowListingOfDataFolder",
         "Action":[
           "s3:ListBucket"
         ],
         "Effect":"Allow",
         "Resource":[
           "arn:aws:s3:::<bucket_name>"
         ],
         "Condition":{
           "StringLike":{
             "s3:prefix":[
               "<prefix>*"
             ]
           }
         }
       },
       {
         "Sid":"AllowAllS3ReadActionsInDataFolder",
         "Effect":"Allow",
         "Action":[
           "s3:GetObject",
           "s3:ListBucket"
         ],
         "Resource":[
           "arn:aws:s3:::<bucket_name>/<prefix>*"
         ]
       },
       {
         "Sid":"AllowUpdateS3EventNotification",
         "Effect":"Allow",
         "Action":[
           "s3:PutBucketNotification",
           "s3:GetBucketNotification"
         ],
         "Resource":[
           "arn:aws:s3:::<bucket_name>"
         ]
       }
     ]
   }
   

4. ロールの権限に移動します。 ステップ 3 で作成したポリシーをロールに適用します。

連携を設定する

以下の手順を実行して、Amazon S3 ソースを設定します。

1. 接続の設定と検証
2. ファイルを選択
3. コンバータ設定を作成する
4. ソースを有効にする

接続の設定と検証

Amplitudeで、S3インポートソースを作成します。

Amplitudeでデータソースを作成するには、S3バケットに関する情報を収集します。

• IAMロールARN：AmplitudeがS3バケットにアクセスするために使用するIAMロールです。これは、「AmplitudeにS3バケットへのアクセス権を付与する」で作成されたロールです。
• IAMロール外部ID：AmplitudeがS3バケットにアクセスするために使用するIAMロールの外部ID。これは、「S3バケットへのアクセスをAmplitudeに許可する」で作成された外部IDです。
• S3バケット名: データを含むS3バケットの名前です。
• S3バケットプレフィックス: データが格納されているS3フォルダーです。
• S3バケットリージョン: S3バケットが存在するリージョン。

バケットの詳細がわかれば、Amazon S3インポートソースを作成します。

1. Amplitudeデータで、[カタログ] をクリックし、[ソース] タブを選択します。

2. [Warehouse Sources] セクションで、[Amazon S3] をクリックします。

3. Amazon S3 を選択し、次へをクリックします。 このソースがリストに表示されていない場合は、Amplitudeソリューションアーキテクトにお問い合わせください。

4. [Set up S3 Bucket] ページの [Configure S3 location] セクションに入力してください。

   • バケット名：ファイルを保存するために作成したバケットの名前。たとえば、com-amplitude-vacuum-<customername>.これによりAmplitudeはファイルをどこで探すべきかを知ることができます。
   • プレフィックス: インポートするファイルのプレフィックスです。 フォルダの場合、プレフィックスは「/」で終わる必要があります。たとえば、dev/event-data/です。 ルートフォルダについては、空のままにしてください。
   • AWSロールARN必須です。
   • AWS 外部 ID。 必須です。
   • AWS リージョン。 必須です。

5. オプション：S3 イベント通知を有効にします。

• イベント通知を使用すると、Amplitudeの取り込みサービスがS3バケット内のデータをより迅速に検出できます。 バケットをスキャンするのと異なり、インジェクションサービスは、S3 が発行する通知に基づいて新しいデータを検出します。 この機能により、新しいデータの検索にかかる時間が短縮されます。
• ほぼリアルタイムにインポートしたい場合は、この機能を使用してください。 Amplitudeは通知を有効にしている場合、30秒以内に新しいデータを検出します。
• 通知を有効にする前に、次の点に注意してください：
  • 使用するIAMロールには、バケットイベント通知を設定する権限が必要です。
  • バケットに既存のイベント通知を保持することはできません。 これは Amazon が S3 バケットに課す制限です。
  • 通知は遡及的に適用されません。

6. すべての値を入力したら、[Test Credentials] をクリックします。 ソースを作成した後は、UIからこれらの値を編集することはできません。そのため、**[次へ]**をクリックする前に、すべての情報が正しいことを確認してください。
7. データソース名と説明（オプション）を入力し、ソースを保存します。 これらの詳細は設定から編集できます。

次に、コンバータ設定を作成します。

Amplitudeはバケットを継続的にスキャンし、ファイルが追加されるたびに新しいファイルを検出します。

ファイルを選択

1. ファイルの種類、圧縮タイプ、および正規表現パターンを指定します。 コンバータ ファイルのボイラープレートは、この手順で行った選択に基づいて事前に入力されます。 **「プレビューを表示」**をクリックして設定をテストします。
2. [次へ] をクリックします。

コンバータ設定を作成する

コンバータの設定により、S3 Vacuum は次の情報を得ることができます。

• 有効なデータファイルがどのようなものかをAmplitudeに伝えるパターンです。 例：\w+\_\d{4}-\d{2}-\d{2}.json.gz。
• ファイルが圧縮されているかどうか、圧縮されている場合はどのように圧縮されているか。
• ファイルのフォーマットです。 たとえば、CSV(特定の区切り文字付き)やJSONオブジェクトの行などです。
• ファイルから各行をAmplitudeイベントまたはミューテーションにマップする方法。

データタイプを選択してください

イベント、ユーザープロパティ、およびグループプロパティデータをインポートできます。

インポート戦略を選択する

選択したデータタイプに応じて、以下の戦略から選択してください。

どのデータタイプがどのインポート戦略と互換性があるかを理解するには、次の表を参照してください。

イベント用にサポートされているフィールドの一覧は、HTTP V2 API のドキュメントを参照してください。ユーザープロパティ用にサポートされているフィールドの一覧は、Identify API のドキュメントを参照してください。 これらのリストにない列をいずれかevent_propertiesに追加します。そうしないとuser_properties、Amplitudeはそれらを無視します。

インポートしたいすべてのフィールドを追加したら、この設定のサンプルを [データプレビュー] セクションで表示してください。 データプレビューは、フィールドやプロパティを追加または削除すると自動的に更新されます。 データプレビューでは、ソースからのサンプルレコードと、Amplitudeがそのデータをどのようにインポートするかを確認できます。 これにより、必要なすべてのデータポイントを確実に取得できます。 10 個のサンプルソースレコードとそれに対応する Amplitude イベントを確認できます。

手動によるコンバータ作成

コンバータファイルは、取り込まれたファイルをどのように処理するかをAmplitudeに伝えます。 これを2つのステップで作成します。まず、ファイルの圧縮タイプ、ファイル名、およびエスケープ文字を設定します。

次に、JSON を使用してコンバータが従うルールを記述します。

コンバータ言語は、JSON 要素に与えられた値を抽出することを記述しています。 これは、SOURCE_DESCRIPTION を使用して指定します。この値には次のものが含まれます。

• BASIC_PATH。
• リスト演算子。
• JSON_OBJECT。

ソースを有効にする

ソースを有効にするには、コンバータのテストに成功する必要があります。 変更を保存して後で再開することもできますが、ソースを有効にするオプションは、コンバータがテストを正常に完了した後にのみ使用できます。

コンバータを設定する際は、[保存して有効にする] をクリックしてソースを有効にします。

トラブルシューティング

• 正しいAmplitudeアカウントへのアクセス権を付与していることを確認してください。 お客様の組織と同じデータセンターを使用してください。 詳細については、「AmplitudeにS3バケットへのアクセス権を付与する」を参照してください。
• Amplitudeはバケット名にドット文字をサポートしていません。バケット名は必ず小文字、数字、ダッシュで構成してください。
• 所有している既存のバケットを使用できます。互換性を確保するために、Amplitudeウィザードの出力に基づいてバケットのポリシーを更新してください。