使用 Azure Data Factory 或 Synapse 管線，在 Azure Synapse Analytics 中複製和轉換資料

發行項
07/23/2024

適用於：Azure Data Factory Azure Synapse Analytics

提示

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

本文概述如何使用 Azure Data Factory 或 Synapse 管線中的複製活動，在 Azure Synapse Analytics 中來回複製資料，以及如何使用資料流程在 Azure Data Lake Storage Gen2 中轉換資料。若要了解 Azure Data Factory，請閱讀簡介文章。

支援的功能

此 Azure Synapse Analytics 連接器支援下列功能：

支援的功能	IR	受控私人端點
複製活動 (來源/接收)	① ②	✓
對應資料流 (來源/接收)	①	✓
查閱活動	① ②	✓
GetMetadata 活動	① ②	✓
指令碼活動	① ②	✓
預存程序活動	① ②	✓

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

針對複製活動，此 Azure Synapse 分析連接器支援下列功能：

搭配使用 SQL 驗證和 Microsoft Entra 應用程式權杖驗證與服務主體或 Azure 資源受控識別，以複製資料。
作為來源時，使用 SQL 查詢或預存程序來擷取資料。您也可以選擇從 Azure Synapse Analytics 來源平行複製，如需詳細資訊，請參閱從 Azure Synapse Analytics 平行複製一節。
做為接收時，使用 COPY 陳述式或 PolyBase 或大量插入來載入資料。建議使用 COPY 陳述式或 PolyBase，以獲得較佳的複製效能。連接器也支援使用 DISTRIBUTION = ROUND_ROBIN 自動建立目的地資料表 (如果根據來源結構描述的項目不存在)。

重要

如果您使用 Azure Integration Runtime 複製資料，請設定伺服器層級防火牆規則，使得 Azure 服務可存取邏輯 SQL 伺服器。如果您使用自我裝載整合執行階段來複製資料，請將防火牆設定為允許適當的 IP 範圍。此範圍包括機器的 IP，用來連線到 Azure Synapse Analytics。

開始使用

提示

若要達到最佳效能，請使用 PolyBase 或 COPY 陳述式將資料載入 Azure Synapse Analytics。使用 PolyBase 將資料載入 Azure Synapse Analytics 和使用 COPY 陳述式將資料載入Azure Synapse Analytics 區段提供詳細資料。如需使用案例的逐步解說，請參閱使用 Azure Data Factory 在 15 分鐘內將 1 TB 載入至 Azure Synapse Analytics。

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

使用 UI 建立 Azure Synapse Analytics 連結服務

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

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

連接器設定詳細資料

下列各節提供屬性的相關詳細資料，這些屬性會定義 Azure Synapse Analytics 連接器專屬的 Data Factory 和 Synapse 管線實體。

連結服務屬性

Azure Synapse Analytics 連接器建議的版本支援 TLS 1.3。請參閱本節，從舊版升級 Azure Synapse Analytics 連接器版本。如需屬性詳細資料，請參閱對應的章節。

建議的版本
舊版

提示

使用 Azure 入口網站在 Azure Synapse 中為無伺服器 SQL 集區建立連結服務時：

針對 [帳戶選取方法]，選擇 [手動輸入]。
貼上無伺服器端點的完整網域名稱。您可以在 Azure 入口網站 Synapse 工作區的 [概觀] 頁面中，從 [無伺服器 SQL 端點] 底下的屬性找到此資訊。例如： myserver-ondemand.sql-azuresynapse.net 。
針對 [資料庫名稱]，提供無伺服器 SQL 集區中的資料庫名稱。

提示

如果您遇到錯誤，其錯誤碼為 "UserErrorFailedToConnectToSqlServer"，以及「資料庫的工作階段限制為 XXX 並已達到。」訊息，請將 Pooling=false 新增至您的連接字串並再試一次。

建議的版本

當您套用建議的版本時，Azure Synapse Analytics 連結服務支援這些泛型屬性：

屬性	描述	必要
type	類型屬性必須設為 AzureSqlDW。	Yes
伺服器	您想要連線的 SQL Server 執行個體名稱或其網路位址。	Yes
database	資料庫的名稱。	Yes
authenticationType	用於驗證的類型。允許的值為 SQL (預設值)、ServicePrincipal、SystemAssignedManagedIdentity、UserAssignedManagedIdentity。移至特定屬性和必要條件的相關驗證一節。	Yes
encrypt	指出用戶端與伺服器之間傳送的所有資料是否都需要 TLS 加密。選項：強制 (若為 true，預設值)/選擇性 (若為 false)/strict。	No
trustServerCertificate	指出通道是否會加密，同時略過驗證信任的憑證鏈結。	No
hostNameInCertificate	針對連線驗證伺服器憑證時要使用的主機名稱。未指定時，伺服器名稱會用於憑證驗證。	No
connectVia	用來連線到資料存放區的整合執行階段。您可以使用 Azure Integration Runtime 或自我裝載整合執行階段 (如果您的資料存放區位於私人網路中)。如果未指定，就會使用預設的 Azure Integration Runtime。	No

如需其他連線屬性，請參閱下表：

屬性	描述	必要
applicationIntent	連線至伺服器時的應用程式工作負載類型。允許值為：`ReadOnly` 和 `ReadWrite`。	No
connectTimeout	在終止嘗試連接到伺服器並產生錯誤之前，所等候的時間長度 (以秒為單位)。	No
connectRetryCount	識別到閒置連線失敗之後，嘗試重新連線的次數。此值應為介於 0 到 255 之間的整數。	No
connectRetryInterval	識別閒置連線失敗之後，每次重新連線嘗試之間的時間 (以秒為單位)。此值應為介於 1 到 60 之間的整數。	No
loadBalanceTimeout	在連線終結之前，連線在連線集區中存在的最短時間 (以秒為單位)。	No
commandTimeout	終止嘗試執行命令並產生錯誤之前的預設等候時間 (以秒為單位)。	No
integratedSecurity	允許的值為 `true` 或 `false`。指定 `false` 時，指出是否已在連線中指定 userName 和 password。指定 `true` 時，指出目前的 Windows 帳戶認證是否用於驗證。	No
failoverPartner	主要伺服器已關閉時，待連線合作夥伴伺服器的名稱或位址。	No
maxPoolSize	特定連線的連線集區中允許的連線數目上限。	No
minPoolSize	特定連線的連線集區中允許的連線數目下限。	No
multipleActiveResultSets	允許的值為 `true` 或 `false`。當您指定 `true` 時，應用程式可以維護多個使用中結果集 (MARS)。當您指定 `false` 時，應用程式必須先處理或取消一個批次的所有結果集，才能在該連線上執行任何其他批次。	No
multiSubnetFailover	允許的值為 `true` 或 `false`。如果您的應用程式連線至不同子網路上的 AlwaysOn 可用性群組 (AG)，則將此屬性設定為 `true` 可以更快地偵測並連線到目前使用中的伺服器。	No
packetSize	伺服器執行個體通訊所使用的網路封包大小 (位元組)。	No
共用	允許的值為 `true` 或 `false`。當您指定 `true` 時，連線會是集區式連線。當您指定 `false` 時，每次要求連線時都會明確開啟連線。	No

SQL 驗證

若要使用 SQL 驗證，除了上一節所述的泛型屬性外，請指定下列屬性：

