使用 Azure Data Factory 或 Azure Synapse Analytics 在 Azure Data Lake Storage Gen2 中複製和轉換資料

適用於:Azure Data Factory Azure Synapse Analytics

Azure Data Lake Storage Gen2 (ADLS Gen2) 是一組巨量資料分析的專屬功能,內建於 Azure Blob 儲存體。 其可讓您使用檔案系統和物件儲存範例連接您的資料。

本文概述如何使用複製活動,在 Azure Data Lake Storage Gen2 中來回複製資料,以及如何使用資料流程在 Azure Data Lake Storage Gen2 中轉換資料。 若要深入了解,請閱讀 Azure Data FactoryAzure Synapse Analytics 的介紹文章。

提示

請參閱將資料從資料湖或資料倉儲移轉至 Azure,以深入了解資料湖或資料倉儲移轉案例。

支援的功能

下列功能支援此 Azure Data Lake Storage Gen2 連接器:

支援的功能 IR 受控私人端點
複製活動 (來源/接收) ① ②
對應資料流 (來源/接收)
查閱活動 ① ②
GetMetadata 活動 ① ②
刪除活動 ① ②

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

對於複製活動,使用此連接器,您可以:

開始使用

提示

如需有關如何使用 Data Lake Storage Gen2 連接器的逐步解說,請參閱將資料載入 Data Lake Storage Gen2 中

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

使用 UI 建立 Azure Data Lake Storage Gen2 連結服務

使用下列步驟在 Azure 入口網站 UI 中建立 Azure Data Lake Storage Gen2 連結服務。

  1. 瀏覽至 Azure Data Factory 或 Synapse 工作區中的 [管理] 索引標籤,並選取 [連結的服務],然後按一下 [新增]:

  2. 搜尋 Azure Data Lake Storage Gen2,然後選取 Azure Data Lake Storage Gen2 連接器。

    選取 Azure Data Lake Storage Gen2 連接器。

  3. 設定服務詳細資料、測試連線,然後建立新的連結服務。

    Azure Data Lake Storage Gen2 連結服務設定的螢幕擷取畫面。

連接器設定詳細資料

下列各節提供屬性的詳細資訊,而這些屬性用來定義 Data Lake Storage Gen2 特有的 Data Factory 和 Synapse 管線實體。

連結服務屬性

Azure Data Lake Storage Gen2 連接器支援下列驗證類型。 如需詳細資訊,請參閱對應章節:

注意

  • 如果您想要藉由利用 Azure 儲存體防火牆上啟用的 [允許信任的 Microsoft 服務存取此儲存體帳戶] 選項,使用公用 Azure 整合執行階段連線到 Data Lake Storage Gen2,您必須使用受控識別驗證。 如需儲存體防火牆的詳細資訊,請參閱 Azure 儲存體防火牆設定和虛擬網路
  • 當您使用 PolyBase 或 COPY 陳述式將資料載入 Azure Synapse Analytics 時,如果您的來源或暫存 Data Lake Storage Gen2 是使用 Azure 虛擬網路端點來設定,您必須依據 Azure Synapse 的需要使用受控識別驗證。 如需更多設定必要條件,請參閱受控識別驗證一節。

帳戶金鑰驗證

若要使用儲存體帳戶金鑰驗證,以下是支援的屬性:

屬性 描述 必要
type 類型屬性必須設為 AzureBlobFS
url 具有 https://<accountname>.dfs.core.windows.net 模式的 Data Lake Storage Gen2 所適用的端點。
accountKey Data Lake Storage Gen2 的帳戶金鑰。 將此欄位標記為 SecureString 以將其安全地儲存,或參考 Azure Key Vault 中儲存的祕密
connectVia 用來連線到資料存放區的整合執行階段。 如果您的資料存放區位於私人網路中,則可使用 Azure Integration Runtime 或自我裝載整合執行階段。 如果未指定此屬性,則會使用預設的 Azure Integration Runtime。

注意

使用帳戶金鑰驗證時,不支援次要 ADLS 檔案系統端點。 您可以使用其他驗證類型。

範例︰

