使用 Azure Data Factory 或 Synapse Analytics (舊版) 將資料複製到 Salesforce 服務雲端

發行項
05/22/2024

適用於：Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。了解如何免費開始新的試用！

本文概述如何使用 Azure Data Factory 和 Synapse Analytics 管線中的複製活動，將資料從 Salesforce 服務雲端複製並複製到 Salesforce 服務雲端。本文是根據複製活動概觀一文，該文提供複製活動的一般概觀。

重要

新的 Salesforce Service Cloud 連接器提供改善的原生 Salesforce Service Cloud 支援。如果您在解決方案中使用舊版 Salesforce Service Cloud 連接器，請在 2024 年 10 月 11 日之前升級 Salesforce Service Cloud 連接器。如需舊版與最新版本之間差異的詳細資料，請參閱本節。

支援的功能

此 Salesforce Service Cloud 連接器支援下列功能：

支援的功能	IR
複製活動 (來源/接收)	4.9
查閱活動	4.9

① Azure 整合執行階段 ② 自我裝載整合執行階段

如需支援作為來源或接收器的資料存放區清單，請參閱支援的資料存放區表格。

具體而言，這個 Salesforce 服務雲端連接器支援：

Salesforce Developer、Professional、Enterprise 或 Unlimited 版本。
從 Salesforce 生產環境、沙箱、自訂網域複製資料，以及將資料複製到這些位置。

Salesforce 連接器建置在 Salesforce REST/Bulk API 之上。根據預設，從 Salesforce 複製資料時，連接器會使用 v45，並根據資料大小自動選擇 REST 和大量 API - 當結果集很大時，會使用大量 API 以獲得更好的效能；將資料寫入 Salesforce 時，連接器會使用大量 API 的 v40。您也可以透過連結服務中的apiVersion屬性來明確設定用來讀取/寫入資料的 API 版本。

必要條件

必須在 Salesforce 中啟用 API 權限。

Salesforce 要求限制

Salesforce 對於 API 要求總數和並行 API 要求均有限制。請注意下列幾點：

如果並行要求數目超過限制，系統就會進行節流，您將會看到隨機失敗。
如果要求總數超過限制，將會封鎖 Salesforce 帳戶 24 小時。

在上述兩種情況中，您也可能會收到 "REQUEST_LIMIT_EXCEEDED" 錯誤。如需詳細資訊，請參閱 Salesforce 開發人員限制中的＜API 要求限制＞一節。

開始使用

若要透過管線執行複製活動，您可以使用下列其中一個工具或 SDK：

使用 UI 建立 Salesforce 服務雲端的連結服務

使用下列步驟，在 Azure 入口網站 UI 中建立連結至 Salesforce 服務雲端的服務。

前往 Azure Data Factory 或 Synapse 工作區的 [管理] 索引標籤，選取 [連結服務]，然後按一下 [新增]：
- Azure Data Factory
- Azure Synapse
搜尋 Salesforce，然後選取 Salesforce 服務雲端連接器。
設定服務詳細資料，測試連線，然後建立新的連結服務。

連接器設定詳細資料

下列各節提供屬性的相關詳細資料，這些屬性是用來定義 Salesforce 服務雲端連接器特定的 Data Factory 實體。

連結服務屬性

以下是針對 Salesforce 連結服務支援的屬性。

屬性	描述	必要
type	類型屬性必須設為 SalesforceServiceCloud。	Yes
environmentUrl	指定 Salesforce 服務雲端執行個體的 URL。 - 預設為 `"https://login.salesforce.com"`. - 若要從沙箱複製資料，請指定 `"https://test.salesforce.com"`。 - 若要從自訂網域複製資料，舉例來說，請指定 `"https://[domain].my.salesforce.com"`。	No
username	指定使用者帳戶的使用者名稱。	Yes
password	指定使用者帳戶的密碼。將此欄位標記為 SecureString 以便安全儲存，或參考 Azure Key Vault 中儲存的祕密。	Yes
securityToken	指定使用者帳戶的安全性權杖。若要整體了解安全性權杖，請參閱安全性和 API。只有在您將 Integration Runtime 的 IP 新增至 Salesforce 上的受信任 IP 位址清單 (英文) 時，才能略過安全性權杖。使用 Azure IR 時，請參閱 Azure Integration Runtime IP 位址 (部分機器翻譯)。如需如何取得及重設安全性權杖的指示，請參閱取得安全性權杖。將此欄位標記為 SecureString，將它安全地儲存在 Data Factory 中，或參考 Azure Key Vault 中儲存的祕密。	No
apiVersion	指定要使用的 Salesforce REST/Bulk API 版本，例如 `48.0`。根據預設，連接器會使用 v45 從 Salesforce 複製資料，並使用 v40 將資料複製到 Salesforce。	No
connectVia	用來連線到資料存放區的整合執行階段。如果未指定，就會使用預設的 Azure Integration Runtime。	No

範例：儲存認證

{
    "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"
        }
    }
}