屬性	描述	必要
userName	用來連線到伺服器的使用者名稱。	Yes
password	使用者名稱的密碼。將此欄位標記為 SecureString 以將其安全地儲存。或者，可以參考 Azure Key Vault 中儲存的認證。	Yes

範例：使用 SQL 驗證

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SQL",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

範例：Azure Key Vault 中的密碼

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SQL",
            "userName": "<user name>",
            "password": {
                "type": "AzureKeyVaultSecret",
                "store": {
                    "referenceName": "<Azure Key Vault linked service name>",
                    "type": "LinkedServiceReference"
                },
                "secretName": "<secretName>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

服務主體驗證

若要使用服務主體驗證，除了上一節所述的一般屬性外，請指定下列屬性：

屬性	描述	必要
servicePrincipalId	指定應用程式的用戶端識別碼。	Yes
servicePrincipalCredential	服務主體認證。指定應用程式的金鑰。將此欄位標記為 SecureString 以將其安全地儲存，或參考 Azure Key Vault 中儲存的祕密。	Yes
tenant	指定您的應用程式所在租用戶的資訊 (網域名稱或租用戶識別碼)。將滑鼠游標暫留在 Azure 入口網站右上角，即可擷取它。	Yes
azureCloudType	針對服務主體驗證，請指定註冊 Microsoft Entra 應用程式的 Azure 雲端環境類型。允許的值為 `AzurePublic`、`AzureChina`、`AzureUsGovernment` 和 `AzureGermany`。預設會使用 Data Factory 或 Synapse 管線的雲端環境。	No

此外，請依照下列步驟操作：

從 Azure 入口網站建立 Microsoft Entra 應用程式。請記下應用程式名稱，以及下列可定義連結服務的值：
- Application ID
- 應用程式金鑰
- 租用戶識別碼
如果您尚未在 Azure 入口網站中，為伺服器佈建 Microsoft Entra 管理員，請加以佈建。 Microsoft Entra 管理員可以是 Microsoft Entra 使用者或 Microsoft Entra 群組。如果您授與受控識別系統管理員角色，請略過步驟 3 和 4。系統管理員將擁有資料庫的完整存取權。
為服務主體建立自主資料庫使用者。以至少具有 ALTER ANY USER 權限的 Microsoft Entra 身分識別，使用 SSMS 這類工具連線至您想要從中以回複製資料的資料倉儲。執行下列 T-SQL：
```
CREATE USER [your_application_name] FROM EXTERNAL PROVIDER;
```
如同您一般對 SQL 使用者或其他人所做的一樣，將所需的權限授與服務主體。執行下列程式碼，或參閱這裡的更多選項。如果您想要使用 PolyBase 來載入資料，請瞭解所需的資料庫權限。
```
EXEC sp_addrolemember db_owner, [your application name];
```
在 Azure Data Factory 或 Synapse 工作區中，設定 Azure Synapse Analytics 連結服務。

使用服務主體驗證的連結服務範例

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;Connection Timeout=30",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<application key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

系統指派的 Azure 資源的受控識別驗證

Data Factory 或 Synapse 工作區可與代表資源的 Azure 資源的系統指派受控識別相關聯。您可以使用此受控識別來進行 Azure Synapse 分析驗證。指定的資源可以使用此身分識別來存取資料倉儲和從中來回複製資料。

若要使用系統指派的受控識別驗證，請指定上一節所述的一般屬性，並依照下列步驟操作。

如果您尚未在 Azure 入口網站上，為伺服器佈建 Microsoft Entra 管理員，請加以佈建。 Microsoft Entra 管理員可以是 Microsoft Entra 使用者或 Microsoft Entra 群組。如果您為具有系統指派的受控識別的群組授與系統管理員角色，請略過步驟 3 和 4。系統管理員將擁有資料庫的完整存取權。
為系統指派的受控識別建立自主資料庫使用者。以至少具有 ALTER ANY USER 權限的 Microsoft Entra 身分識別，使用 SSMS 這類工具連線至您想要從中以回複製資料的資料倉儲。執行下列 T-SQL。
```
CREATE USER [your_resource_name] FROM EXTERNAL PROVIDER;
```
依照您平常為 SQL 使用者和其他人所進行的操作一樣，授與系統指派的受控識別所需的權限。執行下列程式碼，或參閱這裡的更多選項。如果您想要使用 PolyBase 來載入資料，請瞭解所需的資料庫權限。
```
EXEC sp_addrolemember db_owner, [your_resource_name];
```
設定 Azure Synapse Analytics 連結服務。

範例：

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SystemAssignedManagedIdentity"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

使用者指派的受控身分識別驗證

Data Factory 或 Synapse 工作區可以與代表資源的使用者指派受控識別相關聯。您可以使用此受控識別來進行 Azure Synapse 分析驗證。指定的資源可以使用此身分識別來存取資料倉儲和從中來回複製資料。

若要使用使用者指派的受控識別驗證，除了上一節所述的一般屬性外，請指定下列屬性：

屬性	描述	必要
credentials	將使用者指派的受控身分識別指定為認證物件。	Yes

此外，請依照下列步驟操作：

如果您尚未在 Azure 入口網站上，為伺服器佈建 Microsoft Entra 管理員，請加以佈建。 Microsoft Entra 管理員可以是 Microsoft Entra 使用者或 Microsoft Entra 群組。如果您為具有使用者指派的受控身分識別的群組授與系統管理員角色，請略過步驟 3。系統管理員將擁有資料庫的完整存取權。
為使用者指派的受控身分識別建立自主資料庫使用者。以至少具有 ALTER ANY USER 權限的 Microsoft Entra 身分識別，使用 SSMS 這類工具連線至您想要從中以回複製資料的資料倉儲。執行下列 T-SQL。
```
CREATE USER [your_resource_name] FROM EXTERNAL PROVIDER;
```
依照您平常為 SQL 使用者和其他人所進行的操作一樣，建立一或多個使用者指派的受控識別，並授與使用者指派的受控識別所需的權限。執行下列程式碼，或參閱這裡的更多選項。如果您想要使用 PolyBase 來載入資料，請瞭解所需的資料庫權限。
```
EXEC sp_addrolemember db_owner, [your_resource_name];
```
將一或多個使用者指派的受控身分識別指派給資料處理站，並為每個使用者指派的受控身分識別建立認證。
設定 Azure Synapse Analytics 連結服務。

範例

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "UserAssignedManagedIdentity",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

舊版

當您套用舊版時，Azure Synapse Analytics 連接服務支援這些泛型屬性：

屬性	描述	必要
type	類型屬性必須設為 AzureSqlDW。	Yes
connectionString	針對 connectionString 屬性指定連線到 Azure Synapse Analytics 執行個體所需的資訊。將此欄位標記為 SecureString 以將其安全地儲存。您也可以將密碼/服務主體金鑰放在 Azure Key Vault 中，而且，如果這是 SQL 驗證，則會從連接字串中提取 `password` 組態。如需詳細資訊，請參閱在 Azure Key Vault 中儲存認證一文。	Yes
connectVia	用來連線到資料存放區的整合執行階段。您可以使用 Azure Integration Runtime 或自我裝載整合執行階段 (如果您的資料存放區位於私人網路中)。如果未指定，就會使用預設的 Azure Integration Runtime。	No

針對不同的驗證類型，請分別參閱下列各節特定的屬性和必要條件：

舊版的 SQL 驗證
舊版的服務主體驗證
舊版系統指派的受控識別驗證
舊版使用者指派的受控識別驗證

舊版的 SQL 驗證

若要使用 SQL 驗證，請指定上一節所述的泛型屬性。

舊版的服務主體驗證

若要使用服務主體驗證，除了上一節所述的一般屬性外，請指定下列屬性：

屬性	描述	必要
servicePrincipalId	指定應用程式的用戶端識別碼。	Yes
servicePrincipalKey	指定應用程式的金鑰。將此欄位標記為 SecureString 以便安全儲存，或參考 Azure Key Vault 中儲存的祕密。	Yes
tenant	指定您的應用程式所在租用戶的資訊，例如網域名稱或租用戶識別碼。將滑鼠游標暫留在 Azure 入口網站右上角，即可加以擷取。	Yes
azureCloudType	針對服務主體驗證，請指定註冊 Microsoft Entra 應用程式的 Azure 雲端環境類型。允許的值為 AzurePublic、AzureChina、AzureUsGovernment 和 AzureGermany。預設會使用 Data Factory 或 Synapse 管線的雲端環境。	No

您也需要遵循服務主體驗證中的步驟來授與對應的授權。

舊版的系統指派受控識別驗證

如果要使用系統指派的受控識別驗證，請遵循系統指派的受控識別驗證中建議版本的相同步驟。

舊版使用者指派的受控識別驗證

如果要使用使用者指派的受控識別驗證，請遵循使用者指派的受控識別驗證中建議版本的相同步驟。

資料集屬性

如需可用來定義資料集的區段和屬性完整清單，請參閱資料集一文。

以下是 Azure Synapse Analytics 資料集支援的屬性：

屬性	描述	必要
type	資料集的類型屬性必須設定為 AzureSqlDWTable。	Yes
schema	結構描述的名稱。	否 (來源)；是 (接收)
table	資料表/檢視的名稱。	否 (來源)；是 (接收)
tableName	具有結構描述的資料表/檢視名稱。支援此屬性是基於回溯相容性。對於新的工作負載，請使用 `schema` 和 `table`。	否 (來源)；是 (接收)

資料集屬性範例

{
    "name": "AzureSQLDWDataset",
    "properties":
    {
        "type": "AzureSqlDWTable",
        "linkedServiceName": {
            "referenceName": "<Azure Synapse Analytics linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, retrievable during authoring > ],
        "typeProperties": {
            "schema": "<schema_name>",
            "table": "<table_name>"
        }
    }
}

複製活動屬性

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

Azure Synapse Analytics 做為來源

提示

若要使用分割有效率地從 Azure Synapse Analytics 載入資料，請於從 Azure Synapse Analytics 平行複製深入了解。

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

屬性	描述	必要
type	複製活動來源的類型屬性必須設定為 SqlDWSource。	Yes
sqlReaderQuery	使用自訂 SQL 查詢來讀取資料。範例：`select * from MyTable`。	No
sqlReaderStoredProcedureName	從來源資料表讀取資料的預存程序名稱。最後一個 SQL 陳述式必須是預存程序中的 SELECT 陳述式。	No
storedProcedureParameters	預存程序的參數。允許的值為名稱或值組。參數的名稱和大小寫必須符合預存程序參數的名稱和大小寫。	No
isolationLevel	指定 SQL 來源的異動鎖定行為。允許的值為：ReadCommitted、ReadUncommitted、RepeatableRead、Serializable、Snapshot。如果未指定，則會使用資料庫的預設隔離等級。如需詳細資訊，請參閱 system.data.isolationlevel。	No
partitionOptions	指定用來從 Azure Synapse Analytics 載入資料的資料分割選項。允許的值為：None (預設值)、PhysicalPartitionsOfTable 和 DynamicRange。啟用分割區選項後 (即不是 `None`)，從 Azure Synapse Analytics 並行載入資料的平行程度，會由複製活動的 `parallelCopies` 設定所控制。	No
partitionSettings	指定資料分割的設定群組。當分割選項不是 `None` 時套用。	No
在 `partitionSettings` 下方：
partitionColumnName	以整數類型或日期/日期時間類型 (`int`、`smallint`、`bigint`、`date`、`smalldatetime`、`datetime`、`datetime2` 或 `datetimeoffset`) 指定來源資料行的名稱，供平行複製的範圍分割使用。如果未指定，則會自動偵測資料表的索引或主索引鍵作為分割資料行。當分割選項是 `DynamicRange` 時套用。如果您使用查詢來取出來源資料，請在 WHERE 子句中加上 `?DfDynamicRangePartitionCondition` 。如需範例，請參閱從 SQL 資料庫平行複製一節。	No
partitionUpperBound	分割區範圍分割的分割區資料行最大值。這個值用於決定分割區的跨距，而不是用於篩選資料表中的資料列。資料表或查詢結果中的所有資料列都會進行分割和複製。如果未指定，複製活動會自動偵測該值。當分割選項是 `DynamicRange` 時套用。如需範例，請參閱從 SQL 資料庫平行複製一節。	No
partitionLowerBound	分割區範圍分割的分割區資料行最小值。這個值用於決定分割區的跨距，而不是用於篩選資料表中的資料列。資料表或查詢結果中的所有資料列都會進行分割和複製。如果未指定，複製活動會自動偵測該值。當分割選項是 `DynamicRange` 時套用。如需範例，請參閱從 SQL 資料庫平行複製一節。	No

請注意下列幾點：

在來源中使用預存程序來擷取資料時，請注意，如果您的預存程序設計為在傳入不同的參數值時傳回不同的結構描述，在從 UI 匯入結構描述，或使用自動資料表建立將資料複製到 SQL 資料庫時，您可能遇到失敗，或看到非預期的結果。

範例：使用 SQL 查詢

"activities":[
    {
        "name": "CopyFromAzureSQLDW",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure Synapse Analytics input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlDWSource",
                "sqlReaderQuery": "SELECT * FROM MyTable"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

範例：使用預存程序

"activities":[
    {
        "name": "CopyFromAzureSQLDW",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure Synapse Analytics input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlDWSource",
                "sqlReaderStoredProcedureName": "CopyTestSrcStoredProcedureWithParameters",
                "storedProcedureParameters": {
                    "stringData": { "value": "str3" },
                    "identifier": { "value": "$$Text.Format('{0:yyyy}', <datetime parameter>)", "type": "Int"}
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

範例預存程序：

CREATE PROCEDURE CopyTestSrcStoredProcedureWithParameters
(
    @stringData varchar(20),
    @identifier int
)
AS
SET NOCOUNT ON;
BEGIN
    select *
    from dbo.UnitTestSrcTable
    where dbo.UnitTestSrcTable.stringData != stringData
    and dbo.UnitTestSrcTable.identifier != identifier
END
GO

Azure Synapse Analytics 做為接收

Azure Data Factory 和 Synapse 管線支援將資料載入 Azure Synapse Analytics 的三個方式。

使用 COPY 陳述式
使用 PolyBase
使用大量插入

載入資料的最快速且可調整的方式是透過 COPY 陳述式或 PolyBase。

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

屬性	描述	必要
type	複製活動接收端的類型屬性必須設定為 SqlDWSink。	Yes
allowPolyBase	指出是否使用 PolyBase 將資料載入 Azure Synapse Analytics。 `allowCopyCommand` 和 `allowPolyBase` 不可同時為 true。如需限制式和詳細資料，請參閱使用 PolyBase 將資料載入 Azure Synapse Analytics 一節。允許的值為 True 和 False (預設值)。	否。使用 PolyBase 時套用。
polyBaseSettings	可以在 `allowPolybase` 屬性設定為 true 時指定的一組屬性。	否。使用 PolyBase 時套用。
allowCopyCommand	指出是否使用 COPY 陳述式將資料載入 Azure Synapse Analytics。 `allowCopyCommand` 和 `allowPolyBase` 不可同時為 true。如需限制式和詳細資料，請參閱使用 COPY 陳述式將資料載入 Azure Synapse Analytics 一節。允許的值為 True 和 False (預設值)。	否。使用 COPY 時適用。
copyCommandSettings	可以在 `allowCopyCommand` 屬性設定為 TRUE 時指定的一組屬性。	否。使用 COPY 時適用。
writeBatchSize	對於每個批次要插入 SQL 資料表中的資料列數。允許的值為整數 (資料列數目)。根據預設，服務會依據資料列大小動態決定適當的批次大小。	否。使用 bulk insert 時適用。
writeBatchTimeout	在逾時之前等待插入、upsert 和預存程式作業完成的時間。允許的值為時間範圍。例如 “00:30:00” 為 30 分鐘。如果未指定任何值，逾時預設為 "00:30:00"。	否。使用 bulk insert 時適用。
preCopyScript	指定一個供複製活動在每次執行時將資料寫入到 Azure Synapse Analytics 前執行的 SQL 查詢。使用此屬性來清除預先載入的資料。	No
tableOption	指定是否要根據來源結構描述，自動建立接收資料表 (如果不存在)。允許的值包為：`none` (預設) 或 `autoCreate`。	No
disableMetricsCollection	該服務會收集計量，例如 Azure Synapse Analytics DWU，以獲得複製效能最佳化和建議，而這會導致額外的主要 DB 存取。如果您擔心此行為，請指定 `true` 將其關閉。	否 (預設值為 `false`)
maxConcurrentConnections	在活動執行期間建立至資料存放區的同時連線上限。僅在想要限制並行連線時，才需要指定值。	否
WriteBehavior	指定複製活動將資料載入 Azure Synapse Analytics 的寫入行為。允許的值為 Insert 和 Upsert。根據預設，服務會使用 Insert 載入資料。	No
upsertSettings	指定寫入行為的設定群組。當 WriteBehavior 選項為 `Upsert` 時套用。	No
在 `upsertSettings` 下方：
金鑰	指定唯一資料列識別的資料行名稱。您可以使用單一索引鍵或一系列索引鍵。如果未指定，則會使用主索引鍵。	No
interimSchemaName	指定用於建立過渡資料表的過渡結構描述。注意：使用者必須具有建立和刪除資料表的權限。根據預設，過渡資料表會與接收資料表共用相同的結構描述。	No

範例 1：Azure Synapse Analytics 接收

"sink": {
    "type": "SqlDWSink",
    "allowPolyBase": true,
    "polyBaseSettings":
    {
        "rejectType": "percentage",
        "rejectValue": 10.0,
        "rejectSampleValue": 100,
        "useTypeDefault": true
    }
}

範例 2：Upsert 資料

"sink": {
    "type": "SqlDWSink",
    "writeBehavior": "Upsert",
    "upsertSettings": {
        "keys": [
             "<column name>"
        ],
        "interimSchemaName": "<interim schema name>"
    },
}

從 Azure Synapse Analytics 平行複製

複製活動中 Azure Synapse Analytics 連接器提供內建的資料分割，以平行複製資料。您可以在複製活動的 [來源] 索引標籤上找到資料分割選項。

分割選項的螢幕擷取畫面

當您啟用分割複本時，複製活動會平行查詢 Azure Synapse Analytics 來源，以依分割區來載入資料。平行程度由複製活動的 parallelCopies 設定所控制。例如，如果您將 parallelCopies 設定為四，服務會根據您指定的分割區選項和設定，同時產生並執行四個查詢，而每個查詢會從 Azure Synapse Analytics 資料庫取擷取一部分資料。

建議您啟用平行複製與資料分割，特別是從 Azure Synapse Analytics 資料庫載入大量資料時。以下針對各種情節的建議設定。將資料複製到以檔案為基礎的資料存放區時，建議分成多個檔案來寫入資料夾 (僅指定資料夾名稱)，這樣效能會比寫入單一檔案更好。

案例	建議的設定
使用實體分割區從大型資料表完整載入。	分割選項：資料表的實體分割區。在執行期間，服務會自動偵測實體分割區，並依分割區複製資料。若要檢查您的資料表是否有實體分割區，您可以參考此查詢。
從大型資料表完整載入，不含實體分割區，同時在資料分割時包含整數或日期時間資料行。	分割選項：動態範圍分割。分割資料行 (選用)：指定用來分割資料的資料行。如果未指定，則會使用索引或主索引鍵資料行。分割區上限和分割區下限 (選用)：指定是否要決定分割區跨距。這不適用於篩選資料表中的資料列，資料表中的所有資料列都會分割並複製。如果未指定，複製活動會自動偵測值。例如，如果您的分割區資料行「識別碼」具有範圍 1 到 100 之間的值，而您將下限設定為 20、上限設定為 80，且平行複製為 4，則服務會分別依 4 個分割區擷取資料 - 範圍中的識別碼分別為 <=20、[21, 50]、[51, 80] 和 >=81。
使用自訂查詢載入大量資料，不使用實體分割區，同時包含整數或日期/日期時間資料行用於資料分割。	分割選項：動態範圍分割。查詢：`SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>`。分割資料行：指定用來分割資料的資料行。分割區上限和分割區下限 (選用)：指定是否要決定分割區跨距。這不適用於篩選資料表中的資料列，查詢結果中的所有資料列都會分割並複製。如果未指定，複製活動會自動偵測該值。例如，如果您的分割區資料行「識別碼」具有範圍 1 到 100 之間的值，而您將下限設定為 20、上限設定為 80，且平行複製為 4，則服務會分別依 4 個分割區擷取資料 - 範圍中的識別碼分別為 <=20、[21, 50]、[51, 80] 和 >=81。以下是不同案例的更多範例查詢： 1.查詢整個資料表： `SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition` 2.來自具有資料行選取範圍和其他 where 子句篩選的資料表查詢： `SELECT <column_list> FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>` 3.使用子查詢進行查詢： `SELECT <column_list> FROM (<your_sub_query>) AS T WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>` 4.在子查詢中使用分割區進行查詢： `SELECT <column_list> FROM (SELECT <your_sub_query_column_list> FROM <TableName> WHERE ?DfDynamicRangePartitionCondition) AS T`

使用分割區選項載入資料的最佳做法：

選擇獨特的資料行作為分割資料行 (例如主索引鍵或唯一索引鍵) 以避免資料扭曲。
如果資料表有內建分割區，請使用分割選項「資料表的實體分割區」，以獲得更佳的效能。
如果您使用 Azure Integration Runtime 來複製資料，您可以設定較大的「資料整合單位 (DIU)」(>4) 來利用更多運算資源。檢查該處適用的案例。
「複製平行處理原則的程度」會控制分割區數目，將此數目設定過大有時會損害效能，建議將此數目設定為 (DIU 或自我裝載 IR 節點數目) * (2 到 4)。
請注意，Azure Synapse Analytics 一次最多可以執行 32 個查詢，將「複製平行處理原則的程度」設定過大可能會導致 Synapse 節流問題。

範例：使用實體分割區從大型資料表完整載入

"source": {
    "type": "SqlDWSource",
    "partitionOption": "PhysicalPartitionsOfTable"
}

範例：使用動態範圍分割進行查詢

"source": {
    "type": "SqlDWSource",
    "query": "SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>",
    "partitionOption": "DynamicRange",
    "partitionSettings": {
        "partitionColumnName": "<partition_column_name>",
        "partitionUpperBound": "<upper_value_of_partition_column (optional) to decide the partition stride, not as data filter>",
        "partitionLowerBound": "<lower_value_of_partition_column (optional) to decide the partition stride, not as data filter>"
    }
}

用來檢查實體分割區的範例查詢

SELECT DISTINCT s.name AS SchemaName, t.name AS TableName, c.name AS ColumnName, CASE WHEN c.name IS NULL THEN 'no' ELSE 'yes' END AS HasPartition
FROM sys.tables AS t
LEFT JOIN sys.objects AS o ON t.object_id = o.object_id
LEFT JOIN sys.schemas AS s ON o.schema_id = s.schema_id
LEFT JOIN sys.indexes AS i ON t.object_id = i.object_id
LEFT JOIN sys.index_columns AS ic ON ic.partition_ordinal > 0 AND ic.index_id = i.index_id AND ic.object_id = t.object_id
LEFT JOIN sys.columns AS c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
LEFT JOIN sys.types AS y ON c.system_type_id = y.system_type_id
WHERE s.name='[your schema]' AND t.name = '[your table name]'

如果資料表具有實體分割區，您會看到 "HasPartition" 為 "yes"。

使用 COPY 陳述式將資料載入 Azure Synapse Analytics

使用 COPY 陳述式是一種簡單且有彈性的方式，可透過高輸送量將資料載入 Azure Synapse Analytics。若要深入了解詳細資料，請查看使用 COPY 陳述式大量載入資料

如果您的來源資料位於 Azure Blob 或 Azure Data Lake Storage Gen2 中，而且格式與 COPY 陳述式相容，您可以使用複製活動直接叫用 COPY 陳述式，讓 Azure Synapse Analytics 從來源提取資料。如需詳細資料，請參閱使用 COPY 陳述式直接複製。
如果您的來源資料存放區與格式不受 COPY 陳述式支援，您可以改用使用 COPY 陳述式分段複製功能。分段複製功能也能提供更好的輸送量。它會自動將資料轉換成 COPY 陳述式相容格式、將資料儲存在 Azure Blob 儲存體中，然後呼叫 COPY 陳述式，以將資料載入 Azure Synapse Analytics。

提示

使用 COPY 陳述式搭配 Azure Integration Runtime 時，有效的資料整合單位 (DIU) 一律為 2。調整 DIU 不會影響效能，因為從儲存體載入資料是由 Azure Synapse 引擎所提供。

使用 COPY 陳述式直接複製

Azure Synapse Analytics COPY 陳述式直接支援 Azure Blob 和 Azure Data Lake Storage Gen2。如果您的來源資料符合本節所述準則，即可使用 COPY 陳述式從來源資料存放區直接複製到 Azure Synapse Analytics。否則，請運用使用 COPY 陳述式分段複製。該服務會檢查設定，並在不符合準則時讓複製活動執行失敗。

來源連結服務和格式使用下列類型和驗證方法：

支援的來源資料存放區類型	支援的格式	支援的來源驗證類型
Azure Blob	分隔符號文字	帳戶金鑰驗證、共用存取簽章驗證、服務主體驗證 (使用 ServicePrincipalKey)、系統指派的受控識別驗證
	Parquet	帳戶金鑰驗證、共用存取簽章驗證
	ORC	帳戶金鑰驗證、共用存取簽章驗證
Azure Data Lake Storage Gen2 \(部分機器翻譯\)	分隔符號文字 Parquet ORC	帳戶金鑰驗證、服務主體驗證 (使用 ServicePrincipalKey)、共用存取簽章驗證、系統指派的受控識別驗證

重要

當您針對儲存體連結服務使用受控識別驗證時，請分別了解 Azure Blob 和 Azure Data Lake Storage Gen2 所需的設定。
如果您的 Azure 儲存體設定了 VNet 服務端點，您必須使用受控識別驗證並將儲存體帳戶上的「允許受信任的 Microsoft 服務」開啟，請參閱使用 VNet 服務端點搭配 Azure 儲存體的影響。

格式設定使用下列各項︰
1. 對於 Parquet：compression可以是不壓縮、Snappy 或 GZip。
2. 對於 ORC：compression可以是不壓縮、zlib 或 Snappy。
3. 對於分隔符號文字：
  1. rowDelimiter明確設定為單一字元或「\r\n」，不支援預設值。
  2. nullValue 會保留為預設值，或設定為空字串 ("")。
  3. encodingName 會保留為預設值，或設定為 utf-8 或 utf-16。
  4. escapeChar 必須與 quoteChar 相同，而且不是空的。
  5. skipLineCount 會保留為預設值或設定為 0。
  6. compression 可以是不壓縮或 GZip。
如果您的來源是資料夾，則複製活動中的 recursive 必須設定為 true，而且 wildcardFilename 必須是 * 或 *.*。
未指定 wildcardFolderPath、wildcardFilename (* 或 *.* 以外)、modifiedDateTimeStart、modifiedDateTimeEnd、prefix、enablePartitionDiscovery 和 additionalColumns。

在複製活動的 allowCopyCommand 下支援下列 COPY 陳述式設定：

屬性	描述	必要
defaultValues	指定 Azure Synapse Analytics 中每個目標資料行的預設值。屬性中的預設值會覆寫資料倉儲中設定的預設條件約束，而且識別欄位不可有預設值。	No
additionalOptions	在 COPY 陳述式的 "With" 子句中將直接傳遞至 Azure Synapse Analytics COPY 陳述式的其他選項。視需要將值加上引號，以配合 COPY 陳述式需求。	No

"activities":[
    {
        "name": "CopyFromAzureBlobToSQLDataWarehouseViaCOPY",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "ParquetDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ParquetSource",
                "storeSettings":{
                    "type": "AzureBlobStorageReadSettings",
                    "recursive": true
                }
            },
            "sink": {
                "type": "SqlDWSink",
                "allowCopyCommand": true,
                "copyCommandSettings": {
                    "defaultValues": [
                        {
                            "columnName": "col_string",
                            "defaultValue": "DefaultStringValue"
                        }
                    ],
                    "additionalOptions": {
                        "MAXERRORS": "10000",
                        "DATEFORMAT": "'ymd'"
                    }
                }
            },
            "enableSkipIncompatibleRow": true
        }
    }
]

使用 COPY 陳述式分段複製

當您的來源資料與 COPY 陳述式未原生相容時，可透過過渡分段 Azure Blob 或 Azure Data Lake Storage Gen2 (不可以是 Azure 進階儲存體) 來啟用資料複製。在此情況下，該服務會自動轉換資料，以符合 COPY 陳述式的資料格式需求。然後它會叫用 COPY 陳述式，將資料載入至 Azure Synapse Analytics。最後，它會清除儲存體中的暫存資料。如需透過分段複製資料的詳細資料，請參閱分段複製。

若要使用此功能，請使用帳戶金鑰或系統受控識別驗證，來建立 Azure Blob 儲存體連結服務或 Azure Data Lake Storage Gen2 連結服務，其將 Azure 儲存體帳戶稱為過渡儲存體。

重要

當您針對分段連結服務使用受控識別驗證時，請分別了解 Azure Blob 和 Azure Data Lake Storage Gen2 所需的設定。您也需要將權限授與暫存 Azure Blob 儲存體中的 Azure Synapse Analytics 工作區受控識別，或 Azure Data Lake Storage Gen2 帳戶。若要了解如何授與此權限，請參閱將權限授與工作區受控識別。
如果您的分段 Azure 儲存體已設定 VNet 服務端點，您必須使用受控識別驗證並將儲存體帳戶上的「允許受信任的 Microsoft 服務」開啟，請參閱使用 VNet 服務端點搭配 Azure 儲存體的影響。

重要

如果您的分段 Azure 儲存體已設定受控私人端點，且已啟用儲存體防火牆，您必須使用受控識別驗證，並將儲存體 Blob 資料讀取者權限授與 Synapse SQL Server，以確保它可以在 COPY 陳述式載入期間存取分段的檔案。

"activities":[
    {
        "name": "CopyFromSQLServerToSQLDataWarehouseViaCOPYstatement",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "SQLServerDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlSource",
            },
            "sink": {
                "type": "SqlDWSink",
                "allowCopyCommand": true
            },
            "stagingSettings": {
                "linkedServiceName": {
                    "referenceName": "MyStagingStorage",
                    "type": "LinkedServiceReference"
                }
            }
        }
    }
]

使用 PolyBase 將資料載入至 Azure Synapse Analytics

使用 PolyBase 是以高輸送量將大量資料載入 Azure Synapse Analytics 的有效方法。使用 PolyBase 而不是預設的 BULKINSERT 機制，將可看到輸送量大幅提升。

如果您的來源資料位於 Azure Blob 或 Azure Data Lake Storage Gen2 中，而且格式與 PolyBase 相容，您可以使用複製活動直接叫用 PolyBase，讓 Azure Synapse Analytics 從來源提取資料。如需詳細資料，請參閱使用 PolyBase 直接複製。
如果您的來源資料存放區與格式不受 PolyBase 支援，您可以改用使用 PolyBase 分段複製功能。分段複製功能也能提供更好的輸送量。它會自動將資料轉換成與 PolyBase 相容的格式，將資料儲存在 Azure Blob 儲存體中，然後呼叫 PolyBase 以將資料載入 Azure Synapse Analytics。

提示

深入瞭解使用 PolyBase 的最佳做法。使用 PolyBase 搭配 Azure Integration Runtime 時，對 Synapse 的直接或分段儲存體的有效資料整合單位 (DIU) 一律為 2。調整 DIU 不會影響效能，因為從儲存體載入資料是由 Synapse 引擎所提供。

在複製活動的 polyBaseSettings 下支援下列 PolyBase 設定：

屬性	描述	必要
rejectValue	指定在查詢失敗前可以拒絕的資料列數目或百分比。在 CREATE EXTERNAL TABLE (Transact-SQL)的＜引數＞一節中，深入瞭解 PolyBase 的拒絕選項。允許的值為 0 (預設值)、1、2 等其他值。	No
rejectType	指定 rejectValue 選項為常值或百分比。允許的值為值 (預設值) 和百分比。	No
rejectSampleValue	決定在 PolyBase 重新計算已拒絕的資料列百分比之前，所要擷取的資料列數目。允許的值為 1、2 等其他值。	是，如果 rejectType 是百分比。
useTypeDefault	指定當 PolyBase 從文字檔擷取資料時，如何處理分隔符號文字檔中遺漏的值。從 CREATE EXTERNAL FILE FORMAT (Transact-SQL) 的＜引數＞一節深入了解這個屬性。允許的值為 True 和 False (預設值)。	No

使用 PolyBase 直接複製

Azure Synapse Analytics PolyBase 陳述式直接支援 Azure Blob 和 Azure Data Lake Storage Gen2。如果您的來源資料符合本節所述準則，即可使用 PolyBase 從來源資料存放區直接複製到 Azure Synapse Analytics。否則，請利用使用 PolyBase 分段複製。

提示

若要有效率地將資料複製到 Azure Synapse Analytics，請透過使用 Data Lake Store 搭配 Azure Synapse Analytics 時，Azure Data Factory 讓您更輕鬆便利地發掘來自資料的深入解析深入了解。

如果不符合需求，該服務會檢查設定，並自動切換回適合資料移動的 BULKINSERT 機制。

來源連結服務使用下列類型和驗證方法：

支援的來源資料存放區類型	支援的來源驗證類型
Azure Blob	帳戶金鑰驗證、系統指派的受控識別驗證
Azure Data Lake Storage Gen2 \(部分機器翻譯\)	帳戶金鑰驗證、系統指派的受控識別驗證

重要

當您針對儲存體連結服務使用受控識別驗證時，請分別了解 Azure Blob 和 Azure Data Lake Storage Gen2 所需的設定。
如果您的 Azure 儲存體設定了 VNet 服務端點，您必須使用受控識別驗證並將儲存體帳戶上的「允許受信任的 Microsoft 服務」開啟，請參閱使用 VNet 服務端點搭配 Azure 儲存體的影響。

來源資料格式是 Parquet、ORC 或分隔的文字，並具有下列設定：
1. 資料夾路徑不包含萬用字元篩選條件。
2. 檔案名稱是空的，或指向單一檔案。如果您在複製活動中指定萬用字元檔案名稱，則只能是 * 或 *.*。
3. rowDelimiter 是預設值、\n、\r\n 或 \r。
4. nullValue 會保留預設值或設定為空字串 ("")，而 treatEmptyAsNull 則保留預設值或設定為 true。
5. encodingName 會保留為預設值，或設定為 utf-8。
6. 未指定 quoteChar、escapeChar 與 skipLineCount。 PolyBase 支援略過標頭列，這在可設定為 firstRowAsHeader。
7. compression 可以是不壓縮、GZip 或 Deflate。
如果您的來源是資料夾，則複製活動中的 recursive 必須設定為 true。
wildcardFolderPath、wildcardFilename、modifiedDateTimeStart、modifiedDateTimeEnd、prefix、enablePartitionDiscovery 和 additionalColumns 未指定。

注意

如果您的來源是資料夾，請注意 PolyBase 會從資料夾及其所有子資料夾擷取檔案，而且不會從檔案名稱開頭為底線 (_) 或句號 (.) 的檔案中擷取資料，如這裡 - LOCATION 引數所述。

"activities":[
    {
        "name": "CopyFromAzureBlobToSQLDataWarehouseViaPolyBase",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "ParquetDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ParquetSource",
                "storeSettings":{
                    "type": "AzureBlobStorageReadSettings",
                    "recursive": true
                }
            },
            "sink": {
                "type": "SqlDWSink",
                "allowPolyBase": true
            }
        }
    }
]

使用 PolyBase 分段複製

當您的來源資料與 PolyBase 未原生相容時，可透過過渡分段 Azure Blob 或 Azure Data Lake Storage Gen2 (不可以是 Azure 進階儲存體) 來啟用資料複製。在此情況下，該服務會自動轉換資料，以符合 PolyBase 的資料格式需求。然後它會叫用 PolyBase 以將資料載入至 Azure Synapse Analytics。最後，它會清除儲存體中的暫存資料。如需透過分段複製資料的詳細資料，請參閱分段複製。

若要使用此功能，請使用帳戶金鑰或受控識別驗證，來建立 Azure Blob 儲存體連結服務或 Azure Data Lake Storage Gen2 連結服務，其將 Azure 儲存體帳戶稱為過渡儲存體。

重要

當您針對分段連結服務使用受控識別驗證時，請分別了解 Azure Blob 和 Azure Data Lake Storage Gen2 所需的設定。您也需要將權限授與暫存 Azure Blob 儲存體中的 Azure Synapse Analytics 工作區受控識別，或 Azure Data Lake Storage Gen2 帳戶。若要了解如何授與此權限，請參閱將權限授與工作區受控識別。
如果您的分段 Azure 儲存體已設定 VNet 服務端點，您必須使用受控識別驗證並將儲存體帳戶上的「允許受信任的 Microsoft 服務」開啟，請參閱使用 VNet 服務端點搭配 Azure 儲存體的影響。

重要

如果您的分段 Azure 儲存體已設定受控私人端點，且已啟用儲存體防火牆，您必須使用受控識別驗證，並將儲存體 Blob 資料讀取者權限授與 Synapse SQL Server，以確保它可以在 PolyBase 載入期間存取分段的檔案。

"activities":[
    {
        "name": "CopyFromSQLServerToSQLDataWarehouseViaPolyBase",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "SQLServerDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlSource",
            },
            "sink": {
                "type": "SqlDWSink",
                "allowPolyBase": true
            },
            "enableStaging": true,
            "stagingSettings": {
                "linkedServiceName": {
                    "referenceName": "MyStagingStorage",
                    "type": "LinkedServiceReference"
                }
            }
        }
    }
]