{
    "name": "AzureDataLakeStorageGen2LinkedService",
    "properties": {
        "type": "AzureBlobFS",
        "typeProperties": {
            "url": "https://<accountname>.dfs.core.windows.net", 
            "accountkey": { 
                "type": "SecureString", 
                "value": "<accountkey>" 
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

服務主體驗證

若要使用服務主體驗證,請遵循下列步驟。

  1. 遵循使用 Azure AD 租用戶註冊應用程式中的步驟,在 Azure Active Directory (Azure AD) 中註冊應用程式實體。 請記下以下的值,您可以使用這些值來定義連結服務:

    • 應用程式識別碼
    • 應用程式金鑰
    • 租用戶識別碼
  2. 將適當的權限授與服務主體。 請參閱檔案和目錄的存取控制清單,了解 Data Lake Storage Gen2 中權限運作方式的範例。

    • 作為來源:在 [儲存體總管] 中,至少授與對所有上游資料夾和檔案系統的 [執行] 權限,以及對接收資料夾的 [讀取] 權限。 或者,在存取控制 (IAM) 中,至少授與 [儲存體 Blob 資料讀取者] 角色。
    • 作為接收:在 [儲存體總管] 中,至少授與對所有上游資料夾和檔案系統的 [執行] 權限,以及對接收資料夾的 [寫入] 權限。 或者,在存取控制 (IAM) 中,至少授與 [儲存體 Blob 資料參與者] 角色。

注意

如果您使用 UI 進行撰寫,而且未在 IAM 中使用「儲存體 Blob 資料讀取者/參與者」角色設定服務主體,則在進行測試連線或瀏覽/導覽資料夾時,請選擇 [測試與檔案路徑的連線] 或 [從指定的路徑瀏覽],然後指定具有 [讀取 + 執行] 權限的路徑以繼續。

以下是連結服務支援的屬性:

屬性 描述 必要
type 類型屬性必須設為 AzureBlobFS
url 具有 https://<accountname>.dfs.core.windows.net 模式的 Data Lake Storage Gen2 所適用的端點。
servicePrincipalId 指定應用程式的用戶端識別碼。
servicePrincipalCredentialType 用於服務主體驗證的認證類型。 允許的值為 ServicePrincipalKeyServicePrincipalCert Yes
servicePrincipalCredential 服務主體認證。
當您使用 ServicePrincipalKey 作為認證類型時,請指定應用程式的金鑰。 將此欄位標記為 SecureString 以將其安全地儲存,或參考 Azure Key Vault 中儲存的祕密
當您使用 ServicePrincipalCert 作為認證時,請在 Azure Key Vault 中參考憑證,並確定憑證內容類型為 PKCS #12
servicePrincipalKey 指定應用程式的金鑰。 將此欄位標記為 SecureString 以將其安全地儲存,或參考 Azure Key Vault 中儲存的祕密
這個屬性仍依原樣支援 servicePrincipalId + servicePrincipalKey。 當 ADF 新增服務主體憑證驗證時,服務主體驗證的新模型為 servicePrincipalId + servicePrincipalCredentialType + servicePrincipalCredential
tenant 指定您的應用程式所在租用戶的資訊 (網域名稱或租用戶識別碼)。 將滑鼠游標暫留在 Azure 入口網站右上角,即可加以擷取。
azureCloudType 針對服務主體驗證,請指定要註冊 Azure Active Directory 應用程式的 Azure 雲端環境類型。
允許的值為 AzurePublicAzureChinaAzureUsGovernmentAzureGermany。 預設會使用 Data Factory 或 Synapse 管線的雲端環境。
connectVia 用來連線到資料存放區的整合執行階段。 如果您的資料存放區位於私人網路中,則可使用 Azure Integration Runtime 或自我裝載整合執行階段。 若未指定,則會使用預設 Azure Integration Runtime。

範例:使用服務主體金鑰驗證

您也可以將服務主體金鑰儲存在 Azure Key Vault 中。

{
    "name": "AzureDataLakeStorageGen2LinkedService",
    "properties": {
        "type": "AzureBlobFS",
        "typeProperties": {
            "url": "https://<accountname>.dfs.core.windows.net", 
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

範例:使用服務主體憑證驗證

{
    "name": "AzureDataLakeStorageGen2LinkedService",
    "properties": {
        "type": "AzureBlobFS",
        "typeProperties": {
            "url": "https://<accountname>.dfs.core.windows.net", 
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalCredential": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<AKV reference>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<certificate name in AKV>" 
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

系統指派的受控識別驗證

資料處理站或 Synapse 工作區可以與系統指派的受控識別相關聯。 您可以直接將此系統指派的受控識別用於 Data Lake Storage Gen2 驗證,類似於使用您自己的服務主體。 這可以讓這個指定的處理站或工作區存取及複製資料至 Data Lake Store,或從 Data Lake Storage Gen2 存取及複製資料。

若要使用系統指派的受控識別驗證,請遵循下列步驟。

  1. 複製與資料處理站或 Synapse 工作區一起產生的受控識別物件識別碼,藉此擷取系統指派的受控識別資訊

  2. 將適當的權限授與系統指派的受控識別。 請參閱檔案和目錄的存取控制清單,了解 Data Lake Storage Gen2 中權限運作方式的範例。

    • 作為來源:在 [儲存體總管] 中,至少授與對所有上游資料夾和檔案系統的 [執行] 權限,以及對接收資料夾的 [讀取] 權限。 或者,在存取控制 (IAM) 中,至少授與 [儲存體 Blob 資料讀取者] 角色。
    • 作為接收:在 [儲存體總管] 中,至少授與對所有上游資料夾和檔案系統的 [執行] 權限,以及對接收資料夾的 [寫入] 權限。 或者,在存取控制 (IAM) 中,至少授與 [儲存體 Blob 資料參與者] 角色。

以下是連結服務支援的屬性:

屬性 描述 必要
type 類型屬性必須設為 AzureBlobFS
url 具有 https://<accountname>.dfs.core.windows.net 模式的 Data Lake Storage Gen2 所適用的端點。
connectVia 用來連線到資料存放區的整合執行階段。 如果您的資料存放區位於私人網路中,則可使用 Azure Integration Runtime 或自我裝載整合執行階段。 若未指定,則會使用預設 Azure Integration Runtime。

範例︰

{
    "name": "AzureDataLakeStorageGen2LinkedService",
    "properties": {
        "type": "AzureBlobFS",
        "typeProperties": {
            "url": "https://<accountname>.dfs.core.windows.net", 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

資料處理站可以使用一或多個使用者指派的受控識別來指派。 您可以使用此使用者指派的受控識別進行 Blob 儲存體驗證,以允許在 Data Lake Storage Gen2 中來回存取和複製資料。 若要深入了解 Azure 資源受控識別,請參閱 Azure 資源受控識別

若要使用使用者指派的受控識別驗證,請遵循下列步驟:

  1. 建立一或多個使用者指派的受控識別並且授與 Azure Data Lake Storage Gen2 的存取權。 請參閱檔案和目錄的存取控制清單,了解 Data Lake Storage Gen2 中權限運作方式的範例。

    • 作為來源:在 [儲存體總管] 中,至少授與對所有上游資料夾和檔案系統的 [執行] 權限,以及對接收資料夾的 [讀取] 權限。 或者,在存取控制 (IAM) 中,至少授與 [儲存體 Blob 資料讀取者] 角色。
    • 作為接收:在 [儲存體總管] 中,至少授與對所有上游資料夾和檔案系統的 [執行] 權限,以及對接收資料夾的 [寫入] 權限。 或者,在存取控制 (IAM) 中,至少授與 [儲存體 Blob 資料參與者] 角色。
  2. 將一或多個使用者指派的受控識別指派給 Data Factory,並為每個使用者指派的受控識別建立認證

以下是連結服務支援的屬性:

屬性 描述 必要
type 類型屬性必須設為 AzureBlobFS
url 具有 https://<accountname>.dfs.core.windows.net 模式的 Data Lake Storage Gen2 所適用的端點。
認證 將使用者指派的受控識別指定為認證物件。
connectVia 用來連線到資料存放區的整合執行階段。 如果您的資料存放區位於私人網路中,則可使用 Azure Integration Runtime 或自我裝載整合執行階段。 若未指定,則會使用預設 Azure Integration Runtime。

範例︰

{
    "name": "AzureDataLakeStorageGen2LinkedService",
    "properties": {
        "type": "AzureBlobFS",
        "typeProperties": {
            "url": "https://<accountname>.dfs.core.windows.net", 
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
                }
            },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

注意

如果您使用 Data Factory UI 進行撰寫,而且未在 IAM 中使用「儲存體 Blob 資料讀取者/參與者」角色設定受控識別,則在進行測試連線或瀏覽/導覽資料夾時,請選擇 [測試與檔案路徑的連線] 或 [從指定的路徑瀏覽],然後指定具有 [讀取 + 執行] 權限的路徑以繼續。

重要

如果您使用 PolyBase 或 COPY 陳述式從 Data Lake Storage Gen2 將資料載入 Azure Synapse Analytics,當您將受控識別驗證用於 Data Lake Storage Gen2 時,請確定您也遵循本指引中的步驟 1 到 3。 這些步驟會向 Azure AD 註冊您的伺服器,並將儲存體 Blob 資料參與者角色指派給伺服器。 Data Factory 會處理其餘部分。 如果您使用 Azure 虛擬網路端點來設定 Blob 儲存體,也需要讓 [允許信任的 Microsoft 服務] 在 Azure Synapse 所要求的 Azure 儲存體帳戶 [防火牆和虛擬網路設定] 功能表下,存取此儲存體帳戶。

資料集屬性

如需定義資料集的區段和屬性完整清單,請參閱資料集

Azure Data Factory 支援下列檔案格式。 請參閱每篇文章,以取得以格式為基礎的設定。

在格式型資料集內的 location 設定下,Data Lake Storage Gen2 支援下列屬性:

屬性 描述 必要
type 資料集中 location 下的 type 屬性必須設定為 AzureBlobFSLocation
fileSystem Data Lake Storage Gen2 檔案系統名稱。
folderPath 所指定檔案系統下的資料夾路徑。 如果您想要使用萬用字元來篩選資料夾,請略過此設定,並在活動來源設定中指定。
fileName 所指定 fileSystem + folderPath 下方的檔案名稱。 如果您想要使用萬用字元來篩選檔案,請略過此設定,並在活動來源設定中指定。

範例︰

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<Data Lake Storage Gen2 linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "AzureBlobFSLocation",
                "fileSystem": "filesystemname",
                "folderPath": "folder/subfolder"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

複製活動屬性

如需可用來定義活動的區段和屬性完整清單,請參閱複製活動組態管線和活動。 本節提供 Data Lake Storage Gen2 來源和接收端所支援的屬性清單。

以 Azure Data Lake Storage Gen2 作為來源類型

Azure Data Factory 支援下列檔案格式。 請參閱每篇文章,以取得以格式為基礎的設定。

您有數個選項可從 ADLS Gen2 複製資料:

  • 請從資料集內的指定路徑複製。
  • 針對資料夾路徑或檔案名的萬用字元篩選,請參閱 wildcardFolderPathwildcardFileName
  • 將指定文字檔中定義的檔案複製為檔案集,請參閱 fileListPath

在格式型複製來源內的 storeSettings 設定下,Data Lake Storage Gen2 支援下列屬性:

屬性 描述 必要
type storeSettings 下的 type 屬性必須設定為 AzureBlobFSReadSettings
尋找要複製的檔案:
選項 1:靜態路徑
從在資料集內指定的檔案系統或資料夾/檔案路徑複製。 如果您想要複製檔案系統/資料夾中的所有檔案,請另外將 wildcardFileName 指定為 *
選項 2:萬用字元
- wildcardFolderPath
在資料集內設定的指定檔案系統底下,具有萬用字元的資料夾路徑,用來篩選來源資料夾。
允許的萬用字元為:* (比對零或多個字元) 和 ? (比對零或單一字元);如果您的實際資料夾名稱包含萬用字元或此逸出字元,請使用 ^ 來逸出。
如需更多範例,請參閱資料夾和檔案篩選範例
選項 2:萬用字元
- wildcardFileName
在指定 file system + folderPath/wildcardFolderPath 之下,含有萬用字元的檔案名稱,可用來篩選來源檔案。
允許的萬用字元為:* (比對零或多個字元) 和 ? (比對零或單一字元);如果您的實際檔案名稱包含萬用字元或此逸出字元,請使用 ^ 來逸出。 如需更多範例,請參閱資料夾和檔案篩選範例
選項 3:檔案清單
- fileListPath
表示要複製指定的檔案集。 指向含有所要複製檔案清單的文字檔,一行一個檔案,而這是資料集中所設定路徑的相對路徑。
使用此選項時,請勿指定資料集中的檔案名稱。 檔案清單範例 (英文) 有更多範例可供參閱。
其他設定:
遞迴 指出是否從子資料夾、或只有從指定的資料夾,以遞迴方式讀取資料。 請注意,當遞迴設定為 true 且接收是檔案型存放區時,就不會在接收上複製或建立空的資料夾或子資料夾。
允許的值為 true (預設值) 和 false
設定 fileListPath 時,不適用此屬性。
deleteFilesAfterCompletion 指出成功移至目的地存放區之後,是否要從來源存放區中刪除二進位檔案。 檔案刪除會針對每個檔案執行,因此,當複製活動失敗時,您會看到已將某些檔案複製到目的地,而且已從來源刪除,而其他檔案仍保留在來源存放區上。
此屬性僅適用於二進位檔案複製案例。 預設值:false。
modifiedDatetimeStart 檔案篩選會根據以下屬性:上次修改時間。
如果檔案的上次修改時間大於或等於 modifiedDatetimeStart 且小於 modifiedDatetimeEnd,則會選取檔案。 此時間會以 "2018-12-01T05:00:00Z" 格式套用至 UTC 時區。
屬性可以是 NULL,這意謂著不會在資料集中套用任何檔案屬性篩選。 當 modifiedDatetimeStart 具有日期時間值,但 modifiedDatetimeEnd 為 NULL 時,意謂著系統將會選取上次更新時間屬性大於或等於此日期時間值的檔案。 當 modifiedDatetimeEnd 具有日期時間值,但 modifiedDatetimeStart 為 NULL 時,則意謂著系統將會選取上次更新時間屬性小於此日期時間值的檔案。
設定 fileListPath 時,不適用此屬性。
modifiedDatetimeEnd 同上。
enablePartitionDiscovery 針對已分割的檔案,指定是否要從檔案路徑剖析分割區,並將其新增為其他來源資料行。
允許的值為 false (預設值) 和 true
No
partitionRootPath 啟用分割區探索時,請指定絕對根路徑,將已分割的資料夾當成資料行進行讀取。

如果未指定,則根據預設,
- 當您使用資料集中的檔案路徑或來源上的檔案清單時,分割區根路徑是資料集中所設定的路徑。
- 當您使用萬用字元資料夾篩選時,分割區根路徑是第一個萬用字元前面的子路徑。

例如,假設您將資料集中的路徑設定為 "root/folder/year=2020/month=08/day=27":
- 如果您將分割區根路徑指定為 "root/folder/year=2020",則除了檔案內的資料行之外,複製活動還會分別產生值為 "08" 和 "27" 的兩個資料行 monthday
- 如果未指定分割區根路徑,則不會產生額外的資料行。
maxConcurrentConnections 活動執行期間,建立與資料存放區的並行連線上限。 僅在想要限制並行連線時,才需要指定值。

範例︰

"activities":[
    {
        "name": "CopyFromADLSGen2",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Delimited text input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "DelimitedTextSource",
                "formatSettings":{
                    "type": "DelimitedTextReadSettings",
                    "skipLineCount": 10
                },
                "storeSettings":{
                    "type": "AzureBlobFSReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

以 Azure Data Lake Storage Gen2 作為接收類型

Azure Data Factory 支援下列檔案格式。 請參閱每篇文章,以取得以格式為基礎的設定。

在格式型複製接收器內的 storeSettings 設定下,Data Lake Storage Gen2 支援下列屬性:

屬性 描述 必要
type storeSettings 下的 type 屬性必須設定為 AzureBlobFSWriteSettings
copyBehavior 當來源是來自檔案型資料存放區的檔案時,會定義複製行為。

允許的值包括:
- PreserveHierarchy (預設):保留目標資料夾中的檔案階層。 來源檔案到來源資料夾的相對路徑,與目標檔案到目標資料夾的相對路徑相同。
- FlattenHierarchy:來自來源資料夾的所有檔案都會在目標資料夾的第一層中。 目標檔案會有自動產生的名稱。
- MergeFiles:將來自來源資料夾的所有檔案合併成一個檔案。 若已指定檔案名稱,合併檔案的名稱會是指定的名稱。 否則,就會是自動產生的檔案名稱。
blockSizeInMB 指定用於將資料寫入 ADLS Gen2 的區塊大小 (以 MB 為單位)。 深入了解區塊 Blob
允許的值介於 4 MB 到 100 MB 之間
根據預設,ADF 會根據您的來源存放區類型和資料,自動決定區塊大小。 對於非二進位複製到 ADLS Gen2 中,預設區塊大小為 100 MB,因此最多大約可容納 4.75 TB 的資料。 這在資料不大時可能並非最理想,尤其在使用「自我裝載整合執行階段」,而且網路連線不佳的情況下,將導致作業逾時或效能問題。 您可以明確指定區塊大小,同時確保 blockSizeInMB*50000 夠大足以儲存資料,否則複製活動執行會失敗。
maxConcurrentConnections 活動執行期間,建立與資料存放區的並行連線上限。 僅在想要限制並行連線時,才需要指定值。
中繼資料 在複製到接收時設定自訂中繼資料。 metadata 陣列下的每個物件都代表額外的資料行。 name 會定義中繼資料索引鍵名稱,而 value 表示該索引鍵的資料值。 若使用保留屬性功能,指定的中繼資料會與來源檔案中繼資料聯合/覆寫。

允許的資料值為:
- $$LASTMODIFIED:保留變數表示儲存來源檔案上次修改的時間。 僅適用於二進位格式的檔案型來源。
- 運算式
- 靜態值

範例︰

"activities":[
    {
        "name": "CopyToADLSGen2",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Parquet output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "ParquetSink",
                "storeSettings":{
                    "type": "AzureBlobFSWriteSettings",
                    "copyBehavior": "PreserveHierarchy",
                    "metadata": [
                        {
                            "name": "testKey1",
                            "value": "value1"
                        },
                        {
                            "name": "testKey2",
                            "value": "value2"
                        },
                        {
                            "name": "lastModifiedKey",
                            "value": "$$LASTMODIFIED"
                        }
                    ]
                }
            }
        }
    }
]

資料夾和檔案篩選範例

本節描述含有萬用字元篩選之資料夾路徑和檔案名稱所產生的行為。

folderPath fileName 遞迴 來源資料夾結構和篩選結果 (會擷取以粗體顯示的檔案)
Folder* (空白,使用預設值) false FolderA
    File1.csv
    File2.json
    Subfolder1
        File3.csv
        File4.json
        File5.csv
AnotherFolderB
    File6.csv
Folder* (空白,使用預設值) true FolderA
    File1.csv
    File2.json
    Subfolder1
        File3.csv
        File4.json
        File5.csv
AnotherFolderB
    File6.csv
Folder* *.csv false FolderA
    File1.csv
    File2.json
    Subfolder1
        File3.csv
        File4.json
        File5.csv
AnotherFolderB
    File6.csv
Folder* *.csv true FolderA
    File1.csv
    File2.json
    Subfolder1
        File3.csv
        File4.json
        File5.csv
AnotherFolderB
    File6.csv

檔案清單範例

本節說明使用複製活動來源中的檔案清單路徑時,會產生的行為。

假設您的來源資料夾結構如下,且想要複製粗體的檔案:

範例來源結構 FileListToCopy.txt 中的內容 ADF 組態
filesystem
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    中繼資料
        FileListToCopy.txt
File1.csv
Subfolder1/File3.csv
Subfolder1/File5.csv
資料集中:
- 檔案系統:filesystem
- 資料夾路徑:FolderA

在複製活動來源內:
- 檔案清單路徑:filesystem/Metadata/FileListToCopy.txt

檔案清單路徑指向同一個資料存放區中的文字檔,內有您想複製的檔案清單,每行一個檔案,以資料集內所設定路徑的相對路徑表示。

一些遞迴和 copyBehavior 範例

本節說明遞迴和 copyBehavior 值在不同組合的情況下,複製作業所產生的行為。

遞迴 copyBehavior 來源資料夾結構 產生的目標
true preserveHierarchy Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
會以與來源相同的結構,建立目標 Folder1:

Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
true flattenHierarchy Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
會以下列結構建立目標資料夾 Folder1:

Folder1
    針對 File1 自動產生的名稱
    針對 File2 自動產生的名稱
    針對 File3 自動產生的名稱
    針對 File4 自動產生的名稱
    針對 File5 自動產生的名稱
true mergeFiles Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
會以下列結構建立目標資料夾 Folder1:

Folder1
    File1 + File2 + File3 + File4 + File5 的內容會合併成一個檔案,並具有自動產生的檔案名稱。
false preserveHierarchy Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
會以下列結構建立目標資料夾 Folder1:

Folder1
    File1
    File2

系統不會挑選含有 File3、File4、File5 的 Subfolder1。
false flattenHierarchy Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
會以下列結構建立目標資料夾 Folder1:

Folder1
    針對 File1 自動產生的名稱
    針對 File2 自動產生的名稱

系統不會挑選含有 File3、File4、File5 的 Subfolder1。
false mergeFiles Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
會以下列結構建立目標資料夾 Folder1:

Folder1
    File1 + File2 的內容會合併成一個檔案,並具有自動產生的檔案名稱。 針對 File1 自動產生的名稱

系統不會挑選含有 File3、File4、File5 的 Subfolder1。

複製期間保留中繼資料

當您將檔案從 Amazon S3/Azure Blob/Azure Data Lake Storage Gen2 複製到 Azure Data Lake Storage Gen2/Azure Blob 時,除了資料以外,還可選擇保留檔案中繼資料。 深入了解保留中繼資料

保留來自 Data Lake Storage Gen1/Gen2 的 ACL

當您將檔案從 Azure Data Lake Storage Gen1/Gen2 複製到 Gen2 時,您可以選擇連同資料一起保存 POSIX 存取控制清單 (ACL)。 深入了解如何將 ACL 從 Data Lake Storage Gen1/Gen2 保存至 Gen2

提示

若要在一般情況下將資料從 Azure Data Lake Storage Gen1 複製到 Gen2,請參閱將資料從 Azure Data Lake Storage Gen1 複製到 Gen2,取得逐步解說和最佳做法。

對應資料流程屬性

在對應資料流程中轉換資料時,您可以使用下列格式,從 Azure Data Lake Storage Gen2 讀取和寫入檔案:

格式特定設定位於該格式的文件中。 如需詳細資訊,請參閱對應資料流程中的來源轉換對應資料流程中的接收轉換

來源轉換

在來源轉換中,您可以從 Azure Data Lake Storage Gen2 中的容器、資料夾或個別檔案讀取資料。 [來源選項] 索引標籤可讓您管理檔案的讀取方式。

對應資料流程來源轉換中來源選項索引標籤的螢幕擷取畫面。

萬用字元路徑: 在單一來源轉換中,使用萬用字元模式會指示 ADF 循環檢查每個相符的資料夾和檔案。 這在單一流程內處理多個檔案時很有效。 使用 + 符號來新增多個萬用字元比對模式,當滑鼠停留在現有萬用字元模式上時會出現此符號。

從來源容器中,選擇符合模式的一系列檔案。 在資料集內只能指定容器。 因此,萬用字元路徑也必須包含始於根資料夾的資料夾路徑。

萬用字元範例:

  • * 代表任何一組字元

  • ** 代表遞迴目錄巢狀

  • ? 取代一個字元

  • [] 比對括弧中的一個或多個字元

  • /data/sales/**/*.csv 取得 /data/sales 下的所有 csv 檔案

  • /data/sales/20??/**/ 取得 20 世紀的所有檔案

  • /data/sales/*/*/*.csv 取得 /data/sales 下兩層的 csv 檔案

  • /data/sales/2004/*/12/[XY]1?.csv 取得 2004 年 12 月以 X 或 Y 開頭且字首是兩位數字的所有 csv 檔案

分割區根路徑:如果您的檔案來源中有 key=value 格式 (例如 year=2019) 的分割資料夾,則可以將該分割區資料夾樹狀結構的最上層,指派給資料流程資料流中的資料行名稱。

首先,請設定萬用字元來包含所有路徑,即分割資料夾加上您想讀取的分葉檔案。

對應資料流程來源轉換中分割來源檔案設定的螢幕擷取畫面。

使用 [分割區根路徑] 設定來定義資料夾結構的最上層。 當您透過資料預覽來檢視資料的內容時,將會看到 ADF 會新增每個資料夾層級中找到的已解析分割區。

分割區根路徑

檔案清單: 這是檔案集。 建立文字檔,其中包含要處理的相對路徑檔案清單。 指向這個文字檔。

要儲存檔案名稱的資料行: 將來源檔案的名稱儲存在資料中的資料行。 在此輸入新的資料行名稱以儲存檔案名稱字串。

完成後: 選擇在資料流程後不操作來源檔案、刪除來源檔案、或移動來源檔案。 移動時的路徑是相對路徑。

若要在處理後將來源檔案移到另一個位置,請先選取 [移動] 當作檔案操作。 然後,設定「來源」目錄。 如果路徑中未使用任何萬用字元,則「來源」設定與來源資料夾相同。

如果來源路徑含有萬用字元,則語法如下:

/data/sales/20??/**/*.csv

您可以將「來源」指定為

/data/sales

將「目的地」指定為

/backup/priorSales

在此案例中,/data/sales 中的所有檔案都會移至 /backup/priorSales。

注意

只有當您從管線執行 (管線偵錯或執行) 啟動資料流程,且該管線執行在管線中使用「執行資料流程」活動時,檔案操作才會執行。 在資料流程偵錯模式下「不會」執行檔案操作。

依上次修改時間篩選: 您可以指定檔案上次修改的日期範圍,以篩選您處理的檔案。 所有日期時間都是 UTC 格式。

啟用異動資料擷取:如果為 true,您只會從上次執行取得新的或變更的檔案。 初次執行時一律會進行完整快照集資料的初始載入,接著只在下一次執行中擷取新的或變更的檔案。 如需詳細資訊,請參閱異動資料擷取

螢幕擷取畫面,其中顯示啟用變更資料擷取。

接收屬性

在「接收」轉換中,您可以寫入 Azure Data Lake Storage Gen2 中的容器或資料夾。 [設定] 索引標籤可讓您管理檔案的寫入方式。

接收選項

清除資料夾: 決定是否在寫入資料之前先清除目的地資料夾。

檔案名稱選項: 決定目的地檔案在目的地資料夾中的命名方式。 檔案名稱的選項如下:

  • 預設值:可讓 Spark 根據 PART 預設值來命名檔案。
  • 模式:輸入模式來列舉每個分割區的輸出檔案。 例如,loans[n].csv 會建立 loans1.csv、loans2.csv,依此類推。
  • 每個分割區:針對每個分割區輸入一個檔案名稱。
  • 作為資料行中的資料:將輸出檔案設定為資料行的值。 路徑相對於資料集容器,而不是目的地資料夾。 如果資料集含有資料夾路徑,則會被覆寫。
  • 輸出至單一檔案:將分割的輸出檔案結合成單一的具名檔案。 路徑相對於資料集資料夾。 請注意,根據節點的大小而定,「合併」作業可能失敗。 對於大型資料集,不建議使用此選項。

全部以引號括住: 決定是否用引號括住所有的值

umask

您可以選擇性地使用 POSIX 讀取、寫入、執行擁有者、使用者和群組的旗標來設定檔案的 umask

前置和後置處理命令

您可以選擇性地在寫入 ADLS Gen2 接收之前或之後執行 Hadoop 檔案系統命令。 支援的命令如下:

  • cp
  • mv
  • rm
  • mkdir

範例:

  • mkdir /folder1
  • mkdir -p folder1
  • mv /folder1/*.* /folder2/
  • cp /folder1/file1.txt /folder2
  • rm -r /folder1

運算式產生器也支援參數,例如:

mkdir -p {$tempPath}/commands/c1/c2 mv {$tempPath}/commands/*.* {$tempPath}/commands/c1/c2

根據預設,資料夾會建立為使用者/根目錄。 請參閱具有 '/' 的最上層容器。

查閱活動屬性

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

GetMetadata 活動屬性

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

刪除活動屬性

若要了解關於此屬性的詳細資料,請參閱刪除活動

舊版模型

注意

下列模型仍依原狀支援,以提供回溯相容性。 建議您往後使用以上各節所述的新模型,而製作 UI 的 ADF 已切換為產生新模型。

舊版資料集模型

屬性 描述 必要
type 資料集的類型屬性必須設為 AzureBlobFSFile
folderPath Data Lake Storage Gen2 中資料夾的路徑。 若未指定,它會指向根。

支援萬用字元篩選。 允許的萬用字元為:* (符合零或多個字元) 和 ? (符合零或單一字元)。 如果實際資料夾名稱內有萬用字元或逸出字元 ^,請使用此逸出字元來逸出。

範例:filesystem/folder/。 如需更多範例,請參閱資料夾和檔案篩選範例
fileName 在指定 "folderPath" 之下檔案的名稱或萬用字元篩選。 若未指定此屬性的值,資料集就會指向資料夾中的所有檔案。

篩選時,允許的萬用字元為 * (符合零或多個字元) 和 ? (符合零或單一字元)。
- 範例 1:"fileName": "*.csv"
- 範例 2:"fileName": "???20180427.txt"
如果實際檔案名稱內有萬用字元或逸出字元 ^,請使用此逸出字元來逸出。

沒有為輸出資料集指定 fileName 且活動接收器中未指定 preserveHierarchy 時,複製活動會自動以下列模式產生檔案名稱:"Data.[activity run ID GUID].[GUID if FlattenHierarchy].[format if configured].[compression if configured]",例如,"Data.0a405f8a-93ff-4c6f-b3be-f69616f1df7a.txt.gz"。 如果您使用資料表名稱 (而非查詢) 從表格來源複製,則名稱模式會是 "[table name].[format].[compression if configured]",例如 "MyTable.csv"。
modifiedDatetimeStart 檔案篩選會根據「上次修改」屬性。 如果檔案的上次修改時間大於或等於 modifiedDatetimeStart 且小於 modifiedDatetimeEnd,則會選取檔案。 此時間會以 "2018-12-01T05:00:00Z" 格式套用至 UTC 時區。

當您想要對大量檔案進行檔案篩選時,啟用這項設定會影響資料移動的整體效能。

此屬性可以是 NULL,這意謂著不會對資料集套用任何檔案屬性篩選。 當 modifiedDatetimeStart 有日期時間值,但 modifiedDatetimeEnd 為 NULL 時,表示系統將會選取上次修改時間屬性大於或等於此日期時間值的檔案。 當 modifiedDatetimeEnd 有日期時間值,但 modifiedDatetimeStart 為 NULL 時,則表示系統將會選取上次修改時間屬性小於此日期時間值的檔案。
modifiedDatetimeEnd 檔案篩選會根據「上次修改」屬性。 如果檔案的上次修改時間大於或等於 modifiedDatetimeStart 且小於 modifiedDatetimeEnd,則會選取檔案。 此時間會以 "2018-12-01T05:00:00Z" 格式套用至 UTC 時區。

當您想要對大量檔案進行檔案篩選時,啟用這項設定會影響資料移動的整體效能。

此屬性可以是 NULL,這意謂著不會對資料集套用任何檔案屬性篩選。 當 modifiedDatetimeStart 有日期時間值,但 modifiedDatetimeEnd 為 NULL 時,表示系統將會選取上次修改時間屬性大於或等於此日期時間值的檔案。 當 modifiedDatetimeEnd 有日期時間值,但 modifiedDatetimeStart 為 NULL 時,則表示系統將會選取上次修改時間屬性小於此日期時間值的檔案。
format 如果您想要在檔案型存放區之間依原樣複製檔案 (二進位複本),請在輸入和輸出資料集定義中略過格式區段。

如果您想要剖析或產生特定格式的檔案,以下是支援的檔案格式類型:TextFormatJsonFormatAvroFormatOrcFormatParquetFormat。 將 [format] 下的 [type] 屬性設定為下列其中一個值。 如需詳細資訊,請參閱文字格式JSON 格式Avro 格式ORC 格式Parquet 格式章節。
否 (僅適用於二進位複製案例)
compression 指定此資料的壓縮類型和層級。 如需詳細資訊,請參閱支援的檔案格式和壓縮轉碼器
支援的類型為 **GZip**, **Deflate**, **BZip2**, and **ZipDeflate**
支援的層級為 OptimalFastest
No

提示

若要複製資料夾下的所有檔案,請只指定 folderPath
若要複製指定名稱的單一檔案,請以資料夾部分指定 folderPath,並以檔案名稱指定 fileName
若要複製資料夾下的檔案子集,請以 folderPath 指定資料夾部分 ,並以 fileName 指定萬用字元篩選。

範例︰

{
    "name": "ADLSGen2Dataset",
    "properties": {
        "type": "AzureBlobFSFile",
        "linkedServiceName": {
            "referenceName": "<Azure Data Lake Storage Gen2 linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "folderPath": "myfilesystem/myfolder",
            "fileName": "*",
            "modifiedDatetimeStart": "2018-12-01T05:00:00Z",
            "modifiedDatetimeEnd": "2018-12-01T06:00:00Z",
            "format": {
                "type": "TextFormat",
                "columnDelimiter": ",",
                "rowDelimiter": "\n"
            },
            "compression": {
                "type": "GZip",
                "level": "Optimal"
            }
        }
    }
}

舊版複製活動來源模型

屬性 描述 必要
type 複製活動來源的類型屬性必須設為 AzureBlobFSSource
遞迴 指出是否從子資料夾、或只有從指定的資料夾,以遞迴方式讀取資料。 當遞迴設定為 true 且接收是檔案型存放區時,就不會在接收上複製或建立空的資料夾或子資料夾。
允許的值為 true (預設值) 和 false
maxConcurrentConnections 活動執行期間,建立與資料存放區的並行連線上限。 僅在想要限制並行連線時,才需要指定值。

範例︰

"activities":[
    {
        "name": "CopyFromADLSGen2",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<ADLS Gen2 input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "AzureBlobFSSource",
                "recursive": true
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

舊版複製活動接收模型

屬性 描述 必要
type 複製活動接收的類型屬性必須設為 AzureBlobFSSink
copyBehavior 當來源是來自檔案型資料存放區的檔案時,會定義複製行為。

允許的值包括:
- PreserveHierarchy (預設):保留目標資料夾中的檔案階層。 來源檔案到來源資料夾的相對路徑,與目標檔案到目標資料夾的相對路徑相同。
- FlattenHierarchy:來自來源資料夾的所有檔案都會在目標資料夾的第一層中。 目標檔案會有自動產生的名稱。
- MergeFiles:將來自來源資料夾的所有檔案合併成一個檔案。 若已指定檔案名稱,合併檔案的名稱會是指定的名稱。 否則,就會是自動產生的檔案名稱。
maxConcurrentConnections 活動執行期間,建立與資料存放區的並行連線上限。 僅在想要限制並行連線時,才需要指定值。

範例︰

"activities":[
    {
        "name": "CopyToADLSGen2",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<ADLS Gen2 output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "AzureBlobFSSink",
                "copyBehavior": "PreserveHierarchy"
            }
        }
    }
]

變更資料擷取

Azure Data Factory 只能藉由在對應資料流程來源轉換中啟用異動資料擷取,從 Azure Data Lake Storage Gen2 取得新的或變更的檔案。 使用此連接器選項,您只能讀取新的或更新的檔案,並在將轉換資料載入您選擇的目的地資料集之前套用轉換。

請確定管線和活動名稱保持不變,讓檢查點一律會從上次執行記錄,以從該處取得變更。 如果您變更管線名稱或活動名稱,將會重設檢查點,並且在下一次執行時從頭開始。

當您偵錯管線時,[啟用異動資料擷取] 也可以運作。 請注意,當您在偵錯執行期間重新整理瀏覽器時,將會重設檢查點。 對偵錯執行的結果感到滿意後,您可以發佈並觸發管線。 不論偵錯執行所記錄的先前檢查點為何,一律會從頭開始。

在監視區段中,您隨時有機會重新執行管線。 這樣做時,一律會從所選取管線執行的檢查點記錄取得變更。

下一步

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