範例：在 Key Vault 中儲存認證

{
    "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 服務雲端資料集所支援的屬性清單。

若要從 Salesforce 服務雲端複製資料，系統支援下列屬性。

屬性	描述	必要
type	類型屬性必須設為 SalesforceServiceCloudObject。	Yes
objectApiName	要從其中擷取資料的 Salesforce 物件名稱。	否 (來源)；是 (接收)

重要

所有自訂物件的 [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。	Yes
tableName	Salesforce 服務雲端中資料表的名稱。	否 (如果已指定活動來源中的「查詢」)

複製活動屬性

如需可用來定義活動的區段和屬性完整清單，請參閱管線一文。本節提供 Salesforce 服務雲端來源和接收所支援的屬性清單。

Salesforce 服務雲端作為來源類型

若要從 Salesforce 服務雲端複製資料，複製活動的 [source] 區段中支援下列屬性。

屬性	描述	必要
type	複製活動來源的類型屬性必須設定為 SalesforceServiceCloudSource。	Yes
query	使用自訂查詢來讀取資料。您可以使用 Salesforce 物件查詢語言 (SOQL) 查詢或 SQL-92 查詢。請參閱查詢秘訣一節中的秘訣。如果未指定查詢，將會在資料集內擷取 "objectApiName" 中所指定 Salesforce 服務雲端物件的所有資料。	否 (如果在資料集中指定 "objectApiName")
readBehavior	指出是要查詢現有記錄，還是要查詢包含已刪除記錄在內的所有記錄。如果未指定，預設行為是前者。允許的值：query (預設值)、queryAll。	No

重要

所有自訂物件的 [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 Service Cloud 來源在自我裝載整合執行階段中不支援 Proxy 設定，但是接收器支援。

Salesforce 服務雲端作為接收器類型

若要複製資料至 Salesforce 服務雲端，複製活動的 [sink] 區段中支援下列屬性。

屬性	描述	必要
type	複製活動接收的 type 屬性必須設定為 SalesforceServiceCloudSink。	Yes
writeBehavior	作業的寫入行為。允許的值為 Insert 和 Upsert。	否 (預設為 Insert)
externalIdFieldName	upsert 作業的外部識別碼欄位名稱。指定的欄位在 Salesforce 服務雲端物件中必須定義為「外部識別碼欄位」。對應的輸入資料中不能有 NULL 值。	是 (用於 upsert)
writeBatchSize	每個批次中寫入 Salesforce 服務雲端的資料列計數。	否 (預設值為 5,000)
ignoreNullValues	指出在寫入作業期間是否要忽略輸入資料中的 NULL 值。允許的值為 true 和 false。 - true：執行 upsert 或更新作業時，讓目的地物件中的資料保持不變。執行插入作業時，插入已定義的預設值。 - false：執行 upsert 或更新作業時，將目的地物件中的資料更新為 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 服務雲端報告擷取資料

您可以藉由指定 {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 服務雲端資料類型	服務過渡資料類型
自動編號	String
核取方塊	布林值
貨幣	Decimal
Date	Datetime
日期/時間	Datetime
Email	String
識別碼	String
查閱關聯性	String
複選挑選清單	String
數字	Decimal
Percent	Decimal
手機	String
Picklist	String
Text	String
文字區域	String
文字區域 (完整)	String
文字區域 (豐富)	String
文字 (加密)	String
URL	String

注意

Salesforce Service Cloud 編號型別會對應至 Azure Data Factory 中的十進位型別，Azure Synapse Analytics 管線即服務過渡資料類型。十進位型別會接受定義的有效位數和小數位數別。 針對小數位數超過所定義小數位數的資料，其值將會在預覽資料和複製中四捨五入。 若要避免在 Azure Data Factory 和 Azure Synapse Analytics 管線中造成這種精確度方面的缺失，請考慮在 Salesforce 服務雲端的 [自訂欄位定義編輯] 頁面中，將小數位數增加為合適的大值。

查閱活動屬性

若要了解屬性的詳細資料，請參閱查閱活動。

下一步

如需複製活動支援作為來源和接收器的資料存放區清單，請參閱支援的資料存放區。

共用方式為

使用 Azure Data Factory 或 Synapse Analytics (舊版) 將資料複製到 Salesforce 服務雲端

支援的功能

必要條件

Salesforce 要求限制

開始使用

使用 UI 建立 Salesforce 服務雲端的連結服務

連接器設定詳細資料

連結服務屬性

資料集屬性

複製活動屬性

Salesforce 服務雲端作為來源類型

Salesforce 服務雲端作為接收器類型

查詢秘訣

從 Salesforce 服務雲端報告擷取資料

從 Salesforce 服務雲端資源回收筒擷取已刪除的記錄

SOQL 和 SQL 查詢語法的差異

在 DateTime 資料行上使用 where 子句來擷取資料

MALFORMED_QUERY 的錯誤：已截斷

Salesforce 服務雲端的資料類型對應

查閱活動屬性

下一步

意見反應

其他資源