BigQuery에 Salesforce 데이터 로드
Salesforce용 BigQuery Data Transfer Service 커넥터를 사용하여 Salesforce Sales Account에서 BigQuery로 데이터를 로드할 수 있습니다. BigQuery Data Transfer Service를 사용하면 Salesforce Sales Account의 최신 데이터를 BigQuery에 추가하는 반복 전송 작업을 예약할 수 있습니다.
제한사항
Salesforce 데이터 전송에는 다음과 같은 제한사항이 적용됩니다.
- Salesforce 커넥터는 Salesforce Sales Account에서의 전송만 지원합니다.
- Salesforce 커넥터는 Salesforce Bulk API V1 버전 64.0에 포함된 필드만 지원합니다. 이전 버전의 Salesforce Bulk API에 포함된 일부 필드는 지원되지 않을 수 있습니다. Salesforce 커넥터의 이러한 변경사항에 대한 자세한 내용은 Salesforce Bulk API를 참고하세요.
- Salesforce 커넥터는 Salesforce Bulk API V1을 사용하여 Salesforce 엔드포인트에 연결하여 데이터를 가져옵니다.
- Salesforce 커넥터는 Salesforce Bulk API V1만 Salesforce 인스턴스에 연결할 수 있도록 지원하고 Salesforce Bulk API에서 지원하는 항목의 전송만 지원합니다. 지원되는 항목에 관한 자세한 내용은 'Entity is not supported by the Bulk API' error(엔티티가 Bulk API에서 지원되지 않음 오류)을 참고하세요.
- Salesforce 커넥터는 바이너리 필드가 있는 다음 객체의 전송을 지원하지 않습니다.
AttachmentContentVersionDocumentStaticResourceScontrolEmailCaptureMailMergeTemplate
- 반복 데이터 전송 사이의 최소 간격은 15분입니다. 반복 전송의 기본 간격은 24시간입니다.
- Salesforce 처리 한도로 인해 한 번에 너무 많은 데이터 전송을 예약하면 지연 또는 실패가 발생할 수 있습니다. Salesforce 데이터 전송을 다음으로 제한하는 것이 좋습니다.
- 전송 구성당 애셋은 10개 이하로 설정합니다.
- 다양한 전송 구성에서 한 번에 동시에 실행되는 전송이 10개를 초과해서는 안 됩니다.
- 단일 전송 구성은 지정된 시간에 하나의 데이터 전송 실행만 지원할 수 있습니다. 첫 번째 전송이 완료되기 전에 두 번째 데이터 전송이 실행되도록 예약된 경우 첫 번째 데이터 전송만 완료되고 첫 번째 전송과 겹치는 다른 데이터 전송은 건너뜁니다.
- 단일 전송 구성 내에서 전송이 건너뛰는 것을 방지하려면 반복 빈도를 구성하여 대량 데이터 전송 간의 시간을 늘리는 것이 좋습니다.
- 구성된 네트워크 연결과 가상 머신(VM) 인스턴스가 서로 다른 리전에 있는 경우 Salesforce에서 데이터를 전송할 때 리전 간 데이터 이동이 발생할 수 있습니다.
증분 전송 제한사항
증분 Salesforce 전송에는 다음과 같은 제한사항이 적용됩니다.- 워터마크 열로는
TIMESTAMP개의 열만 선택할 수 있습니다. - 증분 수집은 유효한 워터마크 열이 있는 애셋에 대해서만 지원됩니다.
- 워터마크 열의 값은 단조 증가해야 합니다.
- 증분 전송은 소스 테이블의 삭제 작업을 동기화할 수 없습니다.
- 단일 전송 구성은 증분 또는 전체 수집만 지원할 수 있습니다.
- 첫 번째 증분 수집 실행 후에는
asset목록의 객체를 업데이트할 수 없습니다. - 첫 번째 증분 수집이 실행된 후에는 전송 구성에서 쓰기 모드를 변경할 수 없습니다.
- 첫 번째 증분 수집이 실행된 후에는 워터마크 열이나 기본 키를 변경할 수 없습니다.
데이터 수집 옵션
다음 섹션에서는 Salesforce 데이터 전송을 설정할 때의 데이터 수집 옵션에 대해 자세히 설명합니다.
전체 또는 증분 전송
Salesforce 전송을 설정할 때 전송 구성에서 전체 또는 증분 쓰기 환경설정을 선택하여 데이터가 BigQuery에 로드되는 방법을 지정할 수 있습니다. 증분 전송은 미리보기에서 지원됩니다.
전체를 선택하면 각 데이터 전송 시 Salesforce 데이터 세트의 모든 데이터를 전송할 수 있습니다.또는 증분(미리보기)을 선택하여 각 데이터 전송 시 전체 데이터 세트를 로드하는 대신 마지막 데이터 전송 이후 변경된 데이터만 전송할 수 있습니다. 데이터 전송에 증분을 선택하는 경우 추가 또는 업서트 쓰기 모드를 지정하여 증분 데이터 전송 중에 BigQuery에 데이터를 쓰는 방법을 정의해야 합니다. 다음 섹션에서는 사용 가능한 쓰기 모드를 설명합니다.
추가 쓰기 모드
추가 쓰기 모드는 대상 테이블에 새 행만 삽입합니다. 이 옵션은 기존 레코드를 확인하지 않고 전송된 데이터를 엄격하게 추가하므로 이 모드는 대상 테이블에서 데이터 중복을 유발할 수 있습니다.
추가 모드를 선택한 경우 워터마크 열을 선택해야 합니다. Salesforce 커넥터가 소스 테이블의 변경사항을 추적하려면 워터마크 열이 필요합니다.
Salesforce 전송의 경우 레코드가 생성될 때만 업데이트되고 후속 업데이트로 변경되지 않는 열을 선택하는 것이 좋습니다. 예를 들어CreatedDate 열을 사용할 수 있습니다.
Upsert 쓰기 모드
Upsert 쓰기 모드는 기본 키를 확인하여 대상 테이블에서 행을 업데이트하거나 새 행을 삽입합니다. Salesforce 커넥터가 소스 테이블에 맞춰 대상 테이블을 최신 상태로 유지하는 데 필요한 변경사항을 결정하도록 기본 키를 지정할 수 있습니다. 데이터 전송 중에 지정된 기본 키가 대상 BigQuery 테이블에 있으면 Salesforce 커넥터가 소스 테이블의 새 데이터로 해당 행을 업데이트합니다. 데이터 전송 중에 기본 키가 없으면 Salesforce 커넥터가 새 행을 삽입합니다.
삽입/업데이트(upsert) 모드를 선택하는 경우 워터마크 열과 기본 키를 선택해야 합니다.
- Salesforce 커넥터가 소스 테이블의 변경사항을 추적하려면 워터마크 열이 필요합니다.
- 행이 수정될 때마다 업데이트되는 워터마크 열을 선택합니다.
SystemModstamp또는LastModifiedDate열을 사용하는 것이 좋습니다.
- 행이 수정될 때마다 업데이트되는 워터마크 열을 선택합니다.
- 기본 키는 Salesforce 커넥터가 행을 삽입해야 하는지 업데이트해야 하는지 판단하는 데 필요한 테이블의 하나 이상의 열일 수 있습니다.
- 테이블의 모든 행에서 고유한 null이 아닌 값이 포함된 열을 선택합니다. 시스템 생성 식별자, 고유 참조 코드 (예: 자동 증분 ID) 또는 불변 시간 기반 시퀀스 ID가 포함된 열을 사용하는 것이 좋습니다.
- 데이터 손실이나 데이터 손상을 방지하려면 선택한 기본 키 열에 고유한 값이 있어야 합니다. 선택한 기본 키 열의 고유성에 의문이 있는 경우 추가 쓰기 모드를 대신 사용하는 것이 좋습니다.
시작하기 전에
다음 섹션에서는 Salesforce 데이터 전송을 만들기 전에 취해야 할 조치에 대해 설명합니다.
Salesforce Connected App 만들기
다음과 같은 필수 구성으로 Salesforce Connected App을 만들어야 합니다.
- Connected App에서 기본 정보를 구성합니다. Salesforce를 이전하려면 Connected App 이름 및 연락처 이메일 필드가 필요합니다.
- 다음 구성으로 OAuth 설정 사용을 사용 설정합니다.
- OAuth 설정 사용 설정 체크박스를 선택합니다.
- 콜백 URL 필드에 다음을 입력합니다.
- 프로덕션 환경의 경우
https://login.salesforce.com/services/oauth2/token을 입력합니다. - 샌드박스 환경의 경우
https://test.salesforce.com/services/oauth2/token을 입력합니다.
- 프로덕션 환경의 경우
- 명명된 사용자에 대해 JSON 웹 토큰(JWT) 기반 액세스 토큰 발급 체크박스가 선택되어 있지 않은지 확인합니다.
- 선택한 OAuth 범위 섹션에서 API를 통해 사용자 데이터 관리(api)를 선택합니다.
- 지원되는 승인 흐름에 필요한 코드 교환용 증명 키(PKCE) 확장 프로그램 체크박스를 선택 해제합니다.
- 클라이언트 사용자 인증 정보 흐름 사용 설정을 선택한 다음 표시되는 알림에서 확인을 클릭합니다.
필요한 구성으로 Connected App을 구성했으면 저장을 클릭합니다. 새로 만든 Connected App의 세부정보 페이지로 리디렉션됩니다.
Connected App을 만든 후에는 다음을 실행하여 클라이언트 사용자 인증 정보 흐름도 구성해야 합니다.
- 설정을 클릭합니다.
- 검색창에서 Connected App을 검색합니다.
- 앱 관리 > Connected App을 클릭합니다. Salesforce Lightning Experience를 사용하는 경우 Connected App 관리를 클릭합니다.
- 만든 Connected App에서 수정을 클릭합니다.
- 앱 세부정보 페이지가 표시됩니다. 클라이언트 사용자 인증 정보 흐름 섹션의 다음 계정으로 실행 필드에 사용자 이름을 입력합니다. 이 필드의 찾기 도구를 사용하여 올바른 사용자를 선택했는지 확인할 수 있습니다.
- 저장을 클릭합니다.
필수 Salesforce 정보
Salesforce 데이터 전송을 만들 때 다음 Salesforce 정보가 있어야 합니다.
| 매개변수 이름 | 설명 |
|---|---|
myDomain |
Salesforce의 내 도메인 |
clientId |
Salesforce Connected App의 고객 키 |
clientSecret |
Salesforce Connected App의 OAuth 클라이언트 보안 비밀번호 또는 고객 보안 비밀 |
myDomain, clientID, clientSecret 값을 가져오려면 다음 옵션 중 하나를 선택하세요.
Salesforce Classic
myDomain 세부정보 가져오기
myDomain을 찾으려면 다음 단계를 따르세요.
- Salesforce 플랫폼에 로그인합니다.
- 설정을 클릭합니다.
- 검색창에서 내 도메인을 검색합니다.
- 검색 결과에서 도메인 관리 > 내 도메인을 클릭합니다.
내 도메인 세부정보 섹션의 현재 내 도메인 URL에 myDomain이 접두어로 표시됩니다. 예를 들어 내 도메인 URL이 example.my.salesforce.com이면 사용할 myDomain 값은 example입니다.
ClientId 및 ClientSecret 세부정보 가져오기
ClientId 및 ClientSecret 값을 찾으려면 다음 단계를 따르세요.
- Salesforce 플랫폼에 로그인합니다.
- 설정을 클릭합니다.
- 검색 창에서 Apps를 검색합니다.
- 검색 결과의 빌드 섹션에서 만들기 > 앱을 클릭합니다.
- Connected App 이름을 클릭합니다.
- Connected App 세부정보 페이지에서 소비자 세부정보 관리를 클릭합니다.
- 등록된 방법 중 하나를 사용하여 본인 인증을 합니다. 본인 인증을 다시 요청받기 전까지 최대 5분 동안 소비자 세부정보 페이지를 볼 수 있습니다.
- 소비자 세부정보 페이지에서 소비자 키는
ClientId값입니다. 고객 보안 비밀은ClientSecret값입니다.
Salesforce Lightning 환경
myDomain 세부정보 가져오기
myDomain을 찾으려면 다음 단계를 따르세요.
- Salesforce 플랫폼에 로그인합니다.
- 설정을 클릭합니다.
- 검색창에서 내 도메인을 검색합니다.
- 검색 결과에서 회사 설정 > 내 도메인을 클릭합니다.
내 도메인 세부정보 섹션의 현재 내 도메인 URL에 myDomain이 접두어로 표시됩니다. 예를 들어 내 도메인 URL이 example.my.salesforce.com이면 사용할 myDomain 값은 example입니다.
ClientId 및 ClientSecret 세부정보 가져오기
- Salesforce 플랫폼에 로그인합니다.
- 설정을 클릭합니다.
- 검색 창에서 Apps를 검색합니다.
- 검색 결과에서 앱 > 앱 관리자를 클릭합니다.
- 연결된 앱을 찾은 다음 보기를 클릭합니다.
- 소비자 세부정보 관리를 클릭합니다.
- 등록된 방법 중 하나를 사용하여 본인 인증을 합니다. 본인 인증을 다시 요청받기 전까지 최대 5분 동안 소비자 세부정보 페이지를 볼 수 있습니다.
- 소비자 세부정보 페이지에서 소비자 키는
ClientId값입니다. 고객 보안 비밀은ClientSecret값입니다.
Salesforce 전송을 위한 IP 허용 목록 설정
데이터 전송을 위한 허용 목록에 특정 IP 주소를 추가하려면 Google Cloud 환경과 Salesforce 계정을 구성해야 합니다. 이렇게 하면 Salesforce가 신뢰할 수 있는 고정 IP 주소의 연결만 허용합니다.
이렇게 하려면 먼저 고정 IP 주소를 사용하도록 Google Cloud 네트워크를 설정하고 구성해야 합니다.
- 가상 프라이빗 클라우드 네트워크 내에서 고정 IP 주소를 사용하여 공용 네트워크 주소 변환(NAT)을 설정합니다. CloudNAT는 이 데이터 전송의 대상 데이터 세트와 동일한 리전 내에서 구성해야 합니다.
- 동일한 VPC 네트워크 내에서 네트워크 연결을 설정합니다. 이 리소스는 BigQuery Data Transfer Service에서 비공개 서비스에 액세스하는 데 사용됩니다.
다음으로 Salesforce에서 신뢰할 수 있는 IP 범위를 구성해야 합니다. IP 주소 범위를 추가할 때는 IP 범위의 시작 및 종료 IP 주소 모두에Google Cloud 공개 NAT의 고정 IP 주소를 사용하세요.
IP 범위를 설정한 후 네트워크 연결 필드에서 네트워크 연결을 선택하여 전송 구성을 설정할 때 고정 IP를 지정할 수 있습니다.
BigQuery 기본 요건
- BigQuery Data Transfer Service 사용 설정에 필요한 모든 작업을 완료했는지 확인합니다.
- 데이터를 저장할 BigQuery 데이터세트를 만듭니다.
- Pub/Sub의 전송 실행 알림을 설정하려면
pubsub.topics.setIamPolicyIdentity and Access Management(IAM) 권한이 있는지 확인합니다. 이메일 알림만 설정한다면 Pub/Sub 권한이 필요하지 않습니다. 자세한 내용은 BigQuery Data Transfer Service 실행 알림을 참조하세요.
필요한 BigQuery 역할
BigQuery 데이터 전송 서비스 데이터 전송을 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 BigQuery 관리자 (roles/bigquery.admin) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
이 사전 정의된 역할에는 BigQuery Data Transfer Service 데이터 전송을 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
BigQuery Data Transfer Service 데이터 전송을 만들려면 다음 권한이 필요합니다.
-
BigQuery Data Transfer Service 권한:
-
bigquery.transfers.update -
bigquery.transfers.get
-
-
BigQuery 권한:
-
bigquery.datasets.get -
bigquery.datasets.getIamPolicy -
bigquery.datasets.update -
bigquery.datasets.setIamPolicy -
bigquery.jobs.create
-
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
자세한 내용은 bigquery.admin 액세스 권한 부여를 참고하세요.
Salesforce 데이터 전송 설정
다음 옵션 중 하나를 사용하여 전송 구성을 설정하여 BigQuery에 Salesforce 데이터를 추가합니다.
콘솔
Google Cloud 콘솔에서 데이터 전송 페이지로 이동합니다.
전송 만들기를 클릭합니다.
소스 유형 섹션의 소스에서 Salesforce를 선택합니다.
데이터 소스 세부정보 섹션에서 다음을 수행합니다.
- 네트워크 연결에서 목록에서 네트워크 연결을 선택합니다. 자세한 내용은 Salesforce 전송을 위한 IP 허용 목록 설정을 참고하세요.
- 내 도메인에 Salesforce 내 도메인을 입력합니다.
- 클라이언트 ID에 Salesforce 연결 애플리케이션 고객 키를 입력합니다.
- 클라이언트 보안 비밀번호에 Salesforce 연결 애플리케이션 고객 보안 비밀을 입력합니다.
- 수집 유형에서 전체 또는 증분을 선택합니다.
- 증분(프리뷰)을 선택한 경우 쓰기 모드에서 추가 또는 삽입/업데이트(upsert)를 선택합니다. 다양한 쓰기 모드에 관한 자세한 내용은 전체 또는 증분 전송을 참고하세요.
- 전송할 Salesforce 객체에서 찾아보기를 클릭합니다.
- BigQuery 대상 데이터 세트로 전송할 객체를 선택합니다. 데이터 전송에 포함할 객체를 이 필드에 직접 입력할 수도 있습니다.
- 증분 쓰기 모드로 추가를 선택한 경우 열을 워터마크 열로 선택해야 합니다.
- 삽입/업데이트(upsert)를 증분 쓰기 모드로 선택한 경우 열을 워터마크 열로 선택한 다음 하나 이상의 열을 기본 키로 선택해야 합니다.
대상 설정 섹션의 데이터 세트에서 데이터를 저장하기 위해 만든 데이터 세트를 선택합니다.
전송 구성 이름 섹션의 표시 이름에 데이터 전송 이름을 입력합니다.
일정 옵션 섹션에서 다음을 수행합니다.
- 반복 빈도 목록에서 이 데이터 전송 실행 빈도를 지정하는 옵션을 선택합니다. 커스텀 반복 빈도를 지정하려면 커스텀을 선택합니다. 주문형을 선택한 경우 수동으로 전송을 트리거하면 이 전송이 실행됩니다.
- 해당하는 경우 지금 시작 또는 설정 시간에 시작을 선택하고 시작 날짜와 실행 시간을 입력합니다.
선택사항: 알림 옵션 섹션에서 다음을 수행합니다.
- 이메일 알림을 사용 설정하려면 이메일 알림 전환 버튼을 클릭합니다. 이 옵션을 사용 설정하면 전송 실행이 실패할 때 전송 관리자에게 이메일 알림이 발송됩니다.
- 이 전송에 Pub/Sub 전송 실행 알림을 사용 설정하려면 Pub/Sub 알림 전환 버튼을 클릭합니다. 주제 이름을 선택하거나 주제 만들기를 클릭하여 주제를 만들 수 있습니다.
저장을 클릭합니다.
bq
bq mk 명령어를 입력하고 전송 생성 플래그 --transfer_config를 지정합니다.
bq mk --transfer_config --project_id=PROJECT_ID --data_source=DATA_SOURCE --display_name=NAME --target_dataset=DATASET --params='PARAMETERS'
각 항목의 의미는 다음과 같습니다.
- PROJECT_ID(선택사항): Google Cloud 프로젝트 ID.
특정 프로젝트를 지정하는
--project_id가 입력되지 않으면 기본 프로젝트가 사용됩니다. - DATA_SOURCE: 데이터 소스 —
salesforce - NAME: 데이터 전송 구성의 표시 이름. 전송 이름은 나중에 수정해야 할 경우를 대비해 간편하게 전송을 식별할 수 있는 값이면 됩니다.
- DATASET. 전송 구성의 대상 데이터 세트
PARAMETERS: JSON 형식으로 생성된 전송 구성의 매개변수. 예를 들면
--params='{"param":"param_value"}'입니다. Salesforce 데이터 전송에 대한 매개변수는 다음과 같습니다.connector.authentication.oauth.clientId: Salesforce 연결 애플리케이션의 고객 키connector.authentication.oauth.clientSecret: Salesforce 연결 애플리케이션의 OAuth 클라이언트 보안 비밀번호 또는 고객 보안 비밀connector.authentication.oauth.myDomain: Salesforce 내 도메인. 예를 들어 도메인 URL이example.my.salesforce.com이면 값은example입니다.ingestionType:FULL또는INCREMENTAL을 지정합니다. 증분 전송은 미리보기에서 지원됩니다. 자세한 내용은 전체 또는 증분 전송을 참고하세요.writeMode:WRITE_MODE_APPEND또는WRITE_MODE_UPSERT을 지정합니다.watermarkColumns: 테이블의 열을 워터마크 열로 지정합니다. 이 필드는 증분 전송에 필요합니다.primaryKeys: 테이블의 열을 기본 키로 지정합니다. 이 필드는 증분 전송에 필요합니다.assets: BigQuery로 전송할 Salesforce 객체의 경로.
증분 전송 중에 여러 애셋을 지정할 때 watermarkColumns 및 primaryKeys 필드의 값은 assets 필드의 값 위치에 해당합니다. 다음 예시에서 Id은 Account 테이블에 해당하고 master_label 및 type은 CaseHistory 테이블에 해당합니다.
"primaryKeys":[['Id'], ['master_label','type']], "assets":["Account","CaseHistory"],
다음 명령어는 기본 프로젝트에 증분 Salesforce 데이터 전송을 만들고 APPEND 쓰기 모드를 사용합니다.
bq mk --transfer_config --target_dataset=mydataset --data_source=salesforce --display_name='My Transfer' --params='{"assets": ["Account", "CaseHistory"] "connector.authentication.oauth.clientId": "1234567890", "connector.authentication.oauth.clientSecret":"ABC12345", "connector.authentication.oauth.myDomain":"MyDomainName", "connector.authentication.username":"user1@force.com", "connector.authentication.password":"abcdef1234", "ingestionType":"incremental", "writeMode":"WRITE_MODE_UPSERT", "watermarkColumns":["SystemModstamp","CreatedDate"] "primaryKeys":[['Id'], ['master_label','type']]}'
API
projects.locations.transferConfigs.create 메서드를 사용하고 TransferConfig 리소스의 인스턴스를 지정합니다.
정기 일정 외에 데이터 전송을 수동으로 실행하려면 백필 실행을 시작하면 됩니다.
데이터 유형 매핑
다음 표는 Salesforce 데이터 유형을 해당하는 BigQuery 데이터 유형에 매핑합니다.
| Salesforce 데이터 유형 | BigQuery 데이터 유형 |
|---|---|
_bool |
BOOLEAN |
_int |
INTEGER |
_long |
INTEGER |
_double |
FLOAT |
currency |
FLOAT |
percent |
FLOAT |
geolocation (latitude) |
FLOAT |
geolocation (longitude) |
FLOAT |
date |
DATE |
datetime |
TIMESTAMP |
time |
TIME |
picklist |
STRING |
multipicklist |
STRING |
combobox |
STRING |
reference |
STRING |
base64 |
STRING |
textarea |
STRING |
phone |
STRING |
id |
STRING |
url |
STRING |
email |
STRING |
encryptedstring |
STRING |
datacategorygroupreference |
STRING |
location |
STRING |
address |
STRING |
anyType |
STRING |
가격 책정
Salesforce 전송 가격 정보는 Data Transfer Service 가격 책정을 참고하세요.
전송 설정 문제 해결
전송을 설정하는 데 문제가 있으면 Salesforce 데이터 전송 문제를 참조하세요.
다음 단계
- BigQuery Data Transfer Service 개요는 BigQuery Data Transfer Service 소개 참조하기
- 전송 구성 정보 가져오기, 전송 구성 나열, 전송 실행 기록 보기를 포함한 전송 사용에 대한 정보는 전송 작업 참조하기
- 교차 클라우드 작업으로 데이터를 로드하는 방법을 알아보기