콘텐츠로 이동
Get Started

S3 플레이어 데이터 내보내기

Player Data Export는 게임의 플레이어 레코드를 소유하고 있는 Amazon S3 버킷에 기록합니다. 이 레코드를 데이터 웨어하우스나 보고 파이프라인에서 사용하여 FirstLook의 플레이어 정보를 자체 게임 및 비즈니스 데이터와 연결할 수 있습니다.

각 내보내기 실행은 현재 플레이어 레코드를 JSON Lines(JSONL) 파일로 기록하며, 한 줄에 플레이어 한 명이 포함됩니다. 레코드는 번호가 매겨진 여러 파일로 나뉘며, 모든 파일 기록 후 완료 마커가 생성되어 파이프라인에서 전체 실행이 준비되었는지 확인할 수 있습니다.

버킷의 이벤트를 FirstLook으로 가져오려면 S3 이벤트를 참고하세요. 분석 차트의 원본 데이터를 다운로드하려면 분석 내보내기를 참고하세요.


FirstLook이 내보내기 데이터를 기록하기 위해 수임할 수 있는 IAM 역할을 AWS 계정에 생성합니다. 설정은 S3 이벤트와 동일한 크로스 계정 역할 패턴을 따르지만, 파일을 읽는 대신 쓰는 권한을 부여합니다.

아래 예시는 프리픽스 firstlook/exports를 사용합니다. 다른 프리픽스를 사용할 수도 있지만 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 역할 생성

섹션 제목: “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단계에서 생성된 값으로 교체하세요.

게임 대시보드를 열고 Configuration > Player Data Export > Configuration으로 이동합니다.

역할 설정이 완료될 때까지 Enabled를 끈 상태로 다음 설정을 입력합니다.

설정값
KindAmazon S3.
Buckets3://나 경로를 제외한 버킷 이름.
Prefixfirstlook/exports 또는 IAM 정책에 사용한 프리픽스. 정책이 버킷 루트에 대한 쓰기를 허용하면 생략할 수 있습니다.
IAM Role ARNarn:aws:iam::123456789012:role/FirstLookPlayerExport와 같은 역할의 ARN.
AWS Regionus-east-1과 같은 버킷이 위치한 리전.
Chunk size파일당 플레이어 수. 기본값은 1,000, 최솟값은 1입니다.
Enabled초기 설정 중에는 끄고, 자동 내보내기를 시작할 준비가 되면 켭니다.

Save Changes를 클릭합니다. FirstLook은 대상을 저장하고 External ID를 생성하며, Enabled가 꺼져 있어도 쓰기 프로브를 시도합니다.

신뢰 정책에 여전히 자리 표시자가 포함되어 있으므로 첫 저장 시 IAM 역할 오류가 표시되는 것이 정상입니다. 대상은 저장되며, 이제 읽기 전용 External ID 필드를 확인할 수 있습니다.

4. External ID 추가 및 내보내기 활성화

섹션 제목: “4. External ID 추가 및 내보내기 활성화”
  1. Player Data Export Configuration 탭에서 External ID를 복사합니다.
  2. IAM 역할의 신뢰 정책에서 YOUR_EXPORT_EXTERNAL_ID를 복사한 정확한 값으로 교체합니다.
  3. FirstLook으로 돌아와 Enabled를 켜고 Save Changes를 다시 클릭합니다.
  4. 대시보드에 Export destination saved and write probe passed가 표시되는지 확인합니다.

이미 S3 Events를 설정했더라도 이 내보내기 설정의 External ID를 사용하세요. 대상을 다시 저장해도 External ID는 유지됩니다. 대상을 삭제하고 다시 생성하면 새 External ID로 신뢰 정책을 업데이트하세요.

저장 시 설정한 프리픽스 아래에 임시 _firstlook_probe_<uuid> 객체를 기록한 다음 삭제를 시도하여 액세스를 검증합니다. 저장만으로 전체 플레이어 내보내기가 실행되지는 않으며, 활성화된 대상은 이후 내보내기 실행에 포함됩니다.


각 실행은 자체 디렉터리를 생성합니다. 위의 예시 프리픽스를 사용하면 구조는 다음과 같습니다.

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 형식으로, 한 줄에 JSON 객체 하나가 포함되며 이를 감싸는 JSON 배열은 없습니다.
  • _SUCCESS는 모든 파트가 성공적으로 업로드된 후 기록되는 0바이트 S3 객체입니다. 플레이어가 없는 게임은 JSONL 파트 없이 마커만 생성합니다.

실행 디렉터리를 처리하기 전에 _SUCCESS가 생성될 때까지 기다리세요. 그런 다음 해당 디렉터리의 모든 .jsonl 파트를 하나의 내보내기로 읽습니다. _SUCCESS가 없는 디렉터리는 불완전할 수 있으므로 성공한 실행으로 로드해서는 안 됩니다.

각 실행은 이전 실행 이후 변경된 레코드만이 아니라 현재 레코드 전체를 내보냅니다. 웨어하우스에 여러 실행을 보관한다면 실행 ID나 날짜별로 구분하거나, 모든 스냅샷을 하나의 현재 플레이어 테이블에 계속 추가하는 대신 player.game_id와 player.id를 사용하여 레코드를 병합하세요.

플레이어 레코드는 실행 중 배치 단위로 읽습니다. 값은 각 배치를 읽는 시점의 상태를 반영하며, 실행 결과가 모든 플레이어를 정확히 같은 시점에 트랜잭션 일관성을 유지하며 조회한 것은 아닙니다.

버킷의 객체 보존 기간은 직접 관리합니다. 이전 실행이나 불완전한 디렉터리가 만료되도록 하려면 S3 수명 주기 규칙을 설정하세요.


이메일 주소, 이름, 성을 위한 전용 식별 정보 필드는 제외됩니다. 그러나 내보내기에는 플랫폼 식별자, 계정 이름과 핸들, 메모, 사용자 정의 데이터 및 개인정보가 포함될 수 있는 기타 필드가 유지됩니다. 내보낸 레코드를 익명 데이터가 아닌 플레이어 데이터로 취급하세요.


Configuration > Player Data Export > Monitor로 이동하여 다음을 확인할 수 있습니다.

  • Last Run — 가장 최근 내보내기 시도가 시작된 시점.
  • Last Success — 마지막으로 내보내기가 성공적으로 완료된 시점.
  • Status — 가장 최근에 기록된 성공 또는 오류를 기반으로 한 Pending, Healthy 또는 Failed 상태.
  • Last Error — 가장 최근에 기록된 오류와 발생 시점.

첫 내보내기 시도 전에는 Monitor에 아직 내보내기 실행이 없다는 메시지가 표시됩니다. 이 표는 최신 상태를 요약하며, 파일별 로그나 모든 실행의 기록을 제공하지는 않습니다.

증상확인할 사항
Failed to assume IAM roleRole 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에서 전체 내보내기가 성공하는지 확인하세요.