# 데이터 연동 - 데이터 가져오기 (Data Import) {% hint style="info" %} 엔터프라이즈 플랜에서만 지원하는 기능입니다. {% endhint %} ### 데이터 가져오기 (Data Import) 데이터 가져오기 (Data Import) 기능을 통해서 고객사의 AWS S3, GCP GCS 에 저장되어 있는 이벤트 데이터를 핵클로 보낼 수 있습니다. 데이터 가져오기 기능은 일별 (Daily) 로 데이터를 가져옵니다. #### 지원 가능 저장소 (Supported Cloud Storage) | | | | | --- | -------- | ----- | | AWS | S3 | Y | | AWS | Redshift | 지원 예정 | | GCP | GCS | Y | | GCP | BigQuery | 지원 예정 | #### 사전 준비 (Requirements) 데이터 추출 전 다음 작업이 필요합니다. * [x] 이벤트 데이터를 저장할 저장소를 생성합니다. (AWS S3, GCP GCS 등) * [x] 이벤트 데이터를 저장할 저장소의 접근 하기 위한 Key 를 생성하고 권한을 부여합니다. * [x] 이벤트 데이터를 규격에 맞추어 가공해 일별로 저장합니다. (예시 `2023-01-01`, `2023-01-02` 등) **Key 생성 및 권한 부여: GCP GCS** GCP GCS 의 경우 [GCP IAM > 서비스 계정 키 생성 및 관리](https://cloud.google.com/iam/docs/creating-managing-service-account-keys?hl=ko) 문서를 참고해 Key 를 생성할 수 있습니다. GCS 접근을 위한 Key 생성시 아래의 권한이 필요합니다. ``` storage.buckets.get storage.objects.get storage.objects.create storage.objects.delete storage.objects.list ``` **Key 생성 및 권한 부여: AWS S3** AWS S3의 경우 다음 문서들을 참고해 Key를 생성하고 필요한 권한을 부여할 수 있습니다. 1. [AWS Docs: IAM User 생성하기](https://docs.aws.amazon.com/ko_kr/IAM/latest/UserGuide/id_users_create.html) 문서를 따라 AWS IAM User 를 생성합니다. 2. [AWS Docs: IAM Policy 생성하기](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html#access_policies_create-start) 를 따라 Policy 를 생성하고 아래 코드로 첨부된 IAM Policy 정책을 포함해 생성합니다. 이후 이전 단계에서 생성한 IAM Role 에 IAM Policy 정책을 추가합니다. 3. [AWS Docs: IAM Key 생성하기](https://docs.aws.amazon.com/ko_kr/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) 를 따라 Key 를 생성합니다 ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectVersion", "s3:DeleteObject", "s3:PutObject" ], "Resource": "arn:aws:s3::://*" }, { "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetBucketLocation" ], "Resource": "arn:aws:s3:::", "Condition": { "StringLike": { "s3:prefix": [ "/*", "/", "" ] } } } ] } ``` #### 데이터 가져오기를 위한 데이터 형식 (Data Import Format) 데이터 가져오기는 현재 [Apache Parquet](https://parquet.apache.org/) 형식을 지원합니다. 아래는 전달되는 Parquet 형식 데이터의 스키마입니다. 아래 테이블에 설명된 포맷으로 가공해 저장합니다. | Column Category | Column Name | Column Type | Column Value (Example) | Description | | ------------------- | --------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Insert ID | `insert_id` | STRING | `8fb8e088-9245-4fce-bb87-7e09d9917ed6` | UUID 값으로 이벤트 중복을 확인하기 위해 사용됩니다. | | Event Key | `event_key` | STRING | `purchase` | 이벤트 명칭입니다. | | Client Timestamp | `ts` | TIMESTAMP | `2023-01-01 00:01:02.333` (UTC) | UTC 기준의 Timestamp (Millis 미만은 절삭) | | Metric Value | `metric_value` | DECIMAL(24, 6) | `0.0` | 분석 및 실험에서 값 연산을 위해 사용합니다. (필요 없을 경우 `0.0` 저장) | | Identifiers | `identifiers` | Map\ | `{ "id": "8fb8e088-9245-4fce-bb87-7e09d9917ed6", "device_id": "89ABCDEF-01234567-89ABCDEF", "user_id": "49591", "session_id": "1659710029.4.1.1659710504.0" }` |

