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

發行項
10/01/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 版本。
將資料從自訂網域複製並複製到自訂網域 (可以同時在生產環境與沙箱環境中設定自訂網域)。

您可以透過連結服務中的 apiVersion 屬性，以明確設定用來讀取/寫入資料的 API 版本。您要將資料複製到 Salesforce 時，連接器會使用 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 的連結服務

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

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

連接器設定詳細資料

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

連結服務屬性

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

屬性	描述	必要
type	type 屬性必須設為：SalesforceV2。	Yes
environmentUrl	指定 Salesforce 執行個體的 URL。例如，指定 `"https://<domainName>.my.salesforce.com"` 從自訂網域複製資料。請參閱本文章了解如何設定或檢視自訂網域。	Yes
authenticationType	用來連接到 Salesforce 的驗證類型。允許的值為 OAuth2ClientCredentials。	Yes
clientId	指定 Salesforce OAuth 2.0 連線應用程式的用戶端識別碼。如需詳細資訊，請移至此文章	Yes
clientSecret	指定 Salesforce OAuth 2.0 連線應用程式的用戶端密碼。如需詳細資訊，請移至此文章	Yes
apiVersion	指定要使用的 Salesforce Bulk API 2.0 版本，例如 `52.0`。 Bulk API 2.0 僅支援 API 版本 >= 47.0。若要了解 Bulk API 2.0 版本，請參閱文章。如果您使用較低的 API 版本，就會發生失敗。	Yes
connectVia	用來連線到資料存放區的整合執行階段。如果未指定，就會使用預設的 Azure Integration Runtime。	No

範例：儲存認證

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

範例：在 Key Vault 中儲存認證

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

範例：在 Key Vault 中儲存認證，以及 environmentUrl 和 clientId

您可以將認證儲存在 Key Vault 中，以及 environmentUrl 和 clientId，以較長時間使用 UI 來編輯設定。必須核取 [以 JSON 格式指定動態內容] 核取方塊，且您必須手動進行此設定。此案例的優點是您可以從 Key Vault 取得 ALL 組態設定，而不是參數化此處的內容。

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "SalesforceV2",
        "typeProperties": {
            "environmentUrl": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of environment URL in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "authenticationType": "OAuth2ClientCredentials",
            "clientId": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of client ID in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "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 資料集所支援的屬性清單。

若要從 Salesforce 複製資料和將資料複製到 Salesforce，請將資料集的 type 屬性設為 SalesforceV2Object。以下是支援的屬性。

屬性	描述	必要
type	type 屬性必須設為：SalesforceV2Object。	Yes
objectApiName	要從其中擷取資料的 Salesforce 物件名稱。適用的自我裝載整合執行階段版本是 5.44.8984.1 或更高版本。	否 (來源，如果已指定來源中的「查詢」)；是 (接收)
reportId	要從中擷取資料的 Salesforce 報告識別碼。其在接收中不受支援。使用報告時有限制。適用的自我裝載整合執行階段版本是 5.44.8984.1 或更高版本。	否 (來源，如果已指定來源中的「查詢」)；不支援接收

重要

所有自訂物件的 [API 名稱]都要有 "__c" 部分。

Salesforce 連線 API 名稱

範例：

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

複製活動屬性

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

Salesforce 作為來源類型

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

屬性	描述	必要
type	複製活動來源的 type 屬性必須設為 SalesforceV2Source。	Yes
query	使用自訂查詢來讀取資料。您只能使用具有限制的 Salesforce Object Query Language (SOQL) 查詢。如需 SOQL 限制，請參閱這篇文章。若未指定查詢，將會擷取在資料集的 "objectApiName/reportId" 中指定之 Salesforce 物件的所有資料。	否 (如果指定了資料集中的 "objectApiName/reportId")
includeDeletedObjects	指出是要查詢現有記錄，還是要查詢包含已刪除記錄在內的所有記錄。如果未指定，預設行為為 False。允許的值：false (預設值)、true。	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": "SalesforceV2Source",
                "query": "SELECT Col_Currency__c, Col_Date__c, Col_Email__c FROM AllDataType__c",
                "includeDeletedObjects": false
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Salesforce 作為接收類型

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

屬性	描述	必要
type	複製活動接收的 type 屬性必須設為 SalesforceV2Sink。	Yes
writeBehavior	作業的寫入行為。允許的值為 Insert 和 Upsert。	否 (預設為 Insert)
externalIdFieldName	upsert 作業的外部識別碼欄位名稱。指定的欄位在 Salesforce 物件中必須定義為「外部識別碼欄位」。對應的輸入資料中不能有 NULL 值。	是 (用於 upsert)
writeBatchSize	每個批次中寫入 Salesforce 的資料列計數。建議將此值從 10,000 設定為 200,000。每個批次中的資料列太少，可降低複製效能。每個批次中的資料列數太多，可能會導致 API 逾時。	否 (預設為 100,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": "SalesforceV2Sink",
                "writeBehavior": "Upsert",
                "externalIdFieldName": "CustomerId__c",
                "writeBatchSize": 10000,
                "ignoreNullValues": true
            }
        }
    }
]

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 的 [自訂欄位定義編輯] 頁面中，將小數位數增加為合適的大值。