使用 PolyBase 的最佳做法

除了 Azure Synapse Analytics 的最佳做法中所述的方法外，下列小節也提供最佳做法。

必要的資料庫權限

若要使用 PolyBase，將資料載入 Azure Synapse Analytics 的使用者必須具備目標資料庫的 "CONTROL" 權限。達到此目標的其中一個方法是將該使用者新增為 db_owner 角色的成員。在 Azure Synapse Analytics 概觀中了解如何執行該動作。

資料列大小和資料類型限制

PolyBase 負載的限制為小於 1 MB 的資料列。這無法用來載入 VARCHR(MAX)、NVARCHAR(MAX) 或 VARBINARY(MAX)。如需詳細資訊，請參閱 Azure Synapse Analytics 服務容量限制。

當您來源資料中的資料列大於 1 MB 時，您可能要將來源資料表垂直分割成幾個小的資料表。務必確認每一列的大小不會超過限制。然後可以使用 PolyBase 載入較小的資料表，並且在 Azure Synapse Analytics 中將其合併在一起。

或者，對於具有這類寬資料行的資料，您可以藉由關閉「允許 PolyBase」設定，使用非 PolyBase 來載入資料。

Azure Synapse Analytics 資源類別

若要達到最佳的可能輸送量，請將較大型資源類別指派給會透過 PolyBase 將資料載入 Azure Synapse Analytics 的使用者。

