Amazon S3 가져오기

Amplitude의 Amazon S3 Import를 사용하면 이벤트 데이터를 가져오고 변경할 수 있으며, AWS S3 버킷에서 사용자 또는 그룹 속성을 Amplitude 프로젝트로 동기화할 수 있습니다. Amazon S3 Import를 사용하여 대량의 기존 데이터를 다시 채우고, 기존 데이터 파이프라인을 Amplitude에 연결하며, 높은 처리량이 필요하고 지연 시간이 덜 민감한 곳에서 대량의 데이터를 수집할 수 있습니다.

설정 중에 Amplitude가 이벤트를 계측하는 방법을 제어하기 위해 변환 규칙을 구성합니다. Amazon S3 Import를 설정하고 활성화한 후에는 Amplitude의 수집 서비스가 S3 버킷에서 데이터 파일을 지속적으로 검색한 다음 이벤트를 변환 및 수집합니다.

사전 조건

시작하기 전에 다음 사전 요구 사항을 충족하는지 확인하십시오.

• 데이터를 수신하기 위해 Amplitude 프로젝트가 존재합니다. 그렇지 않은 경우 새 프로젝트를 생성하십시오.
  • 귀하는 Amplitude 프로젝트의 관리자(Admin) 또는 매니저(Manager)입니다.
• 귀하의 S3 버킷에는 Amplitude가 수집할 수 있는 데이터 파일이 준비되어 있습니다. 데이터 파일은 변환기 파일에 설명된 매핑과 일치해야 합니다.
• 가져올 데이터의 각 행은 고유하고 insert_id변경 불가능해야 합니다. 이를 통해 예기치 않은 문제가 발생할 경우 데이터 중복을 방지할 수 있습니다. 자세한 내용은 데이터 중복 제거(insert_id 사용)를 참조하십시오.
• 미러 데이터 동기화를 수행하려면 사용자 ID가 필요합니다. 행에 사용자 ID가 포함되어 있지 않은 경우 Amplitude는 해당 이벤트를 삭제합니다.

파일 요구 사항

Amplitude로 전송하려는 파일은 몇 가지 기본 요구 사항을 준수해야 합니다.

• 파일에는 이벤트가 포함되어 있으며 한 줄에 하나의 이벤트가 있습니다.
• 이벤트의 시간순으로 파일을 업로드합니다.
• 파일 이름은 고유합니다.
• 파일 크기는 1MB보다 크고 5GB보다 작아야 합니다. 대규모 이벤트 볼륨을 가진 고객의 경우, Amplitude는 최적의 성능을 위해 파일 크기를 500MB에 가깝게 설정할 것을 권장합니다.
• 파일은 압축되었거나 압축되지 않은 JSON, CSV 또는 Parquet 파일입니다.
• 변이를 지원하는 미러 동기화의 경우 다음과 같은 제약 조건이 적용됩니다.
  • 이벤트에 대한 변형은 사용자 ID를 필요로 합니다. 행에 사용자 ID가 포함되어 있지 않은 경우 Amplitude는 해당 이벤트를 삭제합니다. 많은 양의 익명 이벤트가 발생하는 경우 Amplitude는 이 모드를 사용하지 않는 것을 권장합니다.
  • Amplitude는 INSERT, UPDATE, 및 DELETE와 같은 뮤테이션(mutation) 유형을 허용합니다. 변이 유형을 제공하지 않으면 프로세스의 기본값은 UPDATE입니다.

데이터 중복 제거 기능 insert_id

데이터 동기화의 경우에만 Amplitude는 고유 식별자인 insert_id을(를) 사용하여 수신 이벤트와 일치시키고 중복을 방지합니다. 동일한 프로젝트 내에서 Amplitude가 첫 사용 후 7일 동안 수신된 다른 이벤트와 동일한 값을 insert_id가진 device_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 버킷 이름입니다.
   • <prefix>: 가져올 파일의 선택적 접두사(예: 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 Import 소스를 생성합니다.

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 Import 소스를 생성합니다.

1. Amplitude Data에서 Catalog를 클릭하고 Sources 탭을 선택합니다.

2. 웨어하우스 소스 섹션에서 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. 모든 값을 입력한 후 자격 증명 테스트를 클릭합니다. 소스를 생성한 후에는 UI에서 이러한 값을 편집할 수 없으므로 다음을 클릭하기 전에 모든 정보가 올바른지 확인하십시오.
7. 데이터 소스 이름과 설명(선택 사항)을 입력하고 소스를 저장합니다. 설정에서 이러한 세부 정보를 편집할 수 있습니다.

다음으로 컨버터 구성을 생성합니다.

Amplitude는 버킷을 지속적으로 스캔하여 새로운 파일이 추가될 때 이를 발견합니다.

파일 선택

1. 파일의 파일 유형, 압축 유형 및 정규식 패턴을 지정합니다. 이 단계에서 선택한 사항에 따라 변환기 파일의 상용구(boilerplate)가 미리 채워집니다. 미리보기를 클릭하여 구성을 테스트합니다.
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에게 수집된 파일을 처리하는 방법을 알려줍니다. 이를 생성하려면 두 단계를 거쳐야 합니다. 첫째, 파일의 압축 유형, 파일 이름 및 이스케이프 문자를 구성합니다.

그런 다음 JSON을 사용하여 변환기가 준수하는 규칙을 설명하십시오.

컨버터 언어는 주어진 JSON 요소에서 값을 추출하는 방법을 설명합니다. 이 값은 다음을 포함하는 SOURCE_DESCRIPTION을 사용하여 지정합니다.

• BASIC_PATH.
• LIST_OPERATOR입니다.
• JSON_OBJECT입니다.

소스 활성화

소스를 활성화하려면 변환기를 성공적으로 테스트해야 합니다. 변경 사항을 저장하고 나중에 다시 돌아올 수 있지만 소스를 활성화하는 옵션은 변환기가 테스트를 성공적으로 완료한 후에만 사용할 수 있습니다.

변환기를 구성할 때 저장 및 활성화를 클릭하여 소스를 활성화합니다.

문제 해결

• 올바른 Amplitude 계정에 대한 액세스 권한을 부여했는지 확인하십시오. 조직과 동일한 데이터 센터를 사용하십시오. 자세한 내용은 S3 버킷에 대한 Amplitude 액세스 권한을 부여하기를 참조하십시오.
• Amplitude는 버킷 이름에 점 문자를 지원하지 않습니다. 버킷 이름이 소문자, 숫자 및 대시로 구성되어 있는지 확인하십시오.
• 자신이 소유하고 있는 기존 버킷을 사용할 수 있습니다. 호환성을 보장하려면 Amplitude 마법사의 결과를 사용하여 버킷의 정책을 업데이트하십시오.