使用 Azure Data Factory 或 Synapse Analytics 從 Amazon S3 相容儲存體複製資料

  • 發行項

適用於：Azure Data Factory Azure Synapse Analytics

提示

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

本文概述如何從 Amazon Simple Storage Service (Amazon S3) 相容儲存體複製資料。 若要深入了解，請閱讀 Azure Data Factory 和 Synapse Analytics 的介紹文章。

支援的功能

下列功能支援此 Amazon S3 相容儲存體連接器：

支援的功能 IR
複製活動 (來源/-) ① ②
查閱活動 ① ②
GetMetadata 活動 ① ②
刪除活動 ① ②

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

具體而言，此 Amazon S3 相容儲存體連接器支援依原樣複製檔案，或使用支援的檔案格式和壓縮轉碼器來剖析檔案。 連接器會使用 AWS Signature 第 4 版來驗證對 S3 的要求。 您可以使用此 Amazon S3 相容儲存體連接器，以從任何與 S3 相容的儲存體提供者中複製資料。 在連結服務設定中指定相對應的服務 URL。

所需的權限

若要從 Amazon S3 相容儲存體複製資料，請確定您已獲授與下列 Amazon S3 物件作業的權限︰s3:GetObject 和 s3:GetObjectVersion。

如果您使用 UI 進行編寫，則測試連結服務連線以及從根目錄瀏覽這類作業需要額外的 s3:ListAllMyBuckets 和 s3:ListBucket/s3:GetBucketLocation 權限。 如果您不想要授與這些權限，則可以從 UI 中選擇 [測試檔案路徑的連線] 或 [從指定的路徑瀏覽] 選項。

如需完整的 Amazon S3 權限清單，請參閱 AWS 網站上的在原則中指定權限 (英文)。

開始使用

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

使用 UI 建立 Amazon S3 相容儲存體的連結服務

使用下列步驟，以在 Azure 入口網站 UI 中建立 Amazon S3 相容儲存體的連結服務。

  1. 前往 Azure Data Factory 或 Synapse 工作區的 [管理] 索引標籤，選取 [連結服務]，然後按一下 [新增]：

  2. 搜尋 Amazon，然後選取 [Amazon S3 相容儲存體連接器]。

    Select the Amazon S3 Compatible Storage connector.

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

    Configure a linked service to Amazon S3 Compatible Storage.

連接器設定詳細資料

下列各節提供屬性的相關詳細資料，而這些屬性用來定義 Amazon S3 相容儲存體特有的實體。

連結服務屬性

下列是 Amazon S3 相容連結服務所支援的屬性：

屬性 描述 必要
type type 屬性必須設定為 AmazonS3Compatible。 Yes
accessKeyId 密碼存取金鑰的識別碼。 Yes
secretAccessKey 密碼存取金鑰本身。 將此欄位標記為 SecureString 以將其安全地儲存，或參考 Azure Key Vault 中儲存的祕密。 Yes
serviceUrl 指定自訂 S3 端點 https://<service url>。 No
forcePathStyle 指出是否使用 S3 路徑樣式存取，而不是虛擬託管樣式存取。 允許的值為：false (預設值)、true。
檢查每個資料存放區的文件，以了解是否需要路徑樣式存取。		 No
connectVia 用來連線到資料存放區的整合執行階段。 您可以使用 Azure 整合執行階段或自我裝載整合執行階段 (若您的資料儲存在私人網路中)。 如未指定此屬性，服務將使用預設的 Azure 整合執行階段。 No

範例：

