베타HubSpot 데이터를 Microsoft Fabric으로 내보내기

참고: 슈퍼 관리자인 경우, 이 기능을 사용하려면 계정을Data Studio 베타 프로그램에 등록해야합니다.

Data Out을 사용하여 선택한 HubSpot CRM 데이터를 본인이 소유한 Microsoft Fabric Warehouse의 기본 테이블로 내보낼 수 있습니다. 개체, 연관 관계 및 이벤트 데이터를 웨어하우스의 테이블로 동기화한 다음, SQL을 사용하여 해당 데이터를 쿼리하거나 비즈니스 인텔리전스 및 분석 도구에서 활용할 수 있습니다.

동기화할 때마다 선택한 데이터의 전체 스냅샷이 생성됩니다. 동기화가 성공하면 대상 테이블의 이전 스냅샷이 대체됩니다.

시작하기 전에

요구 사항 파악

데이터를 Microsoft Fabric으로 내보내려면 다음이 필요합니다.

• Fabric Warehouse가 포함된 Microsoft Fabric 작업 공간
• Fabric 작업 공간에 '기여자(Contributor)' 역할로 추가된 Microsoft Entra ID 서비스 주체
• 서비스 주체의 테넌트 ID, 클라이언트 ID 및 클라이언트 시크릿
• Fabric 웨어하우스 SQL 연결 문자열(포트 번호를 제외한 서버 주소) 및 웨어하우스 이름

Microsoft Entra ID 서비스 주체는 대상 Fabric Warehouse에서 HubSpot 소유 개체를 생성하고 관리할 수 있는 권한이 있어야 합니다. 연결 유효성 검사 및 동기화 과정에서 HubSpot은 스키마와 테이블을 생성하고, 데이터를 삽입하며, 스테이징 테이블의 이름을 변경하고, 임시 개체를 제거합니다. HubSpot이 다음 작업을 수행할 수 있도록 Fabric 작업 공간에서 서비스 주체에게 '기여자(Contributor)' 역할을 부여하십시오:

• 스키마 생성
• 테이블 생성
• 행 삽입
• HubSpot 소유 테이블의 이름 변경 또는 수정
• HubSpot 소유 테이블 및 스키마 삭제

Fabric Warehouse의 SQL 엔드포인트는 HubSpot이 TCP 포트 1433을 통해 접근할 수 있어야 합니다. HubSpot은 모든 연결에 TLS를 사용하며 서버 인증서를 검증합니다.

Fabric 워크스페이스에서 네트워크 액세스를 제한하는 경우, 해당 계정 리전의 HubSpot 출구 IP 주소를 허용 목록에 추가하십시오.

제한 사항 및 고려 사항 이해

• Microsoft Fabric Data Out은 Fabric 웨어하우스만 지원합니다. 레이크하우스는 지원되지 않습니다.
• 동기화가 실행될 때마다 선택한 데이터의 전체 스냅샷이 생성됩니다. 동기화가 성공적으로 완료되면 대상 테이블의 이전 스냅샷이 대체됩니다. HubSpot은 이전 스냅샷을 보관하지 않습니다. 동기화 중에 테이블에 오류가 발생하면, 다음 동기화가 성공적으로 완료될 때까지 해당 테이블의 이전 데이터를 계속 사용할 수 있습니다.
• 계정당 하나의 반복 Microsoft Fabric 동기화에 각 개체 유형, 이벤트 유형 또는 연관 쌍을 포함할 수 있습니다.
• 각 동기화 작업은 대상 테이블을 덮어씁니다. Fabric Warehouse에 추가된 테이블 수준의 권한 또는 설정은 동기화 간에 유지되지 않습니다.
• 다른 서비스 주체로 다시 연결하려면, 연결 테스트나 동기화가 성공적으로 수행되기 전에 해당 서비스 주체를 ‘기여자(Contributor)’ 역할로 Fabric 작업 공간에 추가해야 합니다.

HubSpot을 Microsoft Fabric에 연결

HubSpot 계정과 Microsoft Fabric 콘솔을 별도의 탭에서 열어두는 것이 좋습니다.

1. HubSpot 계정에서 더 보기를 클릭한 다음 데이터 관리 > 데이터 스튜디오로 이동하세요. 더 보기가 계정에 표시되지 않으면 바로 데이터 관리 > 데이터 스튜디오로 이동하세요.
2. 오른쪽 상단에서 '외부 데이터 소스 연결'을 클릭합니다.
3. '데이터 소스 추가' 패널에서 Microsoft Fabric을 검색하거나 찾아갑니다.
4. '설치'를 클릭한 다음 '다음'을 클릭합니다.
5. 서비스 주체의 테넌트 ID, 클라이언트 ID 및 클라이언트 시크릿을 입력합니다.
6. 다음 대상 세부 정보를 입력합니다.
   • SQL 연결 문자열: 포트 번호를 제외한 Fabric Warehouse의 서버 주소.
   • 웨어하우스 이름: 내보낼 Fabric 웨어하우스의 이름입니다.
