HubSpot용 Openflow 커넥터 설정

이 주제는 Openflow Connector for HubSpot을 설정하는 단계를 설명해요.

출처: Snowflake 문서

본문

참고: 이 커넥터는 Snowflake Connector Terms가 적용돼요.

이 주제는 Openflow Connector for HubSpot을 설정하는 단계를 설명해요.

전제 조건(Prerequisites)

About Openflow Connector for HubSpot을 검토했는지 확인해요.
Set up Openflow - Snowflake Deployments 또는 Set up Openflow - BYOC를 설정했는지 확인해요.
Openflow - Snowflake Deployments를 사용한다면 configuring required domains을 검토하고, Hubspot 커넥터에 필요한 도메인에 대한 액세스를 부여했는지 확인해요.

자격 증명 가져오기

HubSpot 관리자로서 HubSpot private app 토큰을 생성하거나 HubSpot 계정에서 만들어요. 이렇게 하면 HubSpot API에 대한 요청을 인증할 수 있어요.

HubSpot 계정에 로그인해요.
상단 내비게이션 바의 기어 아이콘을 선택해 Settings로 이동해요.
왼쪽 내비게이션에서 Integrations » Private Apps로 이동해요.
Create a private app을 선택해요.
앱 이름을 입력해요.
Scopes 탭으로 이동해요.
만들려는 API 요청에 필요한 스코프를 선택해요. API 요청에 필요한 스코프를 찾으려면 Scopes를 참고해요.
Create app을 선택해요.
각 엔드포인트에 대해 만들려는 API 요청에 필요한 스코프를 설정해요.
View access token을 선택해 액세스 토큰을 봐요. 토큰을 커넥터 파라미터에 붙여넣거나 안전하게 저장해요.

Snowflake 계정 설정하기

Openflow 관리자로서 Snowflake 계정을 설정하려면 다음 작업을 수행해요. 기본 SNOWFLAKE_MANAGED 인증 전략을 사용하면 런타임의 execute-as 역할이 커넥터가 Snowflake에 접근할 때 사용하는 신원이 되므로, 그 역할에 다음 권한을 부여해요.

참고: Openflow - BYOC Deployments에 커넥터를 배포하고 권장하는 SNOWFLAKE_MANAGED 대신 KEY_PAIR 인증 전략을 사용한다면, 런타임의 관리 토큰에 의존하는 대신 이 같은 execute-as 역할을 서비스 사용자에게 부여해요. 서비스 사용자를 만들려면 Set up key-pair authentication for Openflow - BYOC Deployments을 참고해요.

데이터베이스, 스키마, 웨어하우스 만들기

대상 데이터베이스를 만들어요:

USE ROLE OPENFLOW_ADMIN;
CREATE DATABASE IF NOT EXISTS <destination_database>;

대상 스키마를 만들어요:

CREATE SCHEMA IF NOT EXISTS <destination_database>.<destination_schema>;

런타임의 execute-as 역할에 필요한 권한을 부여해요:

GRANT USAGE ON DATABASE <destination_database> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;
GRANT USAGE ON SCHEMA <destination_database>.<destination_schema> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;
GRANT CREATE TABLE, CREATE VIEW ON SCHEMA <destination_database>.<destination_schema> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;

웨어하우스를 만들거나(기존 것을 사용하거나) 사용 권한을 부여해요:

CREATE WAREHOUSE IF NOT EXISTS <openflow_warehouse>
  WITH
  WAREHOUSE_SIZE = 'XSMALL'
  AUTO_SUSPEND = 300
  AUTO_RESUME = TRUE;

GRANT USAGE, OPERATE ON WAREHOUSE <openflow_warehouse> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;

커넥터가 수집한 테이블과 뷰에 액세스가 필요한 다른 Snowflake 사용자가 있다면(예: Snowflake에서 커스텀 처리), 그 사용자에게 execute-as 역할을 부여해요.

커넥터 설정하기

데이터 엔지니어로서 커넥터를 설치하고 구성하려면 다음 작업을 수행해요:

커넥터 설치하기

