Google 클라우드 스토리지(GCS)

Amplitude의 GCS 가져오기 기능을 사용하면 GCS 버킷에서 이벤트 또는 사용자 속성을 Amplitude 프로젝트로 가져올 수 있습니다. 이 문서는 Amplitude 첫 사용 후 이 데이터 소스를 구성하는 데 도움을 줍니다.

시작하기

사전 조건

시작하기 전에 몇 가지 전제 조건을 충족했는지 확인하십시오.

• 적절한 권한 관리이 있는 GCS 서비스 계정이 있는지 확인하십시오. 자세히 알아보기.
• 데이터를 수신할 Amplitude 프로젝트가 있는지 확인하십시오. 그렇지 않은 경우 새 프로젝트를 생성하십시오.
• 귀하가 Amplitude 프로젝트의 관리자 또는 매니저인지 확인하십시오.
• GCS 버킷에 수집할 수 있는 데이터 파일이 준비되어 있는지 확인하십시오. 데이터 파일은 변환기 파일에 설명된 매핑과 일치해야 합니다.
• GCS 버킷의 데이터가 Amplitude의 HTTP API v2 사양에 설명된 형식을 따르는지 확인하세요.

파일 요구 사항

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

• 파일에는 이벤트가 포함되어 있으며 한 줄에 하나의 이벤트가 있습니다.
• 파일은 이벤트의 시간순으로 업로드됩니다.
• 파일 이름은 고유합니다.
• 파일 크기는 1MB보다 크고 5GB보다 작아야 합니다. 대규모 이벤트를 처리하는 고객의 경우, Amplitude는 최적의 성능을 위해 파일 크기를 500MB에 가깝게 설정할 것을 권장합니다.
• 파일은 압축되었거나 압축되지 않은 JSON, CSV 또는 Parquet 파일입니다.

GCS 서비스 계정 생성 및 권한 관리 설정

아직 계정을 만들지 않은 경우 Google Cloud 콘솔에서 Amplitude에 대한 서비스 계정을 생성하세요. 이를 통해 Amplitude는 귀하의 데이터를 Google Cloud 프로젝트로 내보낼 수 있습니다.

서비스 계정을 생성한 후에는 서비스 계정 키 파일을 생성하여 다운로드한 후 Amplitude에 업로드하십시오. Amplitude의 계정 키를 JSON 형식으로 내보내야 합니다.

이 서비스 계정을 데이터를 내보내려는 버킷에 멤버로 추가하십시오. 이 멤버에게 스토리지 관리자 역할을 부여해야 Amplitude가 데이터를 버킷으로 내보내는 데 필요한 권한 관리를 갖게 됩니다.

원하는 경우 자신만의 역할을 만들 수도 있습니다.

내보내기 프로세스에는 최소한 다음과 같은 권한 관리 설정이 필요합니다.

• storage.buckets.get.
• storage.objects.get.
• storage.objects.create.
• storage.objects.delete.
• storage.objects.list.

새 GCS 소스 추가

Amplitude에서 데이터를 가져오기 위한 새 GCS 데이터 소스를 추가하려면 다음 단계를 따르십시오.

1. Amplitude Data에서 카탈로그를 클릭하고 소스 탭을 선택합니다.
2. 웨어하우스 소스 섹션에서 GCS를 클릭합니다.
3. 서비스 계정 키 파일을 업로드합니다. 이를 통해 Amplitude는 GCS 버킷에서 데이터를 가져올 수 있는 권한 관리 설정을 갖게 됩니다.
4. 서비스 계정 키 파일을 업로드한 후 버킷 이름과 데이터가 저장된 폴더를 입력합니다.
5. 다음을 클릭하여 자격 증명을 테스트합니다. 모든 정보가 확인되면 Amplitude는 성공 메시지를 표시합니다. 다음 > 을 클릭하여 프로세스를 계속합니다.
6. [데이터 소스 활성화] 패널에서 데이터 소스의 이름을 지정하고 설명을 입력합니다. 이 정보는 나중에 설정을 통해 편집할 수 있습니다. 그런 다음 소스 저장을 클릭합니다. Amplitude는 귀하가 소스를 생성하고 활성화했음을 확인합니다.
7. 데이터 소스 목록으로 돌아가려면 완료를 누릅니다. 이미 변환기를 구성한 경우 데이터 가져오기가 몇 분 후에 시작됩니다. 그렇지 않으면, 이제 데이터 변환기를 만들 차례입니다.