PolyBase, 疑難排解

載入至 Decimal 資料行

如果您的來源資料為文字格式或其他非 PolyBase 相容存放區 (使用分段複製和 PolyBase)，而且其中包含要載入 Azure Synapse Analytics Decimal 資料行中的空白值，您可能會遇到下列錯誤：

ErrorCode=FailedDbOperation, ......HadoopSqlException: Error converting data type VARCHAR to DECIMAL.....Detailed Message=Empty string can't be converted to DECIMAL.....

解決方法是在複製活動接收中取消選取 [使用類型預設] 選項 (為 false) -> [PolyBase 設定]。「USE_TYPE_DEFAULT」是 PolyBase原生設定，會指定當 PolyBase 從文字檔擷取資料時，如何處理分隔符號文字檔中遺漏的值。

檢查 Azure Synapse Analytics 中的 tableName 屬性

下表是如何在 JSON 資料集中指定 tableName 屬性的範例。其中會顯示數個結構描述和資料表名稱的組合。

DB 結構描述	資料表名稱	tableName JSON 屬性
dbo	MyTable	MyTable 或 dbo.MyTable 或 [dbo].[MyTable]
dbo1	MyTable	dbo1.MyTable 或 [dbo1].[MyTable]
dbo	My.Table	[My.Table] 或 [dbo].[My.Table]
dbo1	My.Table	[dbo1].[My.Table]