데이터 엔지니어로서 커넥터를 설치하려면:

Openflow의 Connector library 탭으로 이동해요.
Openflow 커넥터 페이지에서 커넥터를 찾고 Install을 선택해요.
Select runtime 대화상자에서 Available runtimes 드롭다운 목록에서 런타임을 선택하고 Install을 클릭해요.

참고: 커넥터를 설치하기 전에, 수집된 데이터를 저장할 Snowflake에 데이터베이스와 스키마를 만들었는지 확인해요.

Snowflake 계정 자격 증명으로 배포에 인증하고, 런타임 애플리케이션이 Snowflake 계정에 접근하는 것을 허용하라는 프롬프트가 나오면 Allow를 선택해요. 커넥터 설치 과정은 완료되는 데 몇 분이 걸려요.
Snowflake 계정 자격 증명으로 런타임에 인증해요. Openflow 캔버스에 커넥터 프로세스 그룹이 추가된 상태로 나타나요.

커넥터 구성하기

가져온 프로세스 그룹을 마우스 오른쪽 버튼으로 클릭하고 Parameters를 선택해요.
Flow parameters에 설명된 대로 필수 파라미터 값을 채워요.

Flow parameters

이 섹션은 다음 파라미터 컨텍스트에 따라 구성할 수 있는 플로우 파라미터를 설명해요:

HubSpot Source Parameters: HubSpot과의 연결을 설정하는 데 사용
HubSpot Destination Parameters: Snowflake와의 연결을 설정하는 데 사용
HubSpot Ingestion Parameters: HubSpot에서 다운로드한 데이터의 구성을 정의하는 데 사용

HubSpot Source Parameters

파라미터	설명
HubSpot Access Token	HubSpot Private Application 액세스 토큰

HubSpot Destination Parameters

파라미터	설명	필수
Destination Database	데이터가 저장될 데이터베이스. Snowflake에 이미 존재해야 함. 이름은 대소문자를 구분함. 인용되지 않은 식별자는 대문자로 제공	예
Destination Schema	데이터가 저장될 스키마. Snowflake에 이미 존재해야 함. 이름은 대소문자를 구분함. 인용되지 않은 식별자는 대문자로 제공. 예: `CREATE SCHEMA SCHEMA_NAME` 또는 `CREATE SCHEMA schema_name`: `SCHEMA_NAME` 사용. `CREATE SCHEMA "schema_name"` 또는 `CREATE SCHEMA "SCHEMA_NAME"`: 각각 `schema_name` 또는 `SCHEMA_NAME` 사용	예
Snowflake Authentication Strategy	다음 중 하나: Snowflake Openflow Deployment 또는 BYOC: SNOWFLAKE_MANAGED 사용(이 토큰은 Snowflake가 자동 관리함). BYOC 배포는 SNOWFLAKE_MANAGED를 사용하려면 이전에 execute-as roles을 구성해야 함. BYOC: 대안으로 BYOC는 인증 전략 값으로 KEY_PAIR를 사용할 수 있음	예
Snowflake Account Identifier	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 비어 있어야 함. KEY_PAIR: [organization-name]-[account-name] 형식의 Snowflake 계정 이름	예
Snowflake Private Key	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 비어 있어야 함. KEY_PAIR: PKCS8 표준에 따라 형식화되고 표준 PEM 헤더·푸터를 포함하는 인증용 RSA 개인 키. Snowflake Private Key File 또는 Snowflake Private Key 중 하나는 정의해야 함	아니요
Snowflake Private Key File	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 개인 키 파일은 비어 있어야 함. KEY_PAIR: PKCS8 표준에 따라 형식화되고 표준 PEM 헤더·푸터를 포함하는 인증용 RSA 개인 키가 들어 있는 파일을 업로드. 헤더 줄은 `-----BEGIN PRIVATE`로 시작함. Reference asset 체크박스를 선택해 개인 키 파일을 업로드	아니요
Snowflake Private Key Password	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 비어 있어야 함. KEY_PAIR: Snowflake 개인 키 파일과 연결된 비밀번호 제공	아니요
Snowflake Role	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 런타임의 execute-as 역할(또는 그 역할에 부여된 하위 역할) 사용. execute-as 역할은 Openflow UI에서 런타임의 View Details로 이동해 찾을 수 있음. KEY_PAIR: 서비스 사용자에 대해 구성된 유효한 역할 사용	예
Snowflake Username	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 비어 있어야 함. KEY_PAIR: Snowflake 인스턴스에 연결하는 데 사용되는 사용자 이름 제공	예
Snowflake Warehouse	쿼리를 실행하는 데 사용되는 Snowflake 웨어하우스	예

