S3プレイヤーデータエクスポート
Player Data Exportは、ゲームのプレイヤーレコードを自社が所有するAmazon S3バケットに書き込みます。データウェアハウスやレポートパイプラインでこれらのレコードを利用し、FirstLookのプレイヤー情報を自社のゲームやビジネスデータと結び付けることができます。
各エクスポート実行は、現在のプレイヤーレコードを**JSON Lines(JSONL)**ファイルに書き込みます。1行につき1人のプレイヤーが含まれます。レコードは連番のファイルに分割され、最後に完了マーカーが書き込まれるため、パイプラインで実行全体の準備が整ったかどうかを判断できます。
バケットのイベントをFirstLookに取り込むには、S3 Events を参照してください。アナリティクスチャートの元データをダウンロードするには、アナリティクスのエクスポート を参照してください。
S3バケットのセットアップ
Section titled “S3バケットのセットアップ”FirstLookがエクスポートを書き込むために引き受けられるIAMロールを、自社のAWSアカウントに作成します。セットアップは S3 Events と同じクロスアカウントロールの方式ですが、ファイルの読み取りではなく書き込みの権限を付与します。
以下の例では、プレフィックス firstlook/exports を使用します。別のプレフィックスも使用できますが、IAMポリシーとダッシュボードの設定を一致させてください。複数のゲームでバケットを共有する場合は、ゲームごとに別のプレフィックスを使用してください。
1. IAMポリシーの作成
Section titled “1. IAMポリシーの作成”以下の権限を持つポリシーを作成します。YOUR_BUCKET_NAME を実際のバケット名に置き換え、別のプレフィックスを選んだ場合は firstlook/exports も変更してください。
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:PutObject", "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/firstlook/exports/*" }, { "Effect": "Allow", "Action": "s3:DeleteObject", "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/firstlook/exports/_firstlook_probe_*" } ]}s3:PutObject により、FirstLookはエクスポートファイルと完了マーカーをアップロードできます。対象範囲を絞った s3:DeleteObject 権限により、設定保存時に書き込まれる一時ファイルを削除できます。エクスポーターが既存のオブジェクトを読み取ったり、一覧表示したりする必要はありません。
Prefixを空欄にする場合は、書き込み用リソースを arn:aws:s3:::YOUR_BUCKET_NAME/* に、プローブ削除用リソースを arn:aws:s3:::YOUR_BUCKET_NAME/_firstlook_probe_* に変更してください。
バケットでSSE-KMS暗号化を使用している場合は、ロールのIAMポリシーとキーポリシーの両方で、KMSキーへの必要なアクセス権も付与してください。AWSの PutObjectの権限 を参照してください。
2. 信頼ポリシーを設定したIAMロールの作成
Section titled “2. 信頼ポリシーを設定したIAMロールの作成”FirstLookPlayerExport などのIAMロールを作成し、上記のポリシーをアタッチします。External ID条件を使用してFirstLookのAWSアカウントがロールを引き受けられるように、信頼ポリシーを設定します。
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::409257555035:root" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "YOUR_EXPORT_EXTERNAL_ID" } } } ]}External IDは、FirstLookがロールを引き受ける際にこのエクスポート先を識別するための値です。混乱した代理問題 の防止に役立ちます。
FirstLookは、エクスポート先を初めて保存したときにExternal IDを生成します。今は信頼ポリシーのプレースホルダーをそのままにして、手順4で生成された値に置き換えてください。
3. ダッシュボードの初期設定を保存
Section titled “3. ダッシュボードの初期設定を保存”ゲームのダッシュボードを開き、Configuration > Player Data Export > Configuration に移動します。
ロールのセットアップが完了するまでEnabledをオフにしたまま、以下の設定を入力します。
| 設定 | 値 |
|---|---|
| Kind | Amazon S3。 |
| Bucket | s3:// やパスを含めないバケット名。 |
| Prefix | firstlook/exports、またはIAMポリシーで使用したプレフィックス。ポリシーがバケットのルートへの書き込みを許可している場合は省略できます。 |
| IAM Role ARN | arn:aws:iam::123456789012:role/FirstLookPlayerExport など、ロールのARN。 |
| AWS Region | us-east-1 など、バケットが存在するリージョン。 |
| Chunk size | ファイルあたりのプレイヤー数。デフォルトは 1,000、最小値は 1 です。 |
| Enabled | 初期設定中はオフにし、自動エクスポートを開始する準備ができたらオンにします。 |
Save Changes をクリックします。FirstLookはエクスポート先を保存し、External IDを生成します。Enabledがオフでも書き込みプローブを試行します。
信頼ポリシーにプレースホルダーが残っているため、最初の保存でIAMロールのエラーが表示されるのは想定どおりです。エクスポート先は保存され、読み取り専用の External ID フィールドを確認できるようになります。
4. External IDを追加してエクスポートを有効化
Section titled “4. External IDを追加してエクスポートを有効化”- Player Data Export Configurationタブから External ID をコピーします。
- IAMロールの信頼ポリシーで、
YOUR_EXPORT_EXTERNAL_IDをコピーした値に正確に置き換えます。 - FirstLookに戻り、Enabledをオンにして、再度 Save Changes をクリックします。
- ダッシュボードに Export destination saved and write probe passed と表示されることを確認します。
S3 Eventsをすでに設定している場合も、このエクスポート設定のExternal IDを使用してください。エクスポート先を再保存してもExternal IDは維持されます。エクスポート先を削除して作成し直した場合は、新しいExternal IDで信頼ポリシーを更新してください。
保存時には、設定したプレフィックス配下に一時的な _firstlook_probe_<uuid> オブジェクトを書き込み、その削除を試行してアクセスを検証します。保存してもプレイヤー全件のエクスポートは実行されません。有効なエクスポート先は、以降のエクスポート実行で処理されます。
エクスポートファイル
Section titled “エクスポートファイル”各実行は専用のディレクトリを作成します。上記のプレフィックスを使用した場合の構造は次のとおりです。
s3://YOUR_BUCKET_NAME/firstlook/exports/ 2026-10-29/ 20261029T143012Z_<uuid>/ my-game_players_20261029T143012Z_0001.jsonl my-game_players_20261029T143012Z_0002.jsonl _SUCCESS- 日付ディレクトリと実行タイムスタンプは UTC を使用し、そのゲームのエクスポートが開始した時刻を表します。
- 再試行を含むすべての試行に一意のIDが付くため、別の試行が以前のディレクトリを上書きしたり、以前の完了マーカーを再利用したりすることはありません。
- 日付ディレクトリは設定したプレフィックスの直下に配置されます。ゲームスラッグのディレクトリは追加されません。
- パート番号は
0001から始まります。各ファイルには設定したチャンクサイズまでのプレイヤーが含まれます。最後のファイルのプレイヤー数はそれより少ない場合があります。 - ファイルはUTF-8のJSONL形式です。1行につき1つのJSONオブジェクトが含まれ、全体を囲むJSON配列はありません。
_SUCCESSは、すべてのパートが正常にアップロードされた後に書き込まれる0バイトのS3オブジェクトです。プレイヤーがいないゲームでは、JSONLパートなしでマーカーのみが生成されます。
完了した実行の読み取り
Section titled “完了した実行の読み取り”実行ディレクトリを処理する前に、_SUCCESS が書き込まれるのを待ってください。その後、そのディレクトリ内のすべての .jsonl パートを1つのエクスポートとして読み取ります。_SUCCESS がないディレクトリは不完全な可能性があるため、成功した実行として読み込まないでください。
各実行は、前回の実行以降に変更されたレコードだけでなく、現在のレコード全体をエクスポートします。ウェアハウスに複数の実行を保持する場合は、実行IDや日付で分けて管理するか、すべてのスナップショットを1つの現在のプレイヤーテーブルに追記するのではなく、player.game_id と player.id を使ってレコードをマージしてください。
プレイヤーレコードは実行中にバッチ単位で読み取られます。値は各バッチを読み取った時点の状態を反映します。実行全体が、すべてのプレイヤーについて厳密に同一時点のトランザクション整合性を持つビューを提供するわけではありません。
バケット内のオブジェクトの保持期間は自社で管理します。古い実行や不完全なディレクトリを期限切れにするには、S3ライフサイクルルールを設定してください。
メールアドレス、名、姓に対応する専用の本人識別フィールドは除外されます。ただし、エクスポートにはプラットフォーム識別子、アカウント名やハンドル、メモ、カスタムデータなど、個人情報を含みうるフィールドが保持されます。エクスポートされたレコードは、匿名データではなくプレイヤーデータとして扱ってください。
エクスポートの監視
Section titled “エクスポートの監視”Configuration > Player Data Export > Monitor に移動すると、以下を確認できます。
- Last Run — 直近のエクスポート試行が開始した時刻。
- Last Success — 最後にエクスポートが正常完了した時刻。
- Status — 最新の成功またはエラーの記録に基づく
Pending、Healthy、Failedのいずれか。 - Last Error — 最後に記録されたエラーとその時刻。
最初のエクスポート試行前は、Monitorにエクスポートがまだ実行されていないことが表示されます。この表は最新の状態を要約するものであり、ファイルごとのログやすべての実行の履歴ではありません。
トラブルシューティング
Section titled “トラブルシューティング”| 症状 | 確認事項 |
|---|---|
| Failed to assume IAM role | Role ARN、FirstLookアカウントのプリンシパル、sts:ExternalId 条件を確認してください。エクスポートのConfigurationタブに表示されるExternal IDを使用してください。 |
| Write probe failed | バケット名、AWS Region、プレフィックス、ロールの s3:PutObject 権限、書き込みに影響するバケットポリシーやKMSポリシーを確認してください。 |
| プローブファイルがバケットに残る | _firstlook_probe_* に対する s3:DeleteObject 権限を確認してください。削除に失敗しただけでは、書き込みプローブが失敗したとは限りません。 |
ファイルは存在するが _SUCCESS がない | 不完全なディレクトリとして扱ってください。Monitorでエラーを確認し、成功した実行を待ってから読み込んでください。 |
| 保存後もファイルがない | 保存時に実行されるのは書き込みプローブであり、全件エクスポートではありません。Enabledを確認し、設定エラーを解消してからMonitorで次のエクスポート試行を確認してください。 |
IAMポリシーやバケットポリシーを変更した後は、Configurationに戻り、Save Changes をクリックして書き込みプローブを再実行してください。Monitorで全件エクスポートの成功を確認してください。