如果您看到下列錯誤，可能是您為 tableName 屬性指定的值有問題。請參閱前面的資料表，以正確的方式指定 tableName JSON 屬性的值。

Type=System.Data.SqlClient.SqlException,Message=Invalid object name 'stg.Account_test'.,Source=.Net SqlClient Data Provider

包含預設值的資料行

PolyBase 功能目前只接受與目標資料表中相同的資料行數目。範例是內含四個資料行的資料表，且其中一個資料行已使用預設值進行定義。輸入資料仍需要有四個資料行。 3 個資料行的輸入資料集會產生類似下列訊息的錯誤︰

All columns of the table must be specified in the INSERT BULK statement.

NULL 值是一種特殊形式的預設值。如果資料欄可以是 Null，Blob 中該欄的輸入資料可能會是空白。但輸入資料集中不能缺少輸入資料。 PolyBase 會在 Azure Synapse Analytics 中為遺漏值插入 NULL。

外部檔案存取失敗

如果您收到下列錯誤，請確保您使用受控識別驗證，並已將儲存體 Blob 資料讀取者權限授與 Azure Synapse 工作區的受控識別。

Job failed due to reason: at Sink '[SinkName]': shaded.msdataflow.com.microsoft.sqlserver.jdbc.SQLServerException: External file access failed due to internal error: 'Error occurred while accessing HDFS: Java exception raised on call to HdfsBridge_IsDirExist. Java exception message:\r\nHdfsBridge::isDirExist

