베타HubSpot 데이터를 PostgreSQL 또는 MySQL로 내보내기

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

요약

Data Out을 사용하여 선택한 HubSpot CRM 데이터를 귀하가 관리하는 PostgreSQL 또는 MySQL 데이터베이스로 내보낼 수 있습니다. 개체, 연관 관계 및 이벤트 데이터를 데이터베이스의 테이블로 동기화한 다음, SQL을 사용하여 데이터를 쿼리하거나 비즈니스 인텔리전스 및 분석 도구에서 활용할 수 있습니다.

각 동기화 작업은 선택한 데이터의 전체 스냅샷을 생성합니다. 동기화가 성공하면 대상 테이블의 이전 스냅샷이 대체됩니다.

시작하기 전에

필수 사항 확인

• PostgreSQL 또는 MySQL 데이터베이스는 계정 지역별 HubSpot IP 범위에서 접근 가능해야 합니다.
• 데이터베이스 서버는 SSL 연결을 지원해야 합니다.
• 필요한 권한을 가진 데이터베이스 사용자가 있어야 합니다.
  • PostgreSQL: CREATE 권한 및 대상 스키마에 대한 쓰기 권한.
  • MySQL: 데이터베이스에 대한 CREATE 권한 및 쓰기 권한.
• 데이터베이스 사용자가 테이블을 생성하고 데이터를 쓸 수 있는지 확인하십시오.
• HubSpot 계정과 데이터베이스 콘솔을 별도의 탭에서 열어 두십시오.

HubSpot IP 주소 허용

계정 지역별 HubSpot IP 범위를 데이터베이스 서버의 허용 목록에 추가하십시오.

제한 사항 및 고려 사항 파악

• 동기화가 실행될 때마다 선택한 데이터의 전체 스냅샷이 생성됩니다.
• 동기화가 성공적으로 완료되면 대상 테이블의 이전 스냅샷이 대체됩니다.
• HubSpot은 이전 스냅샷을 보관하지 않습니다.
• 동기화 중에 테이블에 오류가 발생하면, 다음 동기화가 성공적으로 완료될 때까지 해당 테이블의 이전 데이터는 계속 사용할 수 있습니다.
• 각 객체 유형, 이벤트 유형 또는 연관 쌍은 계정당 하나의 반복 PostgreSQL 동기화 및 하나의 반복 MySQL 동기화에 포함될 수 있습니다.
• 각 동기화는 대상 테이블을 대체합니다. 데이터베이스 공급자에서 추가된 테이블 수준의 권한 또는 설정은 동기화 사이에 유지되지 않습니다.
• 다른 데이터베이스 사용자로 다시 연결하는 경우, 해당 사용자에게 기존 HubSpot 관리 스키마, 데이터베이스 또는 테이블에 대한 액세스 권한을 부여해야 합니다.

HubSpot을 PostgreSQL 또는 MySQL에 연결

1. HubSpot 계정에서 더 보기를 클릭한 다음 데이터 관리 > 데이터 스튜디오로 이동하세요. 더 보기가 계정에 표시되지 않으면 바로 데이터 관리 > 데이터 스튜디오로 이동하세요.
2. 오른쪽 상단에서 ‘외부 데이터 소스 연결’을 클릭합니다.
3. '데이터 소스 추가' 패널에서 데이터베이스 공급자를 검색하거나 찾아갑니다.
4. 'PostgreSQL ' 또는 'MySQL'을 클릭합니다.
5. 데이터베이스 연결 정보를 입력합니다:
   • 호스트
   • 포트
   • SSL
   • 사용자 이름
   • 비밀번호
6. PostgreSQL의 경우, HubSpot이 스키마를 생성할 데이터베이스 이름을 입력하세요.
7. 'PostgreSQL에 연결 ' 또는 'MySQL에 연결'을 클릭합니다.

HubSpot은 연결된 데이터베이스 사용자를 사용하여 테이블을 생성하고 데이터베이스에 데이터를 로드합니다.

동기화 구성

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

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

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

HubSpot은 각 대상에 대해 HubSpot에서 관리하는 스키마 또는 데이터베이스를 생성합니다.

PostgreSQL

PostgreSQL 테이블은 다음 형식을 사용합니다:

<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"

MySQL

MySQL 테이블은 다음 형식을 사용합니다:

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

예를 들어:

hubspot_data_out_456.OBJECT_WITH_OBJECT_PROPERTIES
hubspot_data_out_456.EVENTS_VISITED_PAGE
hubspot_data_out_456.ASSOCIATIONS_CONTACTS_TO_COMPANIES

정확한 스키마 또는 데이터베이스 이름은 동기화 구성 페이지에서 확인할 수 있습니다.

테이블 및 열 이름

테이블 및 열 이름은 내보낸 데이터를 기반으로 합니다. PostgreSQL 식별자는 최대 63자까지 포함할 수 있습니다. MySQL 식별자는 최대 64자까지 포함할 수 있습니다. 이보다 긴 이름은 해당 제한에 맞도록 축약됩니다.

HubSpot은 따옴표로 묶고 대소문자를 그대로 유지한 이름으로 PostgreSQL 테이블과 열을 생성합니다. PostgreSQL을 쿼리할 때는 큰따옴표를 사용하고, 테이블 이름 및 열 이름에 표시된 대소문자 구분을 정확히 따라야 합니다.

MySQL의 경우 백틱을 사용하고 표시된 대소문자 구분을 준수하십시오. 테이블 이름의 대소문자 구분 여부는 MySQL 서버 구성에 따라 달라질 수 있습니다.

열 유형

PROPERTIES 테이블의 OBJECT_WITH_OBJECT_PROPERTIES 열은 JSON 형식의 문자열로 저장됩니다. 이 열은 PostgreSQL에서는 TEXT, MySQL에서는 LONGTEXT 저장되며, 네이티브 JSON 열 유형으로 저장되지는 않습니다.

객체 테이블

객체 데이터를 선택하면 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. PostgreSQL 또는 MySQL 동기화를 검색하거나 선택합니다.

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

동기화 상태

동기화 실패 해결

동기화가 실패할 경우:

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

이전 실행에서 정상적으로 동기화된 테이블은 이후 실행이 실패하더라도 수정되지 않습니다.

자주 묻는 질문

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

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

PostgreSQL

-- Read all contact records
SELECT *
FROM your_database.hubspot_data_out_456."OBJECT_WITH_OBJECT_PROPERTIES"
WHERE "OBJECTTYPEID" = '0-1';

-- Read a property from the PROPERTIES column
SELECT
  "OBJECTID",
  json_extract_path_text("PROPERTIES"::json, 'email') AS email
FROM your_database.hubspot_data_out_456."OBJECT_WITH_OBJECT_PROPERTIES"
WHERE "OBJECTTYPEID" = '0-1';

MySQL

-- Read all contact records
SELECT *
FROM `hubspot_data_out_456`.`OBJECT_WITH_OBJECT_PROPERTIES`
WHERE `OBJECTTYPEID` = '0-1';

-- Read a property from the PROPERTIES column
SELECT
  `OBJECTID`,
  JSON_EXTRACT(`PROPERTIES`, '$.email') AS email
FROM `hubspot_data_out_456`.`OBJECT_WITH_OBJECT_PROPERTIES`
WHERE `OBJECTTYPEID` = '0-1';

하나의 데이터 유형을 여러 번의 동기화에서 내보낼 수 있나요?

HubSpot 계정당 각 개체 유형, 이벤트 유형 또는 연관 쌍은 하나의 반복 PostgreSQL 동기화와 하나의 반복 MySQL 동기화에 포함될 수 있습니다.

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

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

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

민감 데이터가 지원되나요?

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

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

아니요. 동기화가 성공할 때마다 대상 테이블이 최신 스냅샷으로 대체됩니다. HubSpot은 이전 스냅샷을 보관하지 않습니다.

동기화 중에 테이블에 오류가 발생하면, 해당 테이블이 성공적으로 업데이트될 때까지 이전 데이터가 그대로 유지됩니다.

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

아니요. HubSpot은 데이터를 Parquet 형식으로 내보내며 스테이징을 내부적으로 관리합니다. PostgreSQL 또는 MySQL용으로 고객이 소유한 스테이징 버킷을 제공할 필요가 없습니다.

데이터베이스 사용자를 변경하면 어떻게 되나요?

다른 데이터베이스 사용자를 사용하여 다시 연결하는 경우, 새로운 사용자에게 기존 HubSpot 관리 스키마, 데이터베이스 또는 테이블에 대한 액세스 권한을 부여해야 합니다.