HubSpot Ingestion Parameters

파라미터	설명
Object Types	수집할 쉼표로 구분된 HubSpot 객체 타입 목록. 지원되는 객체 타입 값: Appointments, Calls, Campaigns, Carts, Commerce Payments, Communications, Companies, Contacts, Courses, Deals, Discounts, Emails, Fees, Feedback Submissions, Goals, Invoices, Leads, Line Items, Listings, Meetings, Notes, Orders, Postal Mail, Products, Quotes, Quote Templates, Services, Subscriptions, Tasks, Taxes, Tickets, Users
Updated After	지정된 날짜 또는 시간 이후에 업데이트된 객체를 필터링함. 이 파라미터는 선택적임
Data Ingestion Schedule	다음 일정 사이의 시간. 30분 또는 1시간 같은 유효한 시간 지속 값이어야 함

플로우 실행하기

평면(plane)을 마우스 오른쪽 버튼으로 클릭하고 Enable all Controller Services를 선택해요.
가져온 프로세스 그룹을 마우스 오른쪽 버튼으로 클릭하고 Start를 선택해요. 커넥터가 데이터 수집을 시작해요.

커넥터 재구성하기

커넥터가 데이터 수집을 시작한 후에도 커넥터 파라미터를 수정할 수 있어요. 이슈 쿼리 기준이 변경되면 대상 테이블의 데이터가 일관되도록 다음 단계를 수행해요.

커넥터를 중지해요: 모든 Openflow 프로세서가 중지되었는지 확인해요.
구성 설정에 접근해요: Snowflake Openflow 인터페이스에서 커넥터의 구성 설정으로 이동해요.
파라미터 수정: 필요에 따라 파라미터를 조정해요.
프로세서 상태 지우기: 수집 기준을 변경하는 경우, 대상 테이블의 데이터를 일관되게 유지하려면 Snowflake는 처음부터 수집을 다시 시작할 것을 강력히 권장해요. List Fresh HubSpot Objects 프로세서의 상태를 지운 후 커넥터는 처음부터 모든 객체를 가져와요. 행 중복을 방지하려면 대상 테이블을 수동으로 truncate해야 할 수 있어요.

데이터 구조와 뷰

커넥터는 Snowflake 데이터베이스 안에서 다음 두 형식으로 데이터를 저장해요:

원시 데이터 저장

모든 원시 HubSpot 데이터는 Object Types 파라미터에 지정된 정확한 이름의 테이블에 저장돼요. 예를 들어:

Object Types 파라미터에 Products,Contacts,Companies를 구성하면 커넥터는 PRODUCTS, CONTACTS, COMPANIES 세 개의 테이블을 만들어요.
각 테이블은 HubSpot API 응답의 완전한 JSON 페이로드를 포함해요.
원시 데이터는 HubSpot의 원래 구조와 모든 메타데이터를 보존해요.

평탄화된 뷰(Flattened views)

더 쉬운 쿼리와 분석을 위해 커넥터는 각 객체 타입에 대해 평탄화된 뷰를 자동으로 만들어요:

각 원시 테이블에는 _VIEW 접미사가 붙은 해당 뷰가 있어요. 예: PRODUCTS_VIEW, CONTACTS_VIEW, COMPANIES_VIEW.
뷰는 JSON 페이로드에서 자주 사용되는 필드를 개별 컬럼으로 추출해요.
복잡한 중첩 구조는 단순화된 SQL 쿼리를 위해 평탄화돼요.

HubSpot용 Openflow 커넥터 설정