如需詳細資訊，請參閱建立工作區後將權限授與受控識別。

對應資料流程屬性

在對應資料流程中轉換資料時，您可以從 Azure Synapse 分析讀取和寫入資料表。如需詳細資訊，請參閱對應資料流程中的來源轉換和接收轉換。

來源轉換

您可以在來源轉換的 [來源選項] 索引標籤中找到 Azure Synapse 分析的特定設定。

輸入選取您是要將來源指向資料表 (相當於 Select * from <table-name>) 或輸入自訂的 SQL 查詢。

啟用分段 強烈建議您在生產工作負載中使用此選項搭配 Azure Synapse Analytics 來源。執行資料流程活動搭配來自管線的 Azure Synapse Analytics 來源，將提示您輸入分段位置儲存體帳戶，並會將其用於分段資料載入。這是從 Azure Synapse Analytics 載入資料最快的機制。

當您針對儲存體連結服務使用受控識別驗證時，請分別了解 Azure Blob 和 Azure Data Lake Storage Gen2 所需的設定。
如果您的 Azure 儲存體設定了 VNet 服務端點，您必須使用受控識別驗證並將儲存體帳戶上的「允許受信任的 Microsoft 服務」開啟，請參閱使用 VNet 服務端點搭配 Azure 儲存體的影響。
使用 Azure Synapse 無伺服器 SQL 集區作為來源時，不支援啟用分段。