사용자 식별자를 담고 있는 맵

  • (옵션) user\_id: 로그인 사용자 식별자(Hackle SDK 전송 시 userId 에 해당하는 값)
  • (필수) id: 기기 식별자(Hackle SDK 전송 시 id 에 해당하는 값)
  • (필수) device\_id 기 식별자(Hackle SDK 전송 시 deviceId 에 해당하는 값)
  • (옵션, GA 사용시 적재) ga\_session\_id, ga\_device\_id

Identifiers 키 값은 Lowercase 로 저장됩니다.

| | Event Properties | `event_properties` | Map\ | `{ "product_id": "33537", "product_category": "LEISURE", "order_id": "291994100" }` |

이벤트 정보를 담고 있는 프로퍼티

Property 키 값은 Lowercase 로 저장됩니다.

| | User Properties | `user_properties` | Map\ | `{ "grade": "GOLD", "date_signed": "2022-07-01", "date_recent": "2023-01-17" }` |

사용자 정보를 담고 있는 프로퍼티

Property 키 값은 Lowercase 로 저장됩니다.

| | Platform Properties | `platform_properties` | Map\ |

# Android 예시

/{ "osname":"Android", "appversion": "6.9.0", "language":"ko", "osversion":"12", "devicevendor":"samsung", "versionname":"6.77.0-DEBUG", "platform":"Mobile", "devicemodel":"SM-S908N" /}

iOS 예시

{ "osname":"iOS", "appversion": "6.9.3", "language":"ko-KR", "osversion":"16.0.2", "devicevendor":"Apple", "versionname":"6.77.0", "platform":"Mobile", "devicemodel":"iPhone14,2" /}

|

플랫폼 정보를 담고있는 프로퍼티

  • (필수) osname (Android, iOS)
  • (필수) appversion

Property 키 값은 Lowercase 로 저장됩니다.

| 아래는 위 테이블에서 설명한 데이터 포맷에 대한 요약입니다. ```json root |-- ts: timestamp (nullable = false) |-- event_key: string (nullable = false) |-- identifiers: string (nullable = false) |-- insert_id: string (nullable = false) |-- metric_value: decimal(24,6) (nullable = false) |-- user_properties: map (nullable = false) |-- event_properties: map (nullable = false) |-- platform_properties: map (nullable = false) ``` #### 데이터 가공하기 (Processing for Data Import) 데이터를 앞서 언급한 Parquet Format 에 맞추어 가공후 Bucket 내에 일별로 저장합니다. * [x] 데이터 가공 완료되었을 경우 0 Byte 의 `_SUCCESS` (Signal) 파일을 만듭니다. * [x] 데이터 가공은 D-1 데이터를 포함합니다. 예를 들어, 1월 2일 데이터 가져오기 실행시에는 1월 1일 데이터를 가공해 놓으면 됩니다. 다음은 저장된 파티션 및 파일의 예시입니다. ``` # 2023-01-01 데이터 gcs://customer-data-hackle/test/prefix-custom/dt=2023-01-01/_SUCCESS gcs://customer-data-hackle/test/prefix-custom/dt=2023-01-01/000000000000.parquet gcs://customer-data-hackle/test/prefix-custom/dt=2023-01-01/000000000001.parquet # 2023-01-02 데이터 gcs://customer-data-hackle/test/prefix-custom/dt=2023-01-02/_SUCCESS gcs://customer-data-hackle/test/prefix-custom/dt=2023-01-02/000000000000.parquet gcs://customer-data-hackle/test/prefix-custom/dt=2023-01-02/000000000001.parquet ``` #### 데이터 가져오기 요청 데이터 가져오기 요청은 핵클로 문의 부탁드립니다. 데이터 가져오기를 위해 아래 정보가 필요합니다. * [x] 접근을 위해 권한이 부여된 Key * [x] AWS S3, GCS Bucket 이름 및 Bucket 내 데이터가 적재될 파티션 경로 (예시: `gcs://customer-data-hackle/test/prefix-custom/dt=2023-01-01`) * [x] 데이터 적재 시점 (예시: KST 13:00 이전까지 적재 완료) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hackle.io/data-link/data-integration-data-import.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.