查閱活動屬性

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

升級 Salesforce 連結服務

以下是可協助您升級連結服務和相關查詢的步驟：

參考必要條件，以在 Salesforce 入口網站中設定連線的應用程式。
新建 Salesforce 連結服務，並藉由參考連結服務屬性加以設定。您也需要手動更新依賴舊連結服務的現有資料集，並編輯每個資料集以改用新的連結服務。
如果您在參照舊版連結服務的複製活動來源或查閱活動中使用 SQL 查詢，則必須將其轉換為 SOQL 查詢。從將 Salesforce 作為來源類型和 Salesforce 物件查詢語言 (SOQL) 深入了解 SOQL 查詢。
readBehavior 會取代為複製活動來源或查閱活動中的 includeDeletedObjects。如需詳細設定，請參閱 Salesforce 做為來源類型。

Salesforce 與 Salesforce 之間的差異 (舊版)

Salesforce 連接器提供新功能，並與 Salesforce (舊版) 連接器的大部分功能相容。下表顯示 Salesforce 與 Salesforce (舊版) 之間的功能差異。

Salesforce	Salesforce (舊版)
支援 Salesforce Bulk API 2.0 內的 SOQL。針對 SOQL 查詢： • 不支援 GROUP BY、LIMIT、ORDER BY、OFFSET 或 TYPEOF 子句。 • 不支援 COUNT() 等彙總函式，您可以使用 Salesforce 報表來加以實作。 • 不支援 GROUP BY 子句中的日期函式，但在 WHERE 子句中則可支援。 • 不支援複合位址欄位或複合地理位置欄位。或者，查詢複合欄位的個別元件。 • 不支援父對子關聯性查詢，而支援子對父關聯性查詢。	同時支援 SQL 和 SOQL 語法。
指定查詢時，不支援包含二進位欄位的物件。	指定查詢時，支援包含二進位欄位的物件。
指定查詢時，支援大量 API 中的物件。	指定查詢時，支援大量 API 不支援的物件。
選取報表識別碼來支援報表。	支援報表查詢語法，例如 `{call "<report name>"}`。

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

共用方式為

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

支援的功能

必要條件

Salesforce Bulk API 2.0 限制

開始使用

使用 UI 建立 Salesforce 的連結服務

連接器設定詳細資料

連結服務屬性

資料集屬性

複製活動屬性

Salesforce 作為來源類型

Salesforce 作為接收類型

Salesforce 的資料類型對應

查閱活動屬性

升級 Salesforce 連結服務

Salesforce 與 Salesforce 之間的差異 (舊版)

意見反應

其他資源

共用方式為

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

支援的功能

必要條件

Salesforce Bulk API 2.0 限制

開始使用

使用 UI 建立 Salesforce 的連結服務

連接器設定詳細資料

連結服務屬性

資料集屬性

複製活動屬性

Salesforce 作為來源類型

Salesforce 作為接收類型

Salesforce 的資料類型對應

查閱活動屬性

升級 Salesforce 連結服務

Salesforce 與 Salesforce 之間的差異 (舊版)

相關內容

意見反應

其他資源