변환기 구성 생성

Amplitude의 GCS 수집 소스를 설정하는 마지막 단계는 변환기 파일을 만드는 것입니다. 컨버터 구성은 연동에 다음과 같은 정보를 제공합니다.

• Amplitude에게 유효한 데이터 파일의 모양을 알려주는 패턴입니다. 예를 들어 "\w+_\d{4}-\d{2}-\d{2}.json.gz".
• 파일이 압축되었는지 여부와 압축된 경우 그 방법입니다.
• 파일의 형식입니다. 예를 들어 CSV(특정 구분자 포함) 또는 JSON 객체의 줄입니다.
• 파일의 각 행을 Amplitude 이벤트로 매핑하는 방법.

변환기 파일은 Amplitude에게 수집된 파일을 처리하는 방법을 알려줍니다. 생성하려면 두 단계를 거쳐야 합니다. 첫째, 파일의 압축 유형, 파일 이름 및 이스케이프 문자를 구성합니다. 그런 다음 JSON을 사용하여 변환기가 준수하는 규칙을 설명하십시오.

변환기 작성 안내

Amplitude의 새로운 가이드 컨버터 생성 인터페이스를 통해 컨버터를 생성할 수 있습니다. 이를 통해 필드를 시각적으로 매핑하고 변환할 수 있으므로 JSON 구성 파일을 수동으로 작성할 필요가 없습니다. 내부적으로 UI는 Amplitude에서 사용되는 기존 JSON 구성 언어로 컴파일됩니다.

먼저, 가져올 수 있는 다양한 데이터 유형(이벤트, 사용자 속성 및 그룹 속성 데이터)을 살펴보십시오.

특정 필드를 선택한 후 데이터베이스의 필드를 변환하도록 선택할 수 있습니다. 이를 위해 '트랜스포메이션'을 클릭하고 적용하려는 트랜스포메이션의 종류를 선택합니다. 각 트랜스포메이션에 대한 간단한 설명을 확인할 수 있습니다.

필드를 선택한 후에는 트랜스포메이션 모달을 열고 다양한 트랜스포메이션 중에서 선택할 수 있습니다.

선택한 트랜스포메이션에 따라 더 많은 필드를 포함해야 할 수도 있습니다.

트랜스포메이션에 필요한 모든 필드를 갖추고 나면 이를 저장할 수 있습니다. 요구 사항이 변경될 경우 이를 업데이트할 수 있습니다.

Amplitude는 데이터를 가져오기 위해 특정 필드가 필요하지만, '매핑 추가' 버튼을 클릭하여 포함할 수 있는 추가 필드도 지원합니다. 여기서 Amplitude는 이벤트 속성, 사용자 속성, 그룹 속성 및 추가 속성의 4가지 유형의 매핑을 지원합니다.

이벤트에 대해 지원되는 필드 목록은 HTTP V2 API 설명서에서 확인하고 사용자 속성에 대해 지원되는 필드 목록은 Identify API 설명서에서 확인하십시오. 이러한 목록에 없는 열을 모두 event_properties또는 user_properties에 추가하십시오. 그렇지 않으면 Amplitude는 해당 열을 무시합니다.

