BigQuery: 행 삽입

BigQuery: 행 삽입을 사용하여 스트리밍 삽입 API를 통해 Journey 단계에서 BigQuery 테이블로 한 행을 스트리밍합니다. Google Sheets: 행 추가와 마찬가지로, 이 지점은 전체 계정에 대해 한 번 연결된 Google 계정을 통해 인증합니다. 지점 자체에는 토큰 필드가 없습니다.

일반적인 사용 사례:

• 보고 테이블 피드: 도달한 Journey 단계마다 행을 삽입하여 다운스트림의 대시보드 또는 예약된 쿼리에 사용합니다.
• 이벤트 발생 시 기록: 일괄 내보내기를 기다리는 대신 원시 Journey 데이터를 BigQuery로 스트리밍합니다.
• 기존 데이터와 조인: BigQuery 테이블이 자체 데이터 세트와 조인할 수 있는 기기 또는 태그 값을 삽입합니다.

시작하기 전에

설정 > 타사 통합 > Google에서 Google 계정을 연결합니다. 이는 Google Sheets: 행 추가에서 사용하는 것과 동일한 연결입니다. Google을 연결한 후, 통합을 설치하여 Journey 빌더에 지점이 나타나도록 합니다.

이는 해당 페이지의 Google BigQuery 카드가 아닙니다. 그것은 BigQuery 통합으로, 애플리케이션의 모든 메시지 이벤트를 서비스 계정 키의 고정된 스키마로 스트리밍합니다. 이 지점은 사용자가 정의한 한 행을 배치한 단계에서 작성하며 자체 키를 사용하지 않습니다.

주의

BigQuery 지원이 추가되기 전에 Google을 연결했다면 한 번 다시 연결하십시오. 연결은 부여된 권한을 유지하므로, 이전 연결은 Sheets에는 쓸 수 있지만 BigQuery에는 쓸 수 없어 지점이 403 오류로 실패할 수 있습니다.

Google Cloud 측에서도 두 가지가 준비되어 있어야 요청이 실패하지 않습니다:

• 데이터 세트와 테이블이 이미 존재해야 합니다. 이 지점은 행을 작성합니다. 테이블을 생성하지는 않습니다.
• 연결된 Google 계정에는 해당 데이터 세트에 대한 BigQuery 데이터 편집자 역할(또는 bigquery.tables.updateData 권한을 부여하는 모든 역할)이 필요합니다.

지점 구성

1. 왼쪽 패널의 통합 섹션에서 BigQuery: 행 삽입을 캔버스로 드래그합니다.
2. 지점을 더블 클릭하고 단계 이름을 입력합니다.
3. 프로젝트 ID에 Google Cloud 프로젝트 ID를 입력합니다. 표시 이름이 아닌 ID를 사용하십시오(예: my-analytics-prod).

4. 데이터 세트에 데이터 세트 이름을 입력합니다.

5. 테이블에 테이블 이름을 입력합니다.

6. 열에서 작성할 BigQuery 열마다 한 행씩 추가합니다. 열 이름과 값을 입력합니다. 이름은 비어 있지 않고 고유해야 합니다. 나열하는 모든 열은 테이블의 스키마에 존재해야 합니다. 값은 고정된 텍스트이거나 웹훅 본문과 동일한 매크로인 {{tag:Name}}과 같은 트래블러 매크로일 수 있습니다. 또는 동적 값 삽입을 클릭하여 이 Journey의 이전 단계에서 생성된 속성(예: LLM 응답 또는 매핑된 웹훅 값)을 선택합니다.

예시

데이터 세트를 marketing으로, 테이블을 journey_events로 설정하고, 열을 트래블러의 기기 ID({{device:hwid}})와 함께 device_id로 설정하면 해당 테이블의 device_id 열에 행이 작성됩니다.

7. 저장을 클릭합니다.

응답

트래블러는 캔버스에서 다음에 연결하는 단계로 계속 진행합니다.

단계 실행 후 속성

이 지점은 성공 시 속성을 반환하지 않습니다. BigQuery가 행을 거부하면 대신 bigquery_insert_error에 오류가 기록됩니다. 실패 및 예기치 않은 응답을 참조하십시오.

실패 및 예기치 않은 응답

지점의 창에서 호출 로그를 열고 응답을 확인하십시오:

• 401 — Google 연결이 없거나 만료되었습니다. 설정 > 타사 통합에서 다시 연결하십시오.
• accessDenied: Streaming insert is not allowed in the free tier가 포함된 403 — 프로젝트에 결제 계정이 연결되어 있지 않습니다. 이 지점이 사용하는 스트리밍 삽입은 BigQuery 샌드박스에 포함되지 않습니다. 프로젝트에서 결제를 활성화하면 동일한 요청이 처리됩니다.
• accessDenied 또는 insufficientPermissions가 포함된 403 — BigQuery 지원이 추가되기 전에 연결이 승인되었거나(다시 연결하십시오), Google 계정에 데이터 세트에 대한 쓰기 권한이 없습니다.
• quotaExceeded 또는 rateLimitExceeded가 포함된 403 — 프로젝트의 스트리밍 삽입 할당량이 소진되었습니다. 다시 연결할 필요가 없습니다. Journey가 더 적게 보내거나 Google Cloud에서 할당량을 늘려야 합니다.
• 404 — 프로젝트, 데이터 세트 또는 테이블 이름이 아무것과도 일치하지 않습니다.

주의

BigQuery가 거부하는 행(알 수 없는 열 또는 열 유형에 맞지 않는 값)은 오류 상태가 아닌 insertErrors 본문이 포함된 200으로 반환됩니다. 트래블러는 쓰기가 성공한 것처럼 계속 진행합니다. 첫 번째 이러한 메시지는 bigquery_insert_error 트래블러 속성에 기록됩니다. 조건 분기에서 직접 분기할 수 없으므로, 먼저 사용자 프로필 업데이트를 사용하여 태그에 저장한 다음, 조건 분기를 사용하여 해당 태그에서 분기하십시오. 전체 본문은 호출 로그에 있습니다.

실패한 요청은 Journey에서 트래블러를 제외시킵니다. 오류 및 실패한 요청을 참조하십시오.

예시 시나리오: BigQuery 보고 테이블 피드하기

한 팀이 예약된 보고서가 이미 쿼리하는 동일한 BigQuery 데이터 세트에 Journey 활동을 포함시키고자 합니다.

1. 기록하려는 단계 바로 뒤에 BigQuery: 행 삽입을 추가합니다. 데이터 세트를 marketing으로, 테이블을 journey_events로 설정합니다. 열에서 device_id를 {{device:hwid}}로 설정합니다.
2. 저장을 클릭합니다.

이것이 실행되면, 행은 예약된 쿼리가 읽는 동일한 테이블에 저장되므로 다음 보고서 실행에 이미 포함됩니다.