> For the complete documentation index, see [llms.txt](https://www.analytics-docs.laplacetec.com/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.analytics-docs.laplacetec.com/guide/datamanage/datasync/bigquery.md).

# BigQuery로 보내기

라플라스 데이터 싱크로 Google BigQuery에 데이터를 보내는 방법입니다. 서비스 계정 생성과 권한 부여, JSON 키 발급, 목적지 만들기와 싱크 추가 순서를 안내합니다.

라플라스의 데이터를 고객님의 Google BigQuery 데이터셋으로 보냅니다. 고객님 GCP 서비스 계정의 키(JSON)로 적재합니다.

## 준비하기

GCP 콘솔에서 아래 순서대로 준비해 주세요. 이 작업에는 프로젝트의 IAM 권한을 바꿀 수 있는 계정(예: 프로젝트 소유자)이 필요합니다.

서비스 계정에 줄 권한은 아래 두 가지입니다.

| 권한                                             | 줄 곳                                           |
| ---------------------------------------------- | --------------------------------------------- |
| BigQuery 작업 사용자 (`roles/bigquery.jobUser`)     | 데이터를 받을 GCP 프로젝트 (적재 작업이 이 프로젝트에서 실행되고 과금됩니다) |
| BigQuery 데이터 편집자 (`roles/bigquery.dataEditor`) | 보낼 데이터셋                                       |

### 1. 프로젝트와 데이터셋 정하기

1. 데이터를 받을 **GCP 프로젝트**를 정하고, 콘솔 위쪽 프로젝트 선택기에서 그 프로젝트를 골라 주세요.
2. 데이터를 받을 **BigQuery 데이터셋**이 없다면 BigQuery 콘솔의 탐색기에서 프로젝트 옆 **⋮ > 데이터 세트 만들기**로 만들어 주세요.
3. 프로젝트 ID와 데이터셋 이름을 적어 두세요. 목적지를 만들 때 입력합니다.

### 2. 서비스 계정 만들기

1. GCP 콘솔에서 **IAM 및 관리자 > 서비스 계정**으로 가서 **\[서비스 계정 만들기]** 를 눌러 주세요.
2. **서비스 계정 이름**을 입력해 주세요(예: `laplace-data-sync`). 서비스 계정 ID는 자동으로 채워집니다.
3. **\[만들고 계속하기]** 를 누르고, 역할 선택 단계는 건너뛴 채 **\[완료]** 를 눌러 주세요. 권한은 3·4단계에서 필요한 곳에만 줍니다.
4. 목록에 생긴 서비스 계정의 **이메일**(`...@<프로젝트 ID>.iam.gserviceaccount.com`)을 복사해 두세요.

### 3. 프로젝트에 BigQuery 작업 사용자 권한 주기

1. **IAM 및 관리자 > IAM**으로 가서 **\[액세스 권한 부여]** 를 눌러 주세요.
2. **새 주 구성원**에 2단계에서 복사한 서비스 계정 이메일을 붙여 넣어 주세요.
3. **역할 선택**에서 **BigQuery 작업 사용자**를 고르고 **\[저장]** 을 눌러 주세요.

### 4. 데이터셋에 BigQuery 데이터 편집자 권한 주기

1. BigQuery 콘솔의 탐색기에서 보낼 데이터셋을 고르고 **\[공유] > \[권한 관리]** 를 눌러 주세요.
2. **\[주 구성원 추가]** 를 누르고, **새 주 구성원**에 서비스 계정 이메일을 붙여 넣어 주세요.
3. **역할 선택**에서 **BigQuery 데이터 편집자**를 고르고 **\[저장]** 을 눌러 주세요.

{% hint style="info" %}
쓰기 권한은 프로젝트 전체가 아니라 **보낼 데이터셋에만** 주세요. 그러면 라플라스는 그 데이터셋 밖의 데이터를 바꿀 수 없습니다.
{% endhint %}

### 5. 키 파일(JSON) 받기

1. **IAM 및 관리자 > 서비스 계정**에서 2단계에서 만든 서비스 계정을 눌러 주세요.
2. **\[키]** 탭에서 **\[키 추가] > \[새 키 만들기]** 를 눌러 주세요.
3. 키 유형으로 **JSON**을 고르고 **\[만들기]** 를 누르면 키 파일이 내려받아집니다.

{% hint style="warning" %}
키 파일은 이 서비스 계정으로 로그인할 수 있는 비밀번호와 같습니다. 메일이나 메신저로 주고받지 말고, 목적지를 만들 때 라플라스 화면에 직접 올려 주세요. 올린 뒤에는 내 컴퓨터에 받은 파일을 지워도 됩니다.
{% endhint %}

목적지마다 키를 나누려면 서비스 계정을 따로 만들어 그 키를 올리시면 됩니다.

## 목적지 만들기

1. 왼쪽 메뉴의 **\[데이터 싱크] > \[BigQuery]** 를 눌러 주세요.
2. 오른쪽 위의 **\[목적지 추가]** 를 눌러 주세요.
3. 목적지 정보를 입력해 주세요.
   * **인증 방식**: 고객 서비스 계정 키
   * **서비스 계정 키**: **\[새 키 파일 올리기]** 를 고르고 **\[파일 선택]** 으로 준비한 JSON 키를 올려 주세요. 이미 올린 키가 있으면 목록에서 고르시면 됩니다.
   * **GCP 프로젝트 ID**, **데이터셋**: 준비하기 1번에서 정한 값
   * **목적지 별칭**(선택): 목록과 싱크에서 보일 이름입니다. 비우면 "BigQuery"로 저장됩니다.
4. **\[만들기]** 를 눌러 주세요.
5. 다음 화면에 나오는 **데이터셋 라벨 키**와 **데이터셋 라벨 값**을 보낼 데이터셋의 라벨로 달아 주세요. BigQuery 콘솔에서 데이터셋을 고른 뒤 **세부정보 수정 > 라벨**에서 추가할 수 있습니다. 이 데이터셋이 고객님 것임을 확인하는 표시입니다.
6. **\[연결 확인]** 을 눌러 주세요. 연결 상태가 **인증됨**으로 바뀌면 준비가 끝났습니다.

{% hint style="info" %}
키는 라플라스 비밀 저장소에만 보관되고 화면에 다시 보이지 않습니다. 키를 바꾸려면 같은 서비스 계정의 새 키를 다시 올려 주세요. 기존 연결의 키가 새 키로 바뀝니다.
{% endhint %}

## 싱크 추가하기

1. 목적지 행의 **\[+]** 를 눌러 주세요.
2. **보낼 데이터**를 골라 주세요. 새로 고르거나, 저장해 둔 데이터를 불러올 수 있습니다. 보낼 열과 행 하나를 가려내는 식별 열을 정하고, 일부 행만 보내려면 조건을 더해 주세요.
3. **전송 설정**을 입력하고 **\[싱크 만들기]** 를 눌러 주세요.
   * **싱크 이름**
   * **쓰기 방식**: 아래 표를 참고해 주세요.
   * **테이블 이름**: 데이터를 받을 테이블입니다. 없으면 첫 실행 때 만듭니다.
   * **일정**: 언제 보낼지 정합니다.

| 쓰기 방식 | 동작                          |
| ----- | --------------------------- |
| 교체    | 실행마다 테이블 전체를 새 데이터로 바꿉니다.   |
| 추가    | 지난 실행 뒤 새로 생긴 행만 테이블에 더합니다. |

목적지 행을 펼치면 싱크마다 마지막 싱크 시각과 상태를 볼 수 있습니다.

## 목적지를 지울 때

목적지를 지워도 고객님 GCP 계정에 남은 설정은 라플라스가 지울 수 없습니다. 아래를 정리해 주세요.

1. 이 목적지에 쓰려고 서비스 계정에 주신 데이터셋 권한을 거두어 주세요. 다른 목적지가 같은 키를 쓰고 있다면 키는 그대로 두세요.
2. 데이터셋의 `laplace_data_sync` 라벨을 지워 주세요.

## FAQ

{% hint style="info" %}
**\[연결 확인] 이 실패해요.**

서비스 계정에 두 권한(프로젝트의 BigQuery 작업 사용자, 데이터셋의 BigQuery 데이터 편집자)이 있는지, 데이터셋 라벨의 키와 값이 화면에 나온 값과 같은지 확인해 주세요. 권한은 반영까지 몇 분 걸릴 수 있습니다.
{% endhint %}

{% hint style="info" %}
**\[새 키 만들기] 가 막혀 있거나 키를 만들 수 없다는 안내가 나와요.**

회사 GCP 조직에서 조직 정책으로 서비스 계정 키 생성을 막아 둔 경우입니다(`iam.disableServiceAccountKeyCreation`). 최근에 만든 조직은 이 정책이 기본으로 켜져 있습니다. 조직 정책 관리자에게 데이터를 받을 프로젝트에만 이 정책의 예외를 요청해 주세요. 예외 적용이 어렵다면 아래 문의처로 연락해 주세요.
{% endhint %}

## 전담 매니저에게 요청하기

BigQuery 연결에 어려움이 있으신가요?

하단의 문의하기 혹은 홈페이지의 채팅 상담을 통해 문의하세요. 담당 매니저가 도움을 드리도록 하겠습니다.

> 💬 [채팅으로 문의하기](https://laplacetec.channel.io/lounge)
>
> 💬 [홈페이지에서 문의하기](https://www.analytics.laplacetec.com/contact)

**이메일 문의:** [**product@laplacetec.com**](mailto:product@laplacetec.com)
