Azure Data Factory 또는 Azure Synapse Analytics를 사용하여 Salesforce 간에 데이터 복사(레거시)

아티클
05/11/2024

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

기업용 올인원 분석 솔루션인 Microsoft Fabric의 Data Factory를 사용해 보세요. Microsoft Fabric은 데이터 이동부터 데이터 과학, 실시간 분석, 비즈니스 인텔리전스 및 보고에 이르기까지 모든 것을 다룹니다. 무료로 새 평가판을 시작하는 방법을 알아봅니다!

이 문서에서는 Azure Data Factory 및 Azure Synapse 파이프라인의 복사 작업을 사용하여 Salesforce 간에 데이터를 복사하는 방법을 간략하게 설명합니다. 이 문서는 복사 작업에 대한 일반적인 개요를 제공하는 복사 작업 개요 문서를 기반으로 합니다.

Important

새로운 Salesforce 커넥터는 개선된 네이티브 Salesforce 지원을 제공합니다. 솔루션에서 레거시 Salesforce 커넥터를 사용하는 경우 2024년 10월 11일 이전에 Salesforce 커넥터를 업그레이드하세요. 레거시 버전과 최신 버전의 차이점에 대한 자세한 내용은 이 섹션을 참조하세요.

지원되는 기능

이 Salesforce 커넥터는 다음과 같은 기능에 대해 지원됩니다.

지원되는 기능	IR
복사 작업(원본/싱크)	3,4
조회 작업	3,4

① Azure 통합 런타임 ② 자체 호스팅 통합 런타임

원본 및 싱크로 지원되는 데이터 저장소의 목록은 지원되는 데이터 저장소 표를 참조하세요.

특히 이 Salesforce 커넥터는 다음을 지원합니다.

Salesforce 개발자, Professional, Enterprise 또는 Unlimited Edition.
Salesforce 프로덕션, 샌드박스 및 사용자 지정 도메인 간에 데이터 복사

참고 항목

이 함수는 NPSP(비영리 성공 팩)를 포함하여 위에서 언급한 Salesforce 환경의 모든 스키마 복사본을 지원합니다.

Salesforce 커넥터는 Salesforce REST/Bulk API 위에 빌드됩니다. Salesforce에서 데이터를 복사하는 경우 커넥터는 데이터 크기에 따라 REST 및 Bulk API 중에서 자동으로 선택합니다. 결과 집합이 클 경우 성능 향상을 위해 Bulk API가 사용됩니다. 연결된 서비스에서 apiVersion 속성을 통해 데이터 읽기/쓰기에 사용되는 API 버전을 명시적으로 설정할 수 있습니다. 데이터를 Salesforce에 복사할 때 커넥터는 BULK API v1을 사용합니다.

참고 항목

커넥터는 더 이상 Salesforce API의 기본 버전을 설정하지 않습니다. 이전 버전과의 호환성을 위해 기본 API 버전이 이전에 설정된 경우 해당 버전이 계속 작동합니다. 기본값은 원본의 경우 45.0이고 싱크의 경우 40.0입니다.

필수 조건

Salesforce에서 API 권한을 사용하도록 설정해야 합니다.

Salesforce 요청 제한

Salesforce에는 총 API 요청 수와 동시 API 요청 수에 대한 제한이 있습니다. 다음 사항에 유의하세요.

동시 요청 수가 이 제한을 초과하면 제한이 발생하며 임의 오류가 표시됩니다.
총 요청 수가 이 제한을 초과하면 Salesforce 계정은 24시간 동안 차단됩니다.

두 시나리오 모두에서 "REQUEST_LIMIT_EXCEEDED" 오류 메시지가 나타날 수 있습니다. 자세한 내용은 Salesforce 개발자 제한 문서의 "API 요청 제한" 섹션을 참조하세요.

시작하기

파이프라인에 복사 작업을 수행하려면 다음 도구 또는 SDK 중 하나를 사용하면 됩니다.

