通过使用 Azure 数据工厂从 Amazon S3 兼容存储中复制数据

适用于: Azure 数据工厂

本文概述了如何从 Amazon 简单存储服务 (Amazon S3) 兼容存储中复制数据。 若要了解 Azure 数据工厂,请阅读介绍性文章

支持的功能

以下活动支持此 Amazon S3 兼容存储连接器:

具体而言,此 Amazon S3 兼容存储连接器支持按原样复制文件,或者使用受支持的文件格式和压缩编解码器来分析文件。 此连接器使用 AWS 签名版本 4 对发往 S3 的请求进行身份验证。 可以使用此 Amazon S3 兼容存储连接器从任何兼容 S3 的存储提供程序复制数据。 在链接的服务配置中指定相应的服务 URL。

所需的权限

若要从 Amazon S3 兼容存储复制数据,请确保你已获得以下 Amazon S3 对象操作权限:s3:GetObjects3:GetObjectVersion

如果使用数据工厂 UI 进行创作,则需要额外的 s3:ListAllMyBucketss3:ListBucket/s3:GetBucketLocation 权限,才能执行诸如测试与链接服务的连接、从根目录浏览之类的操作。 如果不想授予这些权限,则可以选择 UI 中的“测试与文件路径的连接”或“从指定路径浏览”选项。

如需 Amazon S3 权限的完整列表,请参阅 AWS 站点上的在策略中指定权限

入门

若要使用管道执行复制活动,可以使用以下工具或 SDK 之一:

以下部分提供了关于一些属性的详细信息,这些属性用于定义特定于 Amazon S3 兼容存储的数据工厂实体。

链接服务属性

Amazon S3 兼容链接服务支持以下属性:

属性 说明 必需
type type 属性必须设置为 AmazonS3Compatible 。
accessKeyId 机密访问键 ID。
secretAccessKey 机密访问键本身。 将此字段标记为 SecureString 以安全地将其存储在数据工厂中或 引用存储在 Azure Key Vault 中的机密
serviceUrl 指定自定义 S3 终结点 https://<service url>
forcePathStyle 指示是否使用 S3 路径样式访问而不是使用虚拟托管样式访问。 允许的值为:false(默认)和 true 。
检查每个数据存储的文档,了解是否需要路径样式访问。
connectVia 用于连接到数据存储的集成运行时。 可使用 Azure Integration Runtime 或自承载集成运行时(如果数据存储位于专用网络中)。 如果未指定此属性,服务会使用默认的 Azure Integration Runtime。

示例:

{
    "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 数据工厂支持以下文件格式。 请参阅每一篇介绍基于格式的设置的文章。

Amazon S3 兼容存储支持基于格式的数据集中 location 设置下的以下属性:

属性 说明 必需
type 数据集中 location 下的 type 属性必须设置为 AmazonS3CompatibleLocation 。
bucketName S3 兼容存储 Bucket 名称。
folderPath 给定 Bucket 下的文件夹路径。 如果要使用通配符来筛选文件夹,请跳过此设置并在活动源设置中进行相应的指定。
fileName 给定 Bucket 和文件夹路径下的文件名。 如果要使用通配符来筛选文件,请跳过此设置并在活动源设置中进行相应的指定。
版本 S3 兼容存储对象的版本(如果已启用 S3 兼容存储版本控制)。 如果未指定,则会提取最新版本。

示例:

{
    "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 数据工厂支持以下文件格式。 请参阅每一篇介绍基于格式的设置的文章。

Amazon S3 兼容存储支持基于格式的复制源中 storeSettings 设置下的以下属性:

属性 说明 必需
type storeSettings 下的 type 属性必须设置为 AmazonS3CompatibleReadSettings 。
找到要复制的文件:
选项 1:静态路径
从数据集中指定的给定存储桶或文件夹/文件路径复制。 若要复制 Bucket 或文件夹中的所有文件,请另外将 wildcardFileName 指定为 *
选项 2:S3 兼容存储前缀
- prefix
数据集中配置的给定 Bucket 下 S3 兼容存储密钥名称的前缀,用于筛选源 S3 兼容存储文件。 选择了名称以 bucket_in_dataset/this_prefix 开头的 S3 兼容存储密钥。 它利用 S3 兼容存储的服务端筛选器,该筛选器提供比通配符筛选器更好的性能。

在使用前缀的情况下选择复制到基于文件的接收器并保留层次结构时,请注意,系统会保留前缀中最后一个“/”后面的子路径。 例如,如果在源为 bucket/folder/subfolder/file.txt 的情况下将前缀配置为 folder/sub,则保留的文件路径为 subfolder/file.txt
选项 3:通配符
- wildcardFolderPath
数据集中配置的给定 Bucket 下包含通配符的文件夹路径,用于筛选源文件夹。
允许的通配符为:*(匹配零个或更多字符)和 ?(匹配零个或单个字符)。 如果文件夹名内包含通配符或此转义字符,请使用 ^ 进行转义。
请参阅文件夹和文件筛选器示例中的更多示例。
选项 3:通配符
- wildcardFileName
给定 Bucket 和文件夹路径(或通配符文件夹路径)下包含通配符的文件名,用于筛选源文件。
允许的通配符为:*(匹配零个或更多字符)和 ?(匹配零个或单个字符)。 如果文件名包含通配符或此转义字符,请使用 ^ 进行转义。 请参阅文件夹和文件筛选器示例中的更多示例。
选项 4:文件列表
- fileListPath
指明复制给定文件集。 指向包含要复制的文件列表的文本文件,其中每行一个文件(即数据集中所配置路径的相对路径)。
使用此选项时,请不要在数据集中指定文件名。 请参阅文件列表示例中的更多示例。
其他设置:
recursive 指示是要从子文件夹中以递归方式读取数据,还是只从指定的文件夹中读取数据。 请注意,当 recursive 设置为 true 且接收器是基于文件的存储时,将不会在接收器上复制或创建空的文件夹或子文件夹。
允许的值为 true(默认值)和 false
如果配置 fileListPath,则此属性不适用。
deleteFilesAfterCompletion 指示是否会在二进制文件成功移到目标存储后将其从源存储中删除。 文件删除按文件进行。因此,当复制活动失败时,你会看到一些文件已经复制到目标并从源中删除,而另一些文件仍保留在源存储中。
此属性仅在二进制文件复制方案中有效。 默认值:false。
modifiedDatetimeStart 文件根据“上次修改时间”属性进行筛选。
如果文件的上次修改时间在 modifiedDatetimeStartmodifiedDatetimeEnd 之间的时间范围内,则将选中这些文件。 该时间应用于 UTC 时区,格式为“2018-12-01T05:00:00Z”。
属性可以为 NULL,这意味着不会向数据集应用任何文件属性筛选器。 如果 modifiedDatetimeStart 具有日期/时间值,但 modifiedDatetimeEnd 为 NULL,则会选中“上次修改时间”属性大于或等于该日期/时间值的文件。 如果 modifiedDatetimeEnd 具有日期/时间值,但 modifiedDatetimeStart 为 NULL,则会选中“上次修改时间”属性小于该日期/时间值的文件。
如果配置 fileListPath,则此属性不适用。
modifiedDatetimeEnd 同上。
enablePartitionDiscovery 对于已分区的文件,请指定是否从文件路径分析分区,并将它们添加为附加的源列。
允许的值为 false(默认)和 true 。
partitionRootPath 启用分区发现时,请指定绝对根路径,以便将已分区文件夹读取为数据列。

如果未指定,默认情况下,
- 在数据集或源的文件列表中使用文件路径时,分区根路径是在数据集中配置的路径。
- 使用通配符文件夹筛选器时,分区根路径是第一个通配符前的子路径。
- 在使用前缀时,分区根路径是最后一个“/”前的子路径。

例如,假设你将数据集中的路径配置为“root/folder/year=2020/month=08/day=27”:
- 如果将分区根路径指定为“root/folder/year=2020”,则除了文件内的列外,复制活动还将生成另外两个列 monthday,其值分别为“08”和“27”。
- 如果未指定分区根路径,则不会生成额外的列。
maxConcurrentConnections 活动运行期间与数据存储建立的并发连接的上限。 仅在要限制并发连接时指定一个值。

示例:

"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>"
            }
        }
    }
]

文件夹和文件筛选器示例

本部分介绍使用通配符筛选器生成文件夹路径和文件名的行为。

Bucket key recursive 源文件夹结构和筛选器结果(用粗体表示的文件已检索)
Bucket Folder*/* false Bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv
Bucket Folder*/* true Bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv
Bucket Folder*/*.csv false Bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv
Bucket Folder*/*.csv true Bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv

文件列表示例

本部分介绍了在复制活动源中使用文件列表路径时产生的行为。

假设有以下源文件夹结构,并且要复制以粗体显示的文件:

示例源结构 FileListToCopy.txt 中的内容 数据工厂配置
Bucket
    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

文件列表路径指向同一数据存储中的一个文本文件,该文件包含要复制的文件列表(每行一个文件,使用数据集中所配置路径的相对路径)。

查找活动属性

若要了解有关属性的详细信息,请查看 Lookup 活动

GetMetadata 活动属性

若要了解有关属性的详细信息,请查看 GetMetadata 活动

Delete 活动属性

若要了解有关属性的详细信息,请查看删除活动

后续步骤

有关数据存储(Azure 数据工厂中的复制活动支持将其用作源和接收器)的列表,请参阅支持的数据存储