使用 Azure 数据工厂或 Azure Synapse Analytics 从/向 Salesforce Service Cloud 复制数据

项目
04/12/2024

适用于： Azure 数据工厂 Azure Synapse Analytics

提示

试用 Microsoft Fabric 中的数据工厂，这是一种适用于企业的一站式分析解决方案。 Microsoft Fabric 涵盖从数据移动到数据科学、实时分析、商业智能和报告的所有内容。了解如何免费开始新的试用！

本文概述如何使用 Azure 数据工厂和 Azure Synapse 管道中的复制活动从/向 Salesforce Service Cloud 复制数据。本文基于总体概述复制活动的复制活动概述一文。

重要

新的 Salesforce Service Cloud 连接器提供改进的原生 Salesforce Service Cloud 支持。如果在解决方案中使用了旧版 Salesforce Service Cloud 连接器，且该连接器仅“按原样”支持后向兼容性，请参阅 Salesforce Service Cloud 连接器（旧版）一文。

支持的功能

以下功能支持此 Salesforce Service Cloud 连接器：

支持的功能	IR
复制活动（源/接收器）	① ②
Lookup 活动	① ②

① Azure 集成运行时 ② 自承载集成运行时

如需可以用作源或接收器的数据存储的列表，请参阅支持的数据存储表。

具体而言，Salesforce Service Cloud 连接器支持：

Salesforce 开发人员版、专业版、企业版或不受限制版。
从自定义域复制数据或将数据复制到自定义域（可以在生产环境和沙箱环境中配置自定义域）。

可以通过链接服务中的 apiVersion 属性显式设置用于读取/写入数据的 API 版本。将数据复制到 Salesforce Service Cloud 时，连接器使用 BULK API 2.0。

先决条件

在 Salesforce 中，必须启用 API 权限。
需要参考此官方文档或这篇文章建议中的分步指南在 Salesforce 门户中配置已连接的应用。
重要
- 执行用户必须具有“仅限 API”权限。
- 可以通过会话策略而非刷新令牌来更改访问令牌过期时间。

Salesforce Bulk API 2.0 限制

我们使用 Salesforce Bulk API 2.0 来查询和引入数据。在 Bulk API 2.0 中，会自动为你创建批处理。每个滚动 24 小时周期最多可提交 15,000 个批处理。如果批处理数量超出限制，则会出现失败情况。

在 Bulk API 2.0 中，只有引入作业使用批处理。查询作业不使用它。有关详细信息，请参阅如何在 Bulk API 2.0 中处理请求 - 开发人员指南。

有关详细信息，请参阅 Salesforce 开发人员限制中的“常规限制”部分。

开始使用

若要使用管道执行复制活动，可以使用以下工具或 SDK 之一：

使用 UI 创建到 Salesforce Service Cloud 的链接服务

使用以下步骤在 Azure 门户 UI 中创建到 Salesforce Service Cloud 的链接服务。

浏览到 Azure 数据工厂或 Synapse 工作区中的“管理”选项卡并选择“链接服务”，然后单击“新建”：
- Azure 数据工厂
- Azure Synapse
搜索“Salesforce”并选择 Salesforce Service Cloud 连接器。
配置服务详细信息、测试连接并创建新的链接服务。

连接器配置详细信息

对于特定于 Salesforce Service Cloud 连接器的实体，以下部分提供有关用于定义这些实体的属性详细信息。

链接服务属性

Salesforce Service Cloud 链接服务支持以下属性。