查詢：如果您在 [輸入] 欄位中選取 [查詢]，請對於來源輸入 SQL 查詢。此設定會覆寫您在資料集中選擇的任何資料表。這裡不支援 Order By 子句，但您可以設定完整的 SELECT FROM 陳述式。您也可使用使用者定義的資料表函數。 select * from udfGetData() 是 SQL 中傳回資料表的 UDF。此查詢會產生您可以在資料流程中使用的來源資料表。使用查詢也是縮減資料列以進行測試或查閱的絕佳方式。

SQL 範例：Select * from MyTable where customerId > 1000 and customerId < 2000

批次大小：輸入批次大小，將大型資料區塊化為讀取。在資料流程中，此設定將用來設定 Spark 單欄式快取。這是選項欄位，如果將其保留空白，則會使用 Spark 預設值。

隔離等級：對應資料流程中 SQL 來源的預設值為「未認可」。您可以在這裡將隔離等級變更為下列其中一個值：

讀取認可
讀取未認可
可重複讀取
可序列化
None (忽略隔離等級)

隔離等級

接收轉換

您可以在接收轉換的 [設定] 索引標籤中找到 Azure Synapse 分析的特定設定。

Update 方法：決定您的資料庫目的地所允許的作業。預設僅允許插入。若要更新、upsert 或刪除資料列，必須使用 alter-row 轉換來標記這些動作的資料列。對於更新、更新插入和刪除，必須設定索引鍵資料行，以決定要改變哪一個資料列。