{
    "name": "AmazonS3CompatibleLinkedService",
    "properties": {
        "type": "AmazonS3Compatible",
        "typeProperties": {
            "accessKeyId": "<access key id>",
            "secretAccessKey": {
                "type": "SecureString",
                "value": "<secret access key>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

資料集屬性

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

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

在格式型資料集的 location 設定下，Amazon S3 相容支援下列屬性：

屬性 描述 必要
type 資料集中 location 下的 type 屬性必須設定為 AmazonS3CompatibleLocation。 Yes
bucketName S3 相容儲存體貯體名稱。 Yes
folderPath 所指定貯體下的資料夾路徑。 如果您想要使用萬用字元來篩選資料夾，則請跳過此設定，並在活動來源設定中指定該項目。 No
fileName 所指定貯體和資料夾路徑下的檔案名稱。 如果您想要使用萬用字元來篩選檔案，則請跳過此設定，並在活動來源設定中指定該項目。 No
version 如果已啟用 S3 相容儲存體版本設定，則為 S3 相容儲存體物件的版本。 如果未指定，將會擷取最新版本。 No

範例：

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<Amazon S3 Compatible Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "AmazonS3CompatibleLocation",
                "bucketName": "bucketname",
                "folderPath": "folder/subfolder"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

複製活動屬性

如需可用來定義活動的區段和屬性完整清單，請參閱管線一文。 本節提供 Amazon S3 相容儲存體來源所支援的屬性清單。

Amazon S3 相容儲存體作為來源類型

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

在格式型複製來源的 storeSettings 設定下，Amazon S3 相容儲存體支援下列屬性：

屬性 描述 必要
type storeSettings 下的 type 屬性必須設定為 AmazonS3CompatibleReadSettings。 Yes
找到要複製的檔案
選項 1：靜態路徑
 從在資料集內指定的貯體或資料夾/檔案路徑複製。 如果您想要複製貯體或資料夾中的所有檔案，則請另外將 wildcardFileName 指定為 *。
選項 2：S3 相容儲存體前置詞
- 前置詞		 資料集中所設定的指定貯體下的 S3 相容儲存體索引鍵名稱前置詞，可篩選來源 S3 相容儲存體檔案。 選取名稱開頭為 bucket_in_dataset/this_prefix 的 S3 相容儲存體索引鍵。 其利用 S3 相容儲存體的服務端篩選，以提供優於萬用字元篩選的效能。

當您使用前置詞，並選擇使用保留階層複製至檔案型接收器時，請注意：前置詞最後一個「/」後的子路徑將會保留。 例如：您有來源 bucket/folder/subfolder/file.txt 且將前置詞設為 folder/sub，保留的檔案路徑則為 subfolder/file.txt。		 No
選項 3：萬用字元
- wildcardFolderPath		 在資料集內設定的指定貯體下，具有萬用字元的資料夾路徑，用來篩選來源資料夾。
允許的萬用字元為：* (符合零或多個字元) 和 ? (符合零或單一字元)。 如果資料夾名稱具有萬用字元或逸出字元 ^，則請使用此逸出字元予以逸出。
如需更多範例，請參閱資料夾和檔案篩選範例。		 No
選項 3：萬用字元
- wildcardFileName		 在所指定貯體和資料夾路徑 (或萬用字元資料夾路徑)下，具有萬用字元的檔案名稱，用來篩選來源檔案。
允許的萬用字元為：* (符合零或多個字元) 和 ? (符合零或單一字元)。 若檔案名稱具有萬用字元或逸出字元 ^，則請使用此逸出字元近性逸出。 如需更多範例，請參閱資料夾和檔案篩選範例。		 Yes
選項 4：檔案清單
- fileListPath		 表示要複製指定的檔案集。 指向含有所要複製檔案清單的文字檔，一行一個檔案，而這是資料集中所設定路徑的相對路徑。
使用此選項時，請不要指定資料集中的檔案名稱。 檔案清單範例有更多範例可供參閱。		 No
其他設定：
遞迴 指出是否從子資料夾、或只有從指定的資料夾，以遞迴方式讀取資料。 請注意，當遞迴設為 true 且接收器是檔案型存放區時，不會在接收器上複製或建立空的資料夾或子資料夾。
允許的值為 true (預設值) 和 false。
設定 fileListPath 時，此屬性不適用。		 No
deleteFilesAfterCompletion 指出成功移至目的地存放區之後，是否要從來源存放區中刪除二進位檔案。 檔案刪除會針對每個檔案執行，因此，當複製活動失敗時，您會看到已將某些檔案複製到目的地，而且已從來源刪除，而其他檔案仍保留在來源存放區上。
此屬性僅適用於二進位檔案複製案例。 預設值：false。		 No
modifiedDatetimeStart 檔案是根據「上次修改時間」屬性進行篩選。
若檔案的上次修改時間大於或等於 modifiedDatetimeStart 且小於 modifiedDatetimeEnd，則會選取檔案。 此時間會套用至國際標準時間時區，格式為「2018-12-01T05:00:00Z」。
屬性可以是 NULL，這表示將不會在資料集中套用任何檔案屬性篩選。 若 modifiedDatetimeStart 有日期時間值，但 modifiedDatetimeEnd 為 NULL，則將會選取上次修改時間屬性大於或等於該日期時間值的檔案。 若 modifiedDatetimeEnd 有日期時間值，但 modifiedDatetimeStart 為 NULL，則將會選取上次修改時間屬性小於該日期時間值的檔案。
設定 fileListPath 時，此屬性不適用。		 No
modifiedDatetimeEnd 同上。 No
enablePartitionDiscovery 針對已分割的檔案，指定是否要從檔案路徑剖析分割區，並將其新增為其他來源資料行。
允許的值為 false (預設值) 和 true。		 No
partitionRootPath 啟用分割區探索時，請指定絕對根路徑，將已分割的資料夾當成資料行進行讀取。

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

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

範例：

"activities":[
    {
        "name": "CopyFromAmazonS3CompatibleStorage",
        "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": "AmazonS3CompatibleReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

資料夾和檔案篩選範例

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

貯體 索引鍵 遞迴 來源資料夾結構和篩選結果 (會擷取以粗體顯示的檔案)
貯體 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 中的內容 組態
貯體
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    中繼資料
        FileListToCopy.txt		 File1.csv
Subfolder1/File3.csv
Subfolder1/File5.csv		 在資料集中：
- 貯體：bucket
- 資料夾路徑：FolderA

在複製活動來源中：
- 檔案清單路徑：bucket/Metadata/FileListToCopy.txt

檔案清單路徑指向相同資料存放區中的文字檔，其中包括所要複製檔案的清單，且一行一個檔案，並具有資料集中所設定路徑的相對路徑。

查閱活動屬性

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

GetMetadata 活動屬性

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

刪除活動屬性

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

相關內容

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