Amplitude에 가져오려는 모든 필드를 추가한 후에는 데이터 미리보기 섹션에서 이 구성의 샘플을 볼 수 있습니다. 데이터 미리 보기는 필드와 속성을 포함하거나 제거할 때 자동으로 업데이트됩니다. 데이터 미리보기에서는 소스 레코드를 기반으로 몇 가지 샘플 레코드를 확인할 수 있으며 Amplitude가 해당 데이터를 가져오는 방식도 확인할 수 있습니다. 이를 통해 필요한 모든 데이터 포인트를 Amplitude로 가져올 수 있습니다. 10개의 서로 다른 샘플 소스 레코드와 해당 Amplitude 이벤트를 볼 수 있습니다.

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

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

Amplitude에서 변환기 구성

1. 가져오기 구성 편집을 클릭하여 파일의 압축 유형, 파일 이름 및 이스케이프 문자를 구성합니다. 변환기 파일의 상용구는 이 단계에서 수행한 선택 사항을 기반으로 미리 채워집니다. 파일 가져오기를 클릭하여 구성이 작동하는지 테스트할 수도 있습니다.
2. 다음을 클릭합니다.
3. 텍스트 편집기에 변환기 규칙을 입력합니다.
4. 전환을 테스트하세요. 변환 테스트를 클릭합니다. 전환 미리보기를 검토합니다. 필요에 따라 컨버터 구성을 조정하십시오.
5. 완료를 클릭합니다.

미리 보기 중 "잘못된 형식의 파일" 오류 발생

변환기를 사용하여 미리 보기 다음 기간동안 오류가 발생하는 경우, 원본 GCS 파일의 형식이 잘못되었음을 항상 의미하는 것은 아닙니다. Amplitude는 먼저 GCS에서 내부 S3로 파일을 복사합니다. 미리보기 버튼은 GCS에 직접 있는 것이 아니라 S3에 있는 파일을 반영합니다. 파일이 필수 폴더 구조와 일치하지 않는 경우, Amplitude는 해당 파일을 Amplitude S3에 복사하지 않으므로 미리보기에는 아무것도 가져오거나 표시되지 않습니다.

스토리지 구성 요구 사항

초기 수집 이후에는 데이터 구성이 후속 가져오기에 대해 이 표준을 준수해야 합니다.

{bucket name}/{GCSPrefix}/{YYYY}/{MM}/{DD}/{HH}/{optional}/{additional}/ {folder}/{structure}/{file name}

위치:

• {bucket name} 는 GCS 버킷의 이름입니다.
• {GCSPrefix} 는 소스 설정 구성에 지정된 소스 접두사 폴더입니다.
• {YYYY}/{MM}/{DD}/{HH} 는 새 파일을 업로드하는 데 필요한 날짜 접두어 형식입니다. 시스템에서 파일을 생성할 때가 아니라 파일이 버킷에 업로드된 시간을 기준으로 파일을 구성하십시오. 또한 월, 일 및 시간을 나타내기 위해 항상 두 자리(한 자리가 아닌)를 사용해야 합니다.
• {optional}/{additional}/{folder}/{structure} 폴더 구조 세부 정보를 추가할 수 있는 곳입니다. 이러한 세부 정보는 선택 사항입니다. 이러한 파일을 포함하는 경우 예제 파일 경로는 다음과 같을 수 있습니다{bucket name}/{GCSPrefix}/{YYYY}/{MM}/{DD}/{HH}/**cluster-01/node-25**/{file name}.

파일 검색 시간 창(48시간)

Amplitude GCS 가져오기 작업은 경로의 폴더 날짜를 기준으로 지난 48시간 동안의 파일만 검색합니다.

예: 배치 작업이 2024/09/03 00:00에 시작되는 경우 다음 위치에서만 검색됩니다.

{bucket name}/{GCSPrefix}/2024/09/01/00/
  to  
{bucket name}/{GCSPrefix}/2024/09/03/00/

데이터 파일이 이 2일 첫 사용 후 기간에 속하는 폴더에 업로드되도록 해야 Amplitude 서비스가 이를 감지하고 가져올 수 있습니다.