資料表動作： 決定在寫入之前，是否要重新建立或移除目的地資料表中的所有資料列。

無：資料表不會執行任何動作。
重新建立：資料表會遭到捨棄並重新建立。如果要動態建立新的資料表，則為必要。
截斷：系統將會移除目標資料表中的所有資料列。

啟用暫存：這可讓您使用 copy 命令載入至 Azure Synapse Analytics SQL 集區，並且是多數 Synpase 接收的建議選項。分段儲存體是在執行資料流程活動中設定。

當您針對儲存體連結服務使用受控識別驗證時，請分別了解 Azure Blob 和 Azure Data Lake Storage Gen2 所需的設定。
如果您的 Azure 儲存體設定了 VNet 服務端點，您必須使用受控識別驗證並將儲存體帳戶上的「允許受信任的 Microsoft 服務」開啟，請參閱使用 VNet 服務端點搭配 Azure 儲存體的影響。

批次大小：控制要在每個貯體中寫入的資料列數目。較大的批次大小會改善壓縮和記憶體優化，但會導致在快取資料時發生記憶體例外狀況的風險。

使用接收結構描述：根據預設，系統會在接收結構描述下建立暫存資料表，並將其作為暫存處理序。或者，您也可以取消核取 [使用接收結構描述] 選項，並在 [選取使用者資料庫結構描述] 中指定一個結構描述名稱，讓 Data Factory 建立暫存表格以便載入上游資料，並在完成時自動將其清除。請確定您的資料庫中具有建立資料表的權限，以及改變結構描述的權限。

螢幕擷取畫面顯示資料流程「使用接收結構描述」。

前置和後置 SQL 指令碼：輸入將在寫入至您的接收資料庫之前 (前置處理) 和之後 (後置處理) 將執行的多行 SQL 指令碼

螢幕擷取畫面顯示在 Azure Synapse Analytics 資料流程中，前期與後期的 SQL 流程指令碼。

提示

建議將含有多個命令的單一批次指令碼分成多個批次。
只有傳回簡單更新計數的資料定義語言 (DDL) 和資料操作語言 (DML) 陳述式可以當作批次的一部份來執行。若要深入了解，請參閱執行批次作業

處理資料列時發生錯誤

寫入至 Azure Synapse Analytics 時，某些資料列可能會因為目的地設定的限制式集而失敗。常見錯誤包括：

資料表中的字串或二進位資料會遭到截斷
無法將 NULL 值插入資料行
將值轉換成資料類型時轉換失敗

根據預設，資料流程執行會在它遇到的第一個錯誤時失敗。您可以選擇 [發生錯誤時繼續]，讓您的資料流程即使在個別資料列發生錯誤時也能夠完成。該服務會提供不同的選項，讓您處理這些錯誤資料列。

交易認可：選擇您的資料是以單一交易或批次寫入。單一交易可提供較佳的效能，而且在交易完成之前，其他人看不到寫入的資料。批次交易的效能較差，但可用於大型資料集。

輸出拒絕的資料：如果啟用，則可以將錯誤資料列輸出至 Azure Blob 儲存體中的 csv 檔案或您選擇的 Azure Data Lake Storage Gen2 帳戶。這會寫入含有三個額外資料行的錯誤資料列：INSERT 或 UPDATE 之類的 SQL 作業、資料流程錯誤碼，以及資料列上的錯誤訊息。

發生錯誤時回報成功：如果啟用，即使找到發生錯誤的資料列，資料流程也會標示為成功。

此圖顯示對應資料流程接收器轉換中的錯誤資料列處理。

查閱活動屬性

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

GetMetadata 活動屬性

若要了解關於屬性的詳細資料，請參閱 GetMetadata 活動

Azure Synapse Analytics 的資料類型對應

從 Azure Synapse Analytics 複製資料或將資料複製到該處時，會使用下列從 Azure Synapse Analytics 資料類型對應到 Azure Data Factory 過渡期資料類型的對應。使用 Synapse 管線往返 Azure Synapse Analytics 複製資料時，也會使用這些對應，因為管線也會在 Azure Synapse 內實作 Azure Data Factory。請參閱結構描述和資料類型對應，以了解複製活動如何將來源結構描述和資料類型對應至接收。

提示

如需 Azure Synapse Analytics 支援的資料類型以及對於不支援的資料類型提供的因應措施，請參閱 Azure Synapse Analytics 中的資料表資料類型一文。

Azure Synapse Analytics 資料類型	Data Factory 過渡期資料類型
BIGINT	Int64
BINARY	Byte[]
bit	Boolean
char	String, Char[]
date	Datetime
Datetime	Datetime
datetime2	Datetime
Datetimeoffset	DateTimeOffset
Decimal	Decimal
FILESTREAM attribute (varbinary(max))	Byte[]
Float	Double
image	Byte[]
int	Int32
money	Decimal
NCHAR	String, Char[]
NUMERIC	Decimal
NVARCHAR	String, Char[]
real	Single
rowversion	Byte[]
smalldatetime	Datetime
SMALLINT	Int16
SMALLMONEY	Decimal
time	TimeSpan
TINYINT	Byte
UNIQUEIDENTIFIER	Guid
varbinary	Byte[]
varchar	String, Char[]

升級 Azure Synapse Analytics 版本

若要升級 Azure Synapse Analytics 版本，請在 [編輯連結服務] 頁面中，選取 [版本] 底下的 [建議]，並參考建議版本的連接服務屬性來設定連結服務。

建議的版本與舊版之間的差異

下表顯示使用建議的和舊版的 Azure Synapse Analytics 之間的差異。

建議的版本	舊版
透過 `encrypt` 為 `strict` 支援 TLS 1.3。	不支援 TLS 1.3。

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

共用方式為