7. '연결 테스트'를 클릭하십시오. 연결 테스트가 성공하면 '다음'을 클릭하십시오.

참고: Fabric 작업 공간에서 연결 테스트를 실행하기 전에 HubSpot 서비스 주체가 ‘기여자(Contributor)’ 역할을 가지고 있는지 확인하십시오. 액세스 구성에 SQL 스크립트는 필요하지 않습니다.

동기화 구성

1. 내보낼 데이터 소스를 선택하십시오:
   • 개체
   • 연관 관계
   • 이벤트
2. 포함할 객체, 속성, 연관 관계 또는 이벤트를 선택하십시오.
3. 동기화를 실행할 빈도와 시작 시점을 선택합니다.
4. '동기화 시작'을 클릭하십시오.

베타 기간 동안 사용 가능한 동기화 빈도는 달라질 수 있습니다. 옵션으로는 1회, 6시간마다, 12시간마다, 매일, 매주 또는 매월이 있습니다.

내보낸 데이터에 액세스하기

HubSpot은 각 대상에 대해 HubSpot에서 관리하는 스키마를 생성합니다. 테이블은 다음 형식을 따릅니다:

<database>.hubspot_data_out_<destination-id>.<table-name>

예:

your_database.hubspot_data_out_456.OBJECT_WITH_OBJECT_PROPERTIES your_database.hubspot_data_out_456.EVENTS_VISITED_PAGE your_database.hubspot_data_out_456.ASSOCIATIONS_CONTACTS_TO_COMPANIES

정확한 스키마 이름은 동기화 설정 페이지에서 확인할 수 있습니다.

테이블 및 열 이름

HubSpot은 내보낸 테이블 및 열 이름을 대문자, 숫자, 밑줄로 정규화합니다:

• 공백과 하이픈은 밑줄로 바뀝니다.
• 그 외의 영숫자가 아닌 문자는 제거됩니다.
• 128자보다 긴 이름은 축약됩니다.
• 중복되는 열 이름에는 접미사가 추가됩니다.
• 중복되는 테이블 이름은 해당 내보내기가 실패합니다.

열 유형

PROPERTIES 테이블의 OBJECT_WITH_OBJECT_PROPERTIES 열은 네이티브 JSON 열 유형이 아닌 VARCHAR(MAX) 형식의 JSON 문자열로 저장됩니다. 아래 FAQ의 쿼리 예시를 참조하십시오.

객체 테이블

객체 데이터를 선택하면 HubSpot은 다음 테이블을 내보냅니다.

OBJECT_PROPERTIES

이 테이블에는 각 객체 속성 값마다 하나의 행이 포함됩니다.

OBJECT_WITH_OBJECT_PROPERTIES

이 테이블에는 각 객체 레코드마다 한 행이 포함됩니다. 선택된 속성 값은 PROPERTIES 열에 그룹화되어 있습니다.

이 테이블에는 서로 다른 객체 유형의 객체 데이터가 통합되어 있습니다. 특정 객체 유형의 레코드를 확인하려면 OBJECTTYPEID 필터링하십시오:

• 연락처: 0-1
• 사용자 정의 개체: 2-{unique_id}, 예: 2-12345

OBJECT_PROPERTIES_HISTORY

이 테이블에는 속성 변경 내역이 포함되어 있습니다. 속성의 각 과거 값마다 한 행씩 포함됩니다.

특정 레코드 및 속성에 대한 전체 내역을 보려면 결과를 UPDATEDAT 기준으로 정렬하십시오.

연관 테이블

연관 데이터를 선택하면 HubSpot은 연관 레코드와 연관 정의를 내보냅니다.

ASSOCIATIONS

이 테이블에는 두 레코드 간의 선택된 연관 관계마다 한 행이 포함됩니다.

ASSOCIATION_DEFINITIONS

이 테이블에는 선택된 각 연관 관계 정의에 대해 한 행씩 포함됩니다.

쌍별 연관 관계 테이블

선택된 연관성 쌍에 대해 HubSpot은 다음 형식의 테이블도 내보낼 수 있습니다.

ASSOCIATIONS_<FROM_OBJECT_TYPE>_TO_<TO_OBJECT_TYPE>

예: ASSOCIATIONS_CONTACTS_TO_COMPANIES

이 테이블에는 연관 기록과 연관 정의 메타데이터가 포함되어 있습니다.

이벤트 테이블

이벤트 데이터를 선택하면 HubSpot은 이벤트 유형별로 하나의 테이블을 내보냅니다. 이벤트 테이블 이름은 다음 형식을 따릅니다:

EVENTS_<EVENT_NAME>

예: EVENTS_VISITED_PAGE

각 이벤트 테이블에는 표준 이벤트 열과 선택한 각 이벤트 속성에 대한 열 하나씩이 포함됩니다.

동기화 상태 모니터링

1. HubSpot 계정에서 더 보기를 클릭한 다음 데이터 관리 > 데이터 스튜디오로 이동하세요. 더 보기가 계정에 표시되지 않으면 바로 데이터 관리 > 데이터 스튜디오로 이동하세요.
2. 왼쪽에서 '앱 동기화'를 클릭합니다.
3. Microsoft Fabric 동기화를 검색하거나 선택합니다.

동기화 세부 정보 페이지에서 동기화 상태, 마지막 동기화 시간, 오류, 동기화 활동 및 동기화 내역을 확인할 수 있습니다. 또한 동기화를 일시 중지하거나, 보관하거나, 수동으로 실행할 수도 있습니다.

동기화 상태

동기화 실패 해결

동기화가 실패할 경우:

• HubSpot UI에는 '실패' 상태가 표시되며, 어떤 테이블이 성공했는지 또는 실패했는지를 나타내는 테이블 수준의 세부 정보가 표시됩니다.
• 테이블은 HubSpot이 해당 테이블의 모든 데이터 로딩을 완료한 후에만 업데이트됩니다. 테이블 동기화가 실패하면, 다음 동기화가 성공적으로 완료될 때까지 이전 데이터가 그대로 유지됩니다.
• 다음 예약된 동기화 시점에 전체 동기화가 자동으로 다시 시도됩니다.
• 동기화 세부 정보 페이지에서 수동으로 동기화를 실행할 수 있습니다.

자주 묻는 질문

내보낸 데이터를 어떻게 쿼리하나요?

SQL을 사용하여 대상 스키마의 테이블을 쿼리하십시오.

-- Read all contact records
SELECT *
FROM [your_database].[hubspot_data_out_456].[OBJECT_WITH_OBJECT_PROPERTIES]
WHERE [OBJECTTYPEID] = '0-1'; -- Read a specific property from the PROPERTIES JSON string
SELECT
  [OBJECTID],
  JSON_VALUE([PROPERTIES], '$.email') AS [email]
FROM [your_database].[hubspot_data_out_456].[OBJECT_WITH_OBJECT_PROPERTIES]
WHERE [OBJECTTYPEID] = '0-1';

하나의 데이터 유형을 여러 동기화 작업에 포함시킬 수 있나요?

HubSpot 계정당 각 객체 유형, 이벤트 유형 또는 연관 쌍은 하나의 반복 Microsoft Fabric 동기화에 포함될 수 있습니다. 이는 다른 Data Out 제공자와는 별개입니다.

예를 들어, 연락처가 이미 반복적인 Fabric 대상에 내보내진 경우, 첫 번째 구성을 보관 처리하기 전까지는 다른 반복적인 Fabric 구성에 연락처를 추가할 수 없습니다. 하지만 동시에 지원되는 다른 Data Out 제공업체로 연락처를 내보내는 것은 가능합니다.

개체별 테이블이 지원되나요?

OBJECTS_CONTACTS 같은 개체별 테이블은 현재 지원되지 않습니다. OBJECT_WITH_OBJECT_PROPERTIES 사용하고 OBJECTTYPEID 필터링하여 특정 개체 유형의 레코드를 가져오십시오.

민감 정보는 지원되나요?

현재 Data Out에서는 민감한 데이터가 지원되지 않습니다. 내보내기 시 민감한 속성을 제외할 수 있습니다.

HubSpot은 이전 스냅샷을 보관하나요?

아니요. 동기화가 성공할 때마다 대상 테이블이 최신 스냅샷으로 대체됩니다. HubSpot은 이전 스냅샷을 보관하지 않습니다. 동기화 중에 테이블에 오류가 발생하면, 해당 테이블이 성공적으로 업데이트될 때까지 이전 데이터가 그대로 유지됩니다.

HubSpot은 제가 관리하는 스테이징 버킷을 사용하나요?

아니요. HubSpot은 HubSpot이 관리하는 스토리지에 임시 Parquet 내보내기 파일을 생성하고, 그 결과를 귀하의 Fabric Warehouse에 기록합니다. 스테이징 버킷을 제공하거나 관리할 필요가 없습니다.

다른 서비스 주체로 다시 연결하면 어떻게 되나요?

다른 서비스 주체를 사용하여 다시 연결하는 경우, 연결 테스트나 동기화가 성공하려면 해당 서비스 주체를 Fabric 워크스페이스에 ‘기여자(Contributor)’ 역할로 추가해야 합니다.