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

项目
10/29/2024

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

本文概述如何使用 Azure 数据工厂和 Synapse Analytics 管道中的复制活动从/向 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 开发人员版、专业版、企业版或不受限制版。
从/向 Salesforce 生产、沙盒和自定义域复制数据。

Salesforce 连接器在 Salesforce REST/Bulk API 之上构建。默认情况下，从 Salesforce 复制数据时，连接器会使用 v45 并根据数据大小自动在 REST 和 Bulk API 之间进行选择–结果集较大时，使用 Bulk API 可获得更好的性能；在将数据写入 Salesforce 时，连接器会使用 Bulk API 的 v40。还可通过链接服务中的 apiVersion 属性显式设置用于读取/写入数据的 API 版本。

先决条件

在 Salesforce 中，必须启用 API 权限。

Salesforce 请求限制

Salesforce 对 API 请求总数和并发 API 请求均有限制。请注意以下几点：

如果并发请求数超过限制，则将进行限制并且会看到随机失败。
如果请求总数超过限制，会阻止 Salesforce 帐户 24 小时。

在这两种情况下，还可能会收到“REQUEST_LIMIT_EXCEEDED”错误消息。有关详细信息，请参阅 Salesforce 开发人员限制中的“API 请求限制”部分。

入门

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

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

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

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

连接器配置详细信息

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

链接服务属性

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

属性	描述	必需
type	type 属性必须设置为 SalesforceServiceCloud。	是
environmentUrl	指定 Salesforce Service Cloud 实例的 URL。 - 默认为 `"https://login.salesforce.com"`。 - 要从沙盒复制数据，请指定 `"https://test.salesforce.com"`。 - 要从自定义域复制数据，请指定 `"https://[domain].my.salesforce.com"`（以此为例）。	否
username	为用户帐户指定用户名。	是
password	指定用户帐户的密码。将此字段标记为 SecureString 以安全地存储它，或引用 Azure Key Vault 中存储的机密。	是
securityToken	为用户帐户指定安全令牌。若要了解有关安全令牌的一般信息，请参阅 Security and the API（安全性和 API）。仅当将 Integration Runtime 的 IP 添加到 Salesforce 上的受信任 IP 地址列表时，才能跳过安全令牌。使用 Azure IR 时，请参阅 Azure Integration Runtime IP 地址。有关如何获取和重置安全令牌的说明，请参阅获取安全令牌。将此字段标记为 SecureString 以安全地将其存储在数据工厂中或引用存储在 Azure Key Vault 中的机密。	否
apiVersion	指定要使用的 Salesforce REST/Bulk API 版本，例如 `48.0`。默认情况下，连接器使用 v45 从 Salesforce 复制数据，使用 v40 将数据复制到 Salesforce。	否
connectVia	用于连接到数据存储的集成运行时。如果未指定，则使用默认 Azure Integration Runtime。	否

示例：存储凭据

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

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

{
    "name": "SalesforceServiceCloudLinkedService",
    "properties": {
        "type": "SalesforceServiceCloud",
        "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"
        }
    }
}

数据集属性

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

支持使用以下属性从/向 Salesforce Service Cloud 复制数据。

属性	描述	必需
type	type 属性必须设置为 SalesforceServiceCloudObject。	是
objectApiName	要从中检索数据的 Salesforce 对象名称。	对于源为“No”，对于接收器为“Yes”

重要

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

Salesforce 连接 API 名称

示例：

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

属性	描述	必需
type	数据集的 type 属性必须设置为 RelationalTable。	是
tableName	Salesforce Service Cloud 中的表名称。	否（如果指定了活动源中的“query”）

复制活动属性

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

将 Salesforce Service Cloud 用作源类型

从 Salesforce Service Cloud 复制数据时，复制活动的 source 节支持以下属性。

属性	描述	必需
type	复制活动源的 type 属性必须设置为 SalesforceServiceCloudSource。	是
查询	使用自定义查询读取数据。可以使用 Salesforce 对象查询语言 (SOQL) 查询或 SQL-92 查询。请在查询提示部分中查看更多提示。如果未指定查询，将检索在数据集的“objectApiName”中指定的 Salesforce Service Cloud 对象的所有数据。	否（如果指定了数据集中的“objectApiName”）
readBehavior	指示是查询现有记录，还是查询包括已删除记录在内的所有记录。如果未指定，默认行为是前者。允许的值：query（默认值）、queryAll。	否

重要

任何自定义对象均需要 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": "SalesforceServiceCloudSource",
                "query": "SELECT Col_Currency__c, Col_Date__c, Col_Email__c FROM AllDataType__c"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

注意

Salesforce 服务云源不支持自承载集成运行时中的代理设置，但接收器支持。

将 Salesforce Service Cloud 用作接收器类型

向 Salesforce Service Cloud 复制数据时，复制活动的 sink 节支持以下属性。

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

示例：

"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": "SalesforceServiceCloudSink",
                "writeBehavior": "Upsert",
                "externalIdFieldName": "CustomerId__c",
                "writeBatchSize": 10000,
                "ignoreNullValues": true
            }
        }
    }
]

查询提示

从 Salesforce Service Cloud 报表检索数据

可通过将查询指定为 {call "<report name>"} 从 Salesforce Service Cloud 报表检索数据。例如 "query": "{call \"TestReport\"}"。

从 Salesforce Service Cloud 回收站中检索删除的记录

若要从 Salesforce Service Cloud 回收站中查询软删除的记录，需要将 readBehavior 指定为 queryAll。

SOQL 与 SQL 查询语法之间的差异

从 Salesforce Service Cloud 中复制数据时，可以使用 SOQL 查询或 SQL 查询。请注意，这两者具有不同的语法和功能支持，不要混用。建议使用 Salesforce Service Cloud 原本就支持的 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:Truncated 错误

如果遇到“MALFORMED_QUERY:Truncated”错误，通常是因为在数据中存在 JunctionIdList 类型列，而 Salesforce 在支持此类具有大量行的数据方面存在限制。若要缓解这种情况，请尝试排除 JunctionIdList 列或限制要复制的行数（可以将其划分为多个复制活动运行）。

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 活动。

后续步骤

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

通过

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

支持的功能

先决条件

Salesforce 请求限制

入门

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

连接器配置详细信息

链接服务属性

数据集属性

复制活动属性

将 Salesforce Service Cloud 用作源类型

将 Salesforce Service Cloud 用作接收器类型

查询提示

从 Salesforce Service Cloud 报表检索数据

从 Salesforce Service Cloud 回收站中检索删除的记录

SOQL 与 SQL 查询语法之间的差异

使用 DateTime 列上的 where 子句检索数据

MALFORMED_QUERY:Truncated 错误

Salesforce Service Cloud 的数据类型映射

查找活动属性

后续步骤

其他资源