UI를 사용하여 Salesforce에 연결된 서비스 만들기

다음 단계를 사용하여 Azure Portal UI에서 Salesforce에 연결된 서비스를 만듭니다.

Azure Data Factory 또는 Synapse 작업 영역에서 관리 탭으로 이동하여 연결된 서비스를 선택하고 새로 만들기를 클릭합니다.
- Azure Data Factory
- Azure Synapse
Salesforce를 검색하고 Salesforce 커넥터를 선택합니다.
서비스 세부 정보를 구성하고, 연결을 테스트하고, 새로운 연결된 서비스를 만듭니다.

커넥터 구성 세부 정보

다음 섹션에서는 Salesforce 커넥터에 한정된 엔터티를 정의하는 데 사용되는 속성에 대해 자세히 설명합니다.

연결된 서비스 속성

Salesforce 연결된 서비스에 다음 속성이 지원됩니다.

속성	설명	필수
type	형식 속성은 Salesforce로 설정되어야 합니다.	예
environmentUrl	Salesforce 인스턴스의 URL을 지정합니다. - 기본값은 `"https://login.salesforce.com"`입니다. - 샌드박스에서 데이터를 복사하려면 `"https://test.salesforce.com"`을 지정합니다. - 사용자 지정 도메인에서 데이터를 복사하려면 예를 들어 `"https://[domain].my.salesforce.com"`을 지정합니다.	아니요
사용자 이름	사용자 계정의 사용자 이름을 지정합니다.	예
password	사용자 계정으로 password를 지정합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	예
securityToken	사용자 계정에 대한 보안 토큰을 지정합니다. 일반적인 보안 토큰에 대해 자세히 알아보려면 보안 및 API를 참조하세요. Salesforce의 신뢰할 수 있는 IP 주소 목록에 Integration Runtime의 IP를 추가하는 경우에만 보안 토큰을 건너뛸 수 있습니다. Azure IR을 사용하는 경우 Azure Integration Runtime IP 주소를 참조하세요. 보안 토큰을 가져오기 및 재설정하는 방법에 대한 자세한 내용은 보안 토큰 가져오기를 참조하세요. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	아니요
apiVersion	사용할 Salesforce REST/Bulk API 버전을 지정합니다. 예: `52.0`	아니요
connectVia	데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. 지정하지 않으면 기본 Azure Integration Runtime을 사용합니다.	아니요

