使用 Azure Data Factory 或 Azure Synapse Analytics (舊版) 從 Salesforce 複製資料或將資料複製到該處

發行項
05/22/2024

適用於：Azure Data Factory Azure Synapse Analytics

提示

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

此文章概述如何使用 Azure Data Factory 和 Azure Synapse 管線中的「複製活動」，從 Salesforce 複製資料或將資料複製到該處。本文是根據複製活動概觀一文，該文提供複製活動的一般概觀。

重要

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

支援的功能

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

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

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

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

具體而言，這個 Salesforce 連接器支援：

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

注意

此函式支援上述 Salesforce 環境的任何結構描述副本，包括 Nonprofit Success Pack (NPSP)。

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 入口網站 UI 中建立 Salesforce 的連結服務。

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

連接器設定詳細資料

下列各節提供屬性的相關詳細資料，這些屬性是用來定義 Salesforce 連接器專屬的實體。

連結服務屬性

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

屬性	描述	必要
type	type 屬性必須設為 Salesforce。	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 以便安全儲存，或參考 Azure Key Vault 中儲存的祕密。	No
apiVersion	指定要使用的 Salesforce REST/Bulk API 版本，例如 `52.0`。	No
connectVia	用來連線到資料存放區的整合執行階段。如果未指定，就會使用預設的 Azure Integration Runtime。	No

範例：儲存認證

{
    "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 和 username

請注意，如此一來，您將無法再使用 UI 來編輯設定。將會核取 [以 JSON 格式指定動態內容] 核取方塊，而且您必須完全手動編輯此設定。優點是您可以從 Key Vault 取得 ALL 組態設定，而不是參數化此處的內容。

{
    "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 複製資料以及將資料複製到 Salesforce，請將資料集的 type 屬性設定為 SalesforceObject。以下是支援的屬性。

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

重要

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

複製活動屬性

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

Salesforce 作為來源類型

若要從 Salesforce 複製資料，請將複製活動中的來源類型設定為 SalesforceSource。複製活動的 [來源] 區段支援下列屬性。

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

重要

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

Salesforce 作為接收類型

若要將資料複製到 Salesforce，請將複製活動中的接收器類型設定為 SalesforceSink。複製活動的 [接收] 區段支援下列屬性。

屬性	描述	必要
type	複製活動接收的 type 屬性必須設定為 SalesforceSink。	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	在活動執行期間建立至資料存放區的同時連線上限。僅在想要限制並行連線時，才需要指定值。	否

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

查閱活動屬性

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

下一步

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

共用方式為