Salesforce Bulk API용 Openflow 커넥터: 구성

이 문서에서는 Salesforce Bulk API용 Openflow 커넥터를 구성하는 단계를 설명합니다.

출처: Snowflake 문서

본문

커넥터 설치

Openflow 런타임에 Salesforce Bulk API용 Openflow 커넥터를 설치하려면 다음 단계를 따르세요.

Openflow의 Connector library 탭으로 이동하세요.
Openflow connectors 페이지에서 Salesforce Bulk API용 Openflow 커넥터를 찾아 Install을 선택하세요.
Select runtime 대화상자의 Available runtimes 드롭다운에서 런타임을 선택하세요.
커넥터 프로세스 그룹이 추가된 Openflow 캔버스가 나타납니다.

커넥터 구성

커넥터를 구성하려면 다음 단계를 수행하세요.

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

파라미터	설명
Column Removal Strategy	최신 수신 스키마에 따라 목적지 테이블에서 열을 제거해야 할 때 채택할 전략 정의. 세 가지 가능한 값: Drop Column, Rename Column, Ignore Column. Drop Column: Snowflake 테이블에서 열 삭제. Rename Column: Snowflake 테이블에서 열 이름 변경. Ignore Column: 열을 무시하고 Snowflake 테이블에 그대로 둠
Connected App Key	Salesforce와의 JWT Bearer Flow 인증에 사용되는 개인 키. Salesforce 설정 중 생성된 private.key 파일의 내용을 복사해 붙여넣기. 이 개인 키는 Salesforce의 외부 클라이언트 앱에 업로드된 공개 인증서(public.crt)와 일치해야 함. 대신 다음 파라미터로 개인 키 파일을 업로드할 수도 있음
Connected App Key File	Reference asset 체크박스를 선택해 private.key 파일을 업로드한 뒤, 자산으로 업로드하고 파라미터 값으로 선택. 이는 Connected App Key 파라미터에 키 내용을 붙여넣는 대안
Connected App Key Password	Salesforce 설정 단계에서 개인 키 파일에 설정한 비밀번호
Destination Database	Salesforce 데이터가 복제될 Snowflake의 데이터베이스 이름. 커넥터를 시작하기 전에 데이터베이스가 존재해야 함
Destination Schema	위 데이터베이스에서 커넥터가 Salesforce 데이터를 추가할 테이블을 만들 스키마 이름. 커넥터를 시작하기 전에 스키마가 존재해야 함
Enable Capture Blob Fields	true로 설정하면 base64 유형 필드(Attachment.Body, ContentVersion.VersionData 같은 바이너리 필드)를 커넥터가 가져옴. blob 필드를 포함한 객체는 Special Objects Filter 파라미터(Non-Bulk API 경로)에 나열되어야 함. 기본: false. 자세한 내용은 'Configure blob field ingestion' 참조
Enable Journal Tables	true로 설정하면 SystemModstamp 또는 LastModifiedDate 필드가 있는 각 동기화 객체에 대해 JOURNAL_
Enable Merge Metrics	true로 설정하면 커넥터가 복제 중 추가·업데이트·삭제·복원된 레코드 수를 세는 추가 쿼리를 실행함. 추가 쿼리는 Snowflake Warehouse를 사용하며 IsDeleted 필드를 포함한 객체에만 적용됨. 커넥터는 횟수를 이벤트 테이블의 로그에 기록함. 기본: false. 'Monitor the Openflow Connector for Salesforce Bulk API' 참조
Enable Views Creation	true로 설정하면 공식 필드를 포함한 각 동기화 객체에 대해
Filter	Salesforce에서 복제할 객체의 쉼표로 구분된 목록, 또는 모든 기존 객체에 적용할 정규식. 필터는 대소문자를 구분하지 않으므로 account로 설정해도 Account 객체 유형과 일치함. 예: Account, Opportunity, Contact. 참고: 비워 두면 모든 객체가 복제됨. Salesforce 인스턴스에는 보통 수천 개의 객체가 있으므로 권장하지 않음
Incremental Offload	프로세서가 증분 오프로드를 수행할지 여부. true이면 프로세서는 적절한 타임스탬프 필드에 WHERE 절을 사용해 마지막 쿼리 작업 제출 이후 수정된 레코드만 가져옴. false이면 커넥터가 실행될 때마다 모든 레코드를 가져옴
Initial Load Chunking	NONE 이외의 값으로 설정하면 초기 데이터 로드가 이 간격에 따라 여러 작업으로 나뉨. 객체의 첫 실행에서 커넥터는 Salesforce를 쿼리해 가장 오래된 레코드를 찾아 시작점으로 사용함. 각 후속 작업은 현재 시각을 따라잡을 때까지 다음 시간 청크를 쿼리함. NONE, MONTHLY, QUARTERLY, YEARLY 중 하나로 설정. 모든 과거 데이터를 단일 쿼리로 로드하면 시간 초과, API 한도 초과, 런타임의 콘텐츠 저장소 스토리지 크기 초과가 발생할 수 있는 큰 데이터셋에 유용. 따라잡은 뒤 프로세서는 정상 증분 오프로드 동작을 계속함
Iceberg Version	Table Storage Format이 ICEBERG(preview)로 설정된 경우에만 적용. 목적지 Iceberg 테이블의 Iceberg 버전 지정. 지원 값: 2와 3. 기본: 3. 수집 시작 후 이 값을 변경하지 마세요. 설정 지침은 'Openflow Connector for Salesforce Bulk API: Iceberg table destinations' 참조
OAuth2 Audience	JWT 토큰에 설정할 audience. 프로덕션 환경은 https://login.salesforce.com, 샌드박스·테스트 환경은 https://test.salesforce.com으로 설정
OAuth2 Client ID	Salesforce Setup 단계에서 검색된 Consumer Key 값으로 설정해야 함
OAuth2 Subject	애플리케이션이 Salesforce API와 상호작용하는 대신으로 하는, 관리자 승인 사용자의 사용자 이름으로 설정해야 함
OAuth2 Token Endpoint URL	JWT Bearer Flow로 토큰을 협상하는 엔드포인트. 예: https://myCompany.my.salesforce.com/services/oauth2/token
Object Fields Filter JSON	Salesforce 객체별로 포함·제외할 필드와 필드 패턴을 지정하는 JSON. 객체당 하나의 항목이 있는 배열 형태. 예시 1: 'Account' 객체에서 'name'으로 끝나는 모든 필드 포함: [ {"objectType":"Account", "includedPattern":".*name"} ]. 예시 2: 'Account' 객체에서 Id, Name, Revenue 필드 포함: [ {"objectType":"Account", "included": ["Id", "Name", "Revenue"]} ]. excluded와 excludedPattern도 필터 구성에 사용 가능
Object Identifier Resolution	스키마/테이블/열 이름을 대소문자 구분 또는 대소문자 구분 없이 취급할지 결정. CASE_INSENSITIVE / CASE_SENSITIVE 중 하나. 참고: 이 파라미터 값을 변경하려면 상태를 지우고 모든 객체를 전체 재로드해야 함
Removed Column Name Suffix	Column Removal Strategy 파라미터가 Rename Column으로 설정될 때 열 이름에 추가되는 접미사. 기본: __deleted
Run Schedule	Filter 파라미터로 구성된 객체에 대해 커넥터가 Salesforce의 업데이트를 확인하는 빈도. 기본: 15분
Salesforce Instance	도메인 이름을 포함한 Salesforce 인스턴스의 호스트 이름. 프로토콜 접두사(https://)는 포함하지 마세요. 예: myCompany.my.salesforce.com
Snowflake Account Identifier	데이터가 저장될 [organization-name]-[account-name] 형식의 Snowflake 계정 이름. 예: PM-CONNECTORS
Snowflake Username	커넥터가 Snowflake에 연결하는 데 사용하는 서비스 사용자 이름. 서비스 사용자는 KEY_PAIR 인증 전략(Openflow BYOC 전용)을 사용할 때만 필요
Snowflake Private Key	커넥터가 Snowflake에 인증하는 데 사용하는 RSA 개인 키. PKCS8 표준에 따라 형식화되고 표준 PEM 헤더와 푸터를 포함. 헤더 줄은 -----BEGIN PRIVATE로 시작. KEY_PAIR 인증 전략(Openflow BYOC 전용)을 사용할 때만 필요. 다음 파라미터로 개인 키를 Openflow 런타임에 업로드할 수도 있음
Snowflake Private Key File	커넥터가 Snowflake에 인증하는 데 사용하는 RSA 개인 키가 담긴 파일. PKCS8 표준에 따라 형식화되고 표준 PEM 헤더와 푸터를 포함. 헤더 줄은 -----BEGIN PRIVATE로 시작. KEY_PAIR 인증 전략(Openflow BYOC 전용)을 사용할 때만 필요. Reference asset 체크박스를 선택해 개인 키 파일을 업로드하고 Openflow 런타임에 안전하게 저장
Snowflake Private Key Password	Snowflake Private Key File과 연결된 비밀번호(암호화된 경우). KEY_PAIR 인증 전략(Openflow BYOC 전용)을 사용할 때만 필요
Snowflake Role	쿼리 실행 중 사용되는 execute-as 역할의 이름. SNOWFLAKE_MANAGED 사용 시 Openflow 런타임의 execute-as 역할. KEY_PAIR 사용 시(Openflow BYOC 전용) 지정된 Snowflake 사용자 이름에 할당된 역할
Snowflake Authentication Strategy	커넥터가 Snowflake에 연결하는 인증 전략. SNOWFLAKE_MANAGED(기본) 사용 시 런타임의 execute-as 역할과 연결된 Snowflake 관리형 토큰을 사용. Openflow BYOC를 사용하면 KEY_PAIR를 사용해 사용자 지정 키 페어로 특정 사용자와 역할을 지정할 수도 있음
Snowflake Warehouse	쿼리를 실행하는 데 사용되는 Snowflake 웨어하우스
Special Objects Filter	Salesforce에서 오프로드할 객체의 쉼표로 구분된 목록(직접 API 접근 사용), 또는 모든 기존 객체에 적용할 정규식. 필터는 대소문자를 구분하지 않으므로 account로 설정해도 Account 객체 유형과 일치함. 이 필터는 Knowledge 데이터처럼 Salesforce Bulk API가 지원하지 않는 객체에만 사용해야 함. 이 파라미터는 Filter 파라미터와 겹치면 안 됨. 예: Knowledge.*
Table Storage Format	목적지 Snowflake 테이블의 스토리지 형식. 표준 Snowflake 테이블에는 STANDARD 사용. Apache Iceberg 테이블에 쓰는 ICEBERG 옵션은 preview 기능. 기본: STANDARD. 수집 시작 후 이 값을 변경하지 마세요. 설정 지침은 'Openflow Connector for Salesforce Bulk API: Iceberg table destinations' 참조

Salesforce 연결 확인

커넥터를 활성화하고 시작하기 전에 Snowflake는 Salesforce 인증이 올바르게 구성되었는지 확인할 것을 권장합니다. 컨트롤러 서비스의 Verification 기능을 사용하면 전체 커넥터 플로우를 시작하지 않고 연결을 테스트할 수 있습니다.

JWT Bearer OAuth2 Access Token Provider 컨트롤러 서비스는 먼저 활성화해야 하는 두 개의 다른 컨트롤러 서비스(Salesforce Private Key Service와 Web Client Service Provider)에 의존합니다.

커넥터 프로세스 그룹을 더블 클릭해 엽니다.
캔버스의 빈 영역을 마우스 오른쪽 버튼으로 클릭하고 Controller Services를 선택합니다.
Salesforce Private Key Service와 Web Client Service Provider 서비스를 활성화합니다.
목록에서 JWT Bearer OAuth2 Access Token Provider 서비스를 찾습니다.
해당 서비스의 Verification 버튼을 클릭합니다. 속성 재정의를 제공할 수 있는 대화상자가 열립니다. 무시하고 바로 Verify를 클릭할 수 있습니다.
모든 것이 올바르게 구성되었다면 Acquire token 단계가 성공을 나타내는 녹색 체크 표시를 보여줍니다. 이는 커넥터가 Salesforce로 인증하고 액세스 토큰을 얻을 수 있음을 확인합니다. 다음 단계로 진행해 커넥터를 실행할 수 있습니다.
검증이 실패하면 오류 메시지를 검토하고 다음을 확인하세요.
- OAuth2 Client ID 파라미터가 Salesforce의 외부 클라이언트 앱의 Consumer Key와 일치.
- 개인 키가 외부 클라이언트 앱에 업로드된 인증서와 대응.
- OAuth2 Subject 사용자가 외부 클라이언트 앱에 대해 승인되었는지.
- OAuth2 Token Endpoint URL이 올바른 Salesforce 인스턴스 호스트 이름을 사용.
- OAuth2 Audience가 올바른 값으로 설정: 프로덕션은 https://login.salesforce.com, 샌드박스는 https://test.salesforce.com.

자세한 문제 해결은 'Troubleshooting the Openflow Connector for Salesforce Bulk API'를 참조하세요.

커넥터 실행

다음 단계에 따라 커넥터를 시작하고 Salesforce에서 Snowflake로 데이터 복제를 시작하세요.

캔버스의 빈 영역을 마우스 오른쪽 버튼으로 클릭하고 Enable all Controller Services를 선택합니다.
커넥터 프로세스 그룹을 마우스 오른쪽 버튼으로 클릭하고 Start를 선택합니다.

객체 복제 관리

커넥터가 시작되고 객체가 복제된 뒤에는 복제에 새 객체를 추가하거나 기존 객체를 제거할 수 있습니다.

복제에 새 객체 추가

복제에 새 객체를 추가하려면 새 객체 이름으로 Filter 파라미터(또는 해당하면 Special Objects Filter 파라미터)를 업데이트하세요. 커넥터를 중지할 필요는 없습니다. 새 객체는 다음 예약 실행에 복제됩니다.

예를 들어 현재 Filter 값이 Account, Opportunity이고 Contact 객체를 추가하려면 값을 Account, Opportunity, Contact로 변경하세요.

복제에서 객체 제거

복제에서 객체를 제거하려면 커넥터를 중지하고 커넥터 상태와 Snowflake의 목적지 테이블을 모두 정리해야 합니다.

커넥터 프로세스 그룹을 마우스 오른쪽 버튼으로 클릭하고 Stop을 선택해 플로우의 모든 프로세서를 중지합니다.
진행 중인 FlowFile이 처리되고 있지 않은지 확인합니다.
캔버스를 마우스 오른쪽 버튼으로 클릭하고 Parameters를 선택한 뒤 Filter 파라미터(또는 해당하면 Special Objects Filter 파라미터)에서 객체 이름을 제거합니다.
캔버스를 마우스 오른쪽 버튼으로 클릭하고 Disable all controller services를 선택합니다.
Controller services로 이동해 Salesforce Bulk Jobs State라는 컨트롤러 서비스의 상태를 엽니다.
제거한 객체 유형 옆의 휴지통 아이콘을 선택해 상태 항목을 삭제합니다.
캔버스를 마우스 오른쪽 버튼으로 클릭하고 Enable all controller services를 선택한 뒤 모든 프로세서를 시작해 커넥터를 재개합니다.
해당하면 이전에 복제된 데이터를 정리하기 위해 Snowflake 목적지 데이터베이스에서 해당 테이블을 삭제합니다. 예:

DROP TABLE <database_name>.<schema_name>.<object_name>;

blob 필드 수집 구성

Salesforce Bulk API 2.0은 바이너리(base64 인코딩) 필드를 지원하지 않습니다. 커넥터는 Salesforce REST Query API를 사용하는 전용 Non-Bulk API 경로를 통해 이러한 필드를 처리합니다. blob 필드가 있는 객체는 이 경로로 라우팅되도록 Special Objects Filter 파라미터에 나열되어야 합니다.

blob 필드 수집을 활성화하려면 커넥터 파라미터에서 Enable Capture Blob Fields를 true로 설정하세요.

다음 단계

복제 활동과 병합 메트릭을 모니터링하려면 'Monitor the Openflow Connector for Salesforce Bulk API'를 참조하세요.
커넥터 문제를 진단하려면 'Troubleshooting the Openflow Connector for Salesforce Bulk API'를 참조하세요.

Salesforce Bulk API용 Openflow 커넥터: 구성