properties	描述	必需
type	type 属性必须设置为 SalesforceServiceCloudV2。	是
environmentUrl	指定 Salesforce Service Cloud 实例的 URL。例如，指定 `"https://<domainName>.my.salesforce.com"` 以从自定义域复制数据。参考此文章来了解如何配置或查看你的自定义域。	是
authenticationType	用于连接 Salesforce Service Cloud 的身份验证类型。允许的值为 OAuth2ClientCredentials。	是
clientId	指定 Salesforce OAuth 2.0 连接的应用的客户端 ID。有关详细信息，请参阅此文章	是
clientSecret	指定 Salesforce OAuth 2.0 连接的应用的客户端机密。有关详细信息，请参阅此文章	是
apiVersion	指定要使用的 Salesforce Bulk API 2.0 版本，例如 `52.0`。 Bulk API 2.0 仅支持 API 版本 >= 47.0。若要了解 Bulk API 2.0 版本，请参阅此文章。如果你使用较低的 API 版本，将会导致失败。	是
connectVia	用于连接到数据存储的集成运行时。如果未指定，则使用默认 Azure Integration Runtime。	否

示例：存储凭据

{
    "name": "SalesforceServiceCloudLinkedService",
    "properties": {
        "type": "SalesforceServiceCloudV2",
        "typeProperties": {
            "environmentUrl": "<environment URL>",
            "authenticationType": "OAuth2ClientCredentials",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "SecureString",
                "value": "<client secret>"
            },
            "apiVersion": "<API Version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

示例：在密钥保管库中存储凭据

{
    "name": "SalesforceServiceCloudLinkedService",
    "properties": {
        "type": "SalesforceServiceCloudV2",
        "typeProperties": {
            "environmentUrl": "<environment URL>",
            "authenticationType": "OAuth2ClientCredentials",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of client secret in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "apiVersion": "<API Version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

数据集属性

有关可用于定义数据集的各部分和属性的完整列表，请参阅数据集一文。本部分提供 Salesforce Service Cloud 数据集支持的属性列表。

要从/向 Salesforce Service Cloud 复制数据，请将数据集的 type 属性设置为 SalesforceServiceCloudV2Object。支持以下属性。

属性	描述	必需
type	type 属性必须设置为 SalesforceServiceCloudV2Object。	是
objectApiName	要从中检索数据的 Salesforce Service Cloud 对象名称。	对于源不是必需的（如果指定了源中的“SOQLQuery”），对于接收器是必需的
reportId	要从中检索数据的 Salesforce Service Cloud 报表的 ID。它在接收器中不受支持。请注意，使用报表时存在限制。	对于源不是必需的（如果指定了源中的“SOQLQuery”），在接收器中不受支持

重要

任何自定义对象均需要 API 名称的“__c”部分。

Salesforce 连接 API 名称

示例：

{
    "name": "SalesforceServiceCloudDataset",
    "properties": {
        "type": "SalesforceServiceCloudV2Object",
        "typeProperties": {
            "objectApiName": "MyTable__c"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Salesforce Service Cloud linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

复制活动属性

有关可用于定义活动的各部分和属性的完整列表，请参阅管道一文。本部分提供 Salesforce Service Cloud 源和接收器支持的属性列表。

将 Salesforce Service Cloud 用作源类型

要从 Salesforce Service Cloud 复制数据，请将复制活动中的源类型设置为 SalesforceServiceCloudV2Source。复制活动的 source 节支持以下属性。

属性	描述	必需
type	复制活动源的 type 属性必须设置为 SalesforceServiceCloudV2Source。	是
SOQLQuery	使用自定义查询读取数据。只能使用具有限制的 Salesforce 对象查询语言 (SOQL) 查询。有关 SOQL 限制，请参阅这篇文章。如果未指定查询，将检索在数据集的“ObjectApiName/reportId”中指定的 Salesforce 对象的所有数据。	否（如果指定了数据集中的“ObjectApiName/reportId”）
includeDeletedObjects	指示是查询现有记录，还是查询包括已删除记录在内的所有记录。如果未指定，则默认行为为 false。允许的值：false（默认）和 true。	否

重要

任何自定义对象均需要 API 名称的“__c”部分。

Salesforce 连接 API 名称列表

示例：

"activities":[
    {
        "name": "CopyFromSalesforceServiceCloud",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Salesforce Service Cloud input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SalesforceServiceCloudV2Source",
                "SOQLQuery": "SELECT Col_Currency__c, Col_Date__c, Col_Email__c FROM AllDataType__c",
                "includeDeletedObjects": false
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

将 Salesforce Service Cloud 用作接收器类型

若要将数据复制到 Salesforce Service Cloud，请将复制活动中的接收器类型设置为 SalesforceServiceCloudV2Sink。复制活动 sink 节支持以下属性。

属性	描述	必需
type	复制活动接收器的 type 属性必须设置为 SalesforceServiceCloudV2Sink。	是
writeBehavior	操作写入行为。允许的值为 Insert 和 Upsert。	否（默认值为 Insert）
externalIdFieldName	更新插入操作的外部的 ID 字段名称。指定的字段必须在 Salesforce Service Cloud 对象中定义为“外部 ID 字段”。它相应的输入数据中不能有 NULL 值。	对于“Upsert”是必需的
writeBatchSize	每批中写入到 Salesforce Service Cloud 的数据行计数。建议将此值设置为介于 10,000 和 200,000 之间的值。每批中的行太少会降低复制性能。每批中的行过多可能会导致 API 超时。	否（默认值为 100,000）
ignoreNullValues	指示是否忽略 NULL 值从输入数据期间写入操作。允许的值为 true 和 false。 - True：执行更新插入或更新操作时，保持目标对象中的数据不变。插入在执行插入操作时定义的默认值。 - False：执行更新插入或更新操作时，将目标对象中的数据更新为 NULL。执行插入操作时插入 NULL 值。	否（默认值为 false）
maxConcurrentConnections	活动运行期间与数据存储建立的并发连接的上限。仅在要限制并发连接时指定一个值。	无

示例：复制活动中的 Salesforce Service Cloud 接收器

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

Salesforce Service Cloud 的数据类型映射

当你从 Salesforce Service Cloud 复制数据时，会在内部使用以下映射，将 Salesforce Service Cloud 数据类型映射到服务中的临时数据类型。若要了解复制活动如何将源架构和数据类型映射到接收器，请参阅架构和数据类型映射。

Salesforce Service Cloud 数据类型	服务临时数据类型
自动编号	String
复选框	布尔
货币	小数
Date	DateTime
日期/时间	DateTime
Email	String
ID	String
查找关系	String
多选择列表	String
Number	小数
百分比	小数
电话	String
选择列表	String
文本	String
文本区域	String
文本区域（长型值）	String
文本区域（丰富）	String
文本（加密）	String
URL	String

注意

Salesforce Service Cloud 的“数字”类型映射为 Azure 数据工厂和 Azure Synapse 管道中的“十进制”类型，作为一种服务临时数据类型。 “十进制”类型遵循定义的精度和小数位数。 对于小数位数超过定义的小数位数的数据，其值将在预览数据和副本中进行舍入。 为了避免在 Azure 数据工厂和 Azure Synapse 管道中出现此类精度损失，请考虑在 Salesforce Service Cloud 的“自定义字段定义编辑”页中将小数位数提高到相当大的值。

查找活动属性

若要了解有关属性的详细信息，请查看 Lookup 活动。

升级 Salesforce Service Cloud 链接服务

下面是帮助你升级链接服务和相关查询的步骤：

参考先决条件在 Salesforce 门户中配置连接的应用。
新建 Salesforce Service Cloud 链接服务，并参考链接服务属性对其进行配置。
如果你在复制活动源或引用旧版链接服务的查找活动中使用 SQL 查询，则需要将它们转换为 SOQL 查询。从 Salesforce Service Cloud 作为源类型和 Salesforce 对象查询语言 (SOQL) 详细了解 SOQL 查询。
readBehavior 在复制活动源或查找活动中被替换为 includeDeletedObjects。有关详细配置，请参阅将 Salesforce Service Cloud 用作源类型。

有关复制活动支持作为源和接收器的数据存储的列表，请参阅受支持的数据存储。