예: 자격 증명 저장

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "username": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            },
            "securityToken": {
                "type": "SecureString",
                "value": "<security token>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

예: Key Vault에 자격 증명 저장

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "username": "<username>",
            "password": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of password in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "securityToken": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of security token in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

예: Key Vault에 자격 증명과 함께 EnvironmentUrl 및 사용자 이름을 저장합니다.

이렇게 하면 더 이상 UI를 사용하여 설정을 편집할 수 없습니다. JSON 형식으로 동적 콘텐츠 지정 확인란이 선택되어 있으며 이 구성을 모두 직접 편집해야 합니다. 장점은 여기서 매개 변수를 지정하는 대신 Key Vault에서 모든 구성 설정을 파생할 수 있다는 것입니다.

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "environmentUrl": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of environment URL in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "username": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of username in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "password": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of password in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "securityToken": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of security token in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

데이터 세트 속성

데이터 세트 정의에 사용할 수 있는 섹션 및 속성의 전체 목록은 데이터 세트 문서를 참조하세요. 이 섹션에서는 Salesforce 데이터 세트에서 지원하는 속성의 목록을 제공합니다.

Salesforce 간에 데이터를 복사하려면 데이터 세트의 형식 속성을 SalesforceObject로 설정합니다. 다음과 같은 속성이 지원됩니다.

속성	설명	필수
type	형식 속성은 SalesforceObject로 설정되어야 합니다.	예
objectApiName	데이터를 검색할 Salesforce 개체 이름입니다.	원본에는 아니요이고 싱크에는 예입니다

Important

모든 사용자 지정 개체에 대해 API 이름에 "__c" 부분이 필요합니다.

Salesforce 연결 API 이름을 보여 주는 스크린샷.

예제:

{
    "name": "SalesforceDataset",
    "properties": {
        "type": "SalesforceObject",
        "typeProperties": {
            "objectApiName": "MyTable__c"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Salesforce linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

참고 항목

이전 버전과의 호환성을 위해, Salesforce에서 데이터를 복사할 때 이전 "RelationalTable" 형식 데이터 세트를 사용할 경우 이 형식도 그대로 작동하지만 "SalesforceObject" 형식으로 전환하는 것이 좋습니다.

속성	설명	필수
type	데이터 세트의 type 속성을 RelationalTable로 설정해야 합니다.	예
tableName	Salesforce에 있는 테이블의 이름입니다.	아니요(작업 원본에서 "query"가 지정된 경우)

복사 작업 속성

작업 정의에 사용할 수 있는 섹션 및 속성의 전체 목록은 파이프라인 문서를 참조하세요. 이 섹션에서는 Salesforce 원본 및 싱크에서 지원하는 속성의 목록을 제공합니다.

Salesforce를 원본 형식으로

Salesforce에서 데이터를 복사하려면 복사 작업의 원본 형식을 SalesforceSource로 설정합니다. 복사 작업 원본 섹션에서 지원되는 속성은 다음과 같습니다.

속성	설명	필수
type	복사 작업 원본의 형식 속성을 SalesforceSource로 설정해야 합니다.	예
query	사용자 지정 쿼리를 사용하여 데이터를 읽습니다. SOQL(Salesforce Object Query Language) 쿼리 또는 SQL-92 쿼리를 사용할 수 있습니다. 쿼리 팁 섹션에서 더 많은 팁을 참조하세요. 쿼리를 지정하지 않으면 데이터 세트의 “objectApiName”에 지정된 Salesforce 개체의 모든 데이터가 검색됩니다.	아니요(데이터 세트의 “objectApiName”이 지정된 경우)
readBehavior	기존 레코드를 쿼리할지, 아니면 삭제된 항목을 포함하여 모든 레코드를 쿼리할지 여부를 나타냅니다. 지정하지 않으면 기본 동작은 전자입니다. 허용되는 값: query(기본값), queryAll입니다.	아니요

Important

모든 사용자 지정 개체에 대해 API 이름에 "__c" 부분이 필요합니다.

Salesforce 연결 API 이름 목록을 보여 주는 스크린샷.

예제:

"activities":[
    {
        "name": "CopyFromSalesforce",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Salesforce input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SalesforceSource",
                "query": "SELECT Col_Currency__c, Col_Date__c, Col_Email__c FROM AllDataType__c"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

참고 항목

이전 버전과의 호환성을 위해, Salesforce에서 데이터를 복사할 때 이전 "RelationalSource" 형식 데이터 집합을 사용할 경우 이 형식도 그대로 작동하지만 "SalesforceSource" 형식으로 전환하는 것이 좋습니다.

참고 항목

Salesforce 원본은 자체 호스팅 통합 런타임에서 프록시 설정을 지원하지 않지만 싱크는 지원합니다.

Salesforce를 싱크 형식으로

Salesforce에 데이터를 복사하려면 복사 작업의 싱크 형식을 SalesforceSink로 설정합니다. 복사 작업 싱크 섹션에서 지원되는 속성은 다음과 같습니다.

속성	설명	필수
type	복사 작업 싱크의 형식 속성은 SalesforceSink로 설정해야 합니다.	예
writeBehavior	작업의 쓰기 동작입니다. 허용되는 값은 Insert 및 Upsert입니다.	아니요(기본값: 삽입)
externalIdFieldName	Upsert 작업의 외부 ID 필드 이름입니다. 지정된 필드는 Salesforce 개체에서 "외부 ID 필드"로 정의되어야 합니다. 해당하는 입력 데이터에서 NULL 값을 가질 수 없습니다.	"Upsert"에서 예
writeBatchSize	각 일괄 처리에서 Salesforce에 작성된 데이터의 행 수입니다.	아니요(기본값: 5,000)
ignoreNullValues	쓰기 작업 중에 입력 데이터에서 NULL 값을 무시할지 여부를 나타냅니다. 허용되는 값은 true 및 false입니다. - True: Upsert나 업데이트 작업을 수행할 때 대상 개체의 데이터를 변경하지 않고 유지합니다. 삽입 작업을 수행할 때 정의된 기본 값을 삽입합니다. - False: Upsert나 업데이트 작업을 수행할 때 대상 개체의 데이터를 NULL로 업데이트합니다. 삽입 작업을 수행할 때 NULL 값을 삽입합니다.	아니요(기본값: false)
maxConcurrentConnections	작업 실행 중 데이터 저장소에 설정된 동시 연결의 상한입니다. 동시 연결을 제한하려는 경우에만 값을 지정합니다.	아님

예: 복사 작업의 Salesforce 싱크

"activities":[
    {
        "name": "CopyToSalesforce",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Salesforce output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "SalesforceSink",
                "writeBehavior": "Upsert",
                "externalIdFieldName": "CustomerId__c",
                "writeBatchSize": 10000,
                "ignoreNullValues": true
            }
        }
    }
]

쿼리 팁

Salesforce 보고서에서 데이터 검색

쿼리를 {call "<report name>"}으로 지정하여 Salesforce 보고서에서 데이터를 검색할 수 있습니다. 예제는 "query": "{call \"TestReport\"}"입니다.

Salesforce 휴지통에서 삭제된 레코드 검색

Salesforce 휴지통에서 소프트 삭제된 레코드를 쿼리하려면 readBehavior를 queryAll로 지정할 수 있습니다.

SOQL과 SQL 쿼리 구문의 차이점

Salesforce에서 데이터를 복사할 때 SOQL 쿼리 또는 SQL 쿼리를 사용할 수 있습니다. 이 두 가지 쿼리는 서로 다른 구문과 기능을 지원하므로 혼용하지 마세요. Salesforce에서 기본적으로 지원되는 SOQL 쿼리를 사용하는 것이 좋습니다. 다음 표에는 주요 차이점이 나와 있습니다.

구문	SOQL 모드	SQL 모드
열 선택	쿼리에 복사할 필드를 열거해야 합니다. 예: `SELECT field1, filed2 FROM objectname`	열 선택 외에도 `SELECT *`이 지원됩니다.
따옴표	필드/개체 이름은 따옴표로 묶을 수 없습니다.	필드/개체 이름은 따옴표로 묶을 수 있습니다. 예: `SELECT "id" FROM "Account"`
날짜/시간 형식	자세한 내용은 여기 및 다음 섹션의 샘플을 참조하세요.	자세한 내용은 여기 및 다음 섹션의 샘플을 참조하세요.
부울 값	`False` 및 `True`로 표시됩니다. 예: `SELECT … WHERE IsDeleted=True`	0 또는 1로 표시됩니다. 예: `SELECT … WHERE IsDeleted=1`
열 이름 바꾸기	지원되지 않습니다.	지원됨. 예: `SELECT a AS b FROM …`
관계	지원됨. 예: `Account_vod__r.nvs_Country__c`	지원되지 않습니다.

DateTime 열에서 Where 문을 사용하여 데이터를 검색합니다.

SOQL 또는 SQL 쿼리를 지정할 때 DateTime 형식 차이에 주의해야 합니다. 예시:

SOQL 샘플: SELECT Id, Name, BillingCity FROM Account WHERE LastModifiedDate >= @{formatDateTime(pipeline().parameters.StartTime,'yyyy-MM-ddTHH:mm:ssZ')} AND LastModifiedDate < @{formatDateTime(pipeline().parameters.EndTime,'yyyy-MM-ddTHH:mm:ssZ')}
SQL 샘플: SELECT * FROM Account WHERE LastModifiedDate >= {ts'@{formatDateTime(pipeline().parameters.StartTime,'yyyy-MM-dd HH:mm:ss')}'} AND LastModifiedDate < {ts'@{formatDateTime(pipeline().parameters.EndTime,'yyyy-MM-dd HH:mm:ss')}'}

MALFORMED_QUERY 오류: 잘림

"MALFORMED_QUERY: 잘림" 오류가 발생하는 경우 일반적으로 데이터에 JunctionIdList 형식 열이 있고 Salesforce에 많은 수의 행이 있는 이러한 데이터의 지원 제한이 있기 때문입니다. 완화하려면 JunctionIdList 열을 제외하거나 복사할 행 수를 제한합니다(여러 복사 작업 실행으로 분할할 수 있음).

Salesforce에 대한 데이터 형식 매핑

Salesforce에서 데이터를 복사할 경우 Salesforce 데이터 형식에서 내부적으로 서비스 내의 중간 데이터 형식으로 다음 매핑이 사용됩니다. 복사 활동에서 원본 스키마와 데이터 형식을 싱크에 매핑하는 방법에 대한 자세한 내용은 스키마 및 데이터 형식 매핑을 참조하세요.

Salesforce 데이터 형식	서비스 중간 데이터 형식
자동 번호	문자열
Checkbox	부울
통화	소수
날짜	DateTime
날짜/시간	DateTime
Email	문자열
ID	문자열
관계 조회	문자열
다중 선택 선택 목록	문자열
숫자	소수
퍼센트	소수
전화	문자열
선택 목록	문자열
Text	문자열
텍스트 영역	문자열
텍스트 영역(Long)	문자열
텍스트 영역(Rich)	문자열
텍스트(암호화됨)	문자열
URL	문자열

참고 항목

Salesforce 숫자 형식은 Azure Data Factory 및 Azure Synapse 파이프라인의 10진 형식에 서비스 중간 데이터 형식으로 매핑됩니다. 10진 형식은 정의된 정밀도와 스케일을 따릅니다. 소수점 이하 자릿수가 정의된 스케일을 초과하는 데이터의 경우 해당 값은 미리 보기 데이터 및 복사에서 반올림됩니다. Azure Data Factory 및 Azure Synapse 파이프라인에서 이러한 정밀도 손실을 방지하려면 Salesforce의 사용자 지정 필드 정의 편집 페이지에서 소수점 이하 자릿수를 상당히 큰 값으로 늘리는 것이 좋습니다.

조회 작업 속성

속성에 대한 자세한 내용을 보려면 조회 작업을 확인하세요.

다음 단계

복사 작업에서 원본 및 싱크로 지원되는 데이터 저장소 목록은 지원되는 데이터 저장소를 참조하세요.

다음을 통해 공유

Azure Data Factory 또는 Azure Synapse Analytics를 사용하여 Salesforce 간에 데이터 복사(레거시)

지원되는 기능

필수 조건

Salesforce 요청 제한

시작하기

UI를 사용하여 Salesforce에 연결된 서비스 만들기

커넥터 구성 세부 정보

연결된 서비스 속성

데이터 세트 속성

복사 작업 속성

Salesforce를 원본 형식으로

Salesforce를 싱크 형식으로

쿼리 팁

Salesforce 보고서에서 데이터 검색

Salesforce 휴지통에서 삭제된 레코드 검색

SOQL과 SQL 쿼리 구문의 차이점

DateTime 열에서 Where 문을 사용하여 데이터를 검색합니다.

MALFORMED_QUERY 오류: 잘림

Salesforce에 대한 데이터 형식 매핑

조회 작업 속성

다음 단계

피드백

추가 리소스