你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
.ingest into
.ingest into 命令通过从一个或多个云存储文件“拉取”数据将数据引入表中。
例如，该命令可以从 Azure Blob 存储检索 1,000 个 CSV 格式的 Blob，对其进行分析，并将其一起引入到单个目标表中。
数据将追加到表中，而不会影响现有记录，也不会影响表的架构。
注意
此引入方法适用于探索和原型制作。 请勿在生产或大容量方案中使用它。
注意
此引入方法适用于探索和原型制作。 请勿在生产或大容量方案中使用它。 有关引入选项的详细信息，请参阅 数据引入概述。
权限
必须至少具有 表引入器 权限才能运行此命令。
语法
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
详细了解
参数
| 名字 | 类型 | 必填 | 描述 |
|---|---|---|---|
async |
string |
如果指定，该命令将立即返回并继续在后台引入。 该命令的结果包括一个 OperationId 值，该值随后可与 .show operation 命令一起使用，以检索引入完成状态和结果。 |
|
| TableName | string |
✔️ | 要将数据引入到其中的表的名称。 表名称始终相对于上下文中的数据库。 如果未提供架构映射对象，则使用上下文中的数据库的架构。 |
| SourceDataLocator | string |
✔️ |
注意
建议对 SourceDataLocators使用 模糊字符串文本。 该服务将在内部跟踪和错误消息中清理凭据。
引入属性
重要
在排队引入 数据是使用引入属性批处理的。 使用的不同引入映射属性（如不同的 ConstValue 值）越分散，引入就越分散，这可能会导致性能下降。
下表列出了和支持的属性，并提供示例：
| 财产 | 描述 | 例 |
|---|---|---|
ingestionMapping |
一个字符串值，指示如何将源文件中的数据映射到表中的实际列。 使用相关的映射类型定义 format 值。 请参阅 数据映射。 |
with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")（已弃用： avroMapping、csvMapping、jsonMapping） |
ingestionMappingReference |
一个字符串值，指示如何使用命名映射策略对象将数据从源文件映射到表中的实际列。 使用相关的映射类型定义 format 值。 请参阅 数据映射。 |
with (format="csv", ingestionMappingReference = "Mapping1")（已弃用： avroMappingReference、csvMappingReference、jsonMappingReference） |
creationTime |
在引入的数据区创建时使用的日期/时间值（格式化为ISO8601字符串）。 如果未指定，则使用当前值（now()）。 引入旧数据时，重写默认值非常有用，以便正确应用保留策略。 指定后，请确保目标表的有效 盘区合并策略中的 Lookback 属性 与指定的值保持一致。 |
with (creationTime="2017-02-13") |
extend_schema |
一个布尔值，如果指定，则指示命令扩展表的架构（默认值为 false）。 此选项仅适用于 .append 和 .set-or-append 命令。 唯一允许的架构扩展在末尾将更多列添加到表中。 |
如果原始表架构 (a:string, b:int)，则会 (a:string, b:int, c:datetime, d:string)有效的架构扩展，但 (a:string, c:datetime) 无效 |
folder |
对于 从查询引入 命令，要分配给表的文件夹。 如果该表已存在，则此属性将替代表的文件夹。 | with (folder="Tables/Temporary") |
format |
数据格式（请参阅 支持的数据格式）。 | with (format="csv") |
ingestIfNotExists |
如果表已使用具有相同值的 ingest-by: 标记标记数据，则如果指定了字符串值，则阻止引入成功。 这可确保幂等数据引入。 有关详细信息，请参阅 引入方式：标记。 |
属性 with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') 指示如果标记 ingest-by:Part0001 的数据已存在，则不会完成当前引入。 如果它尚不存在，则此新的引入应设置此标记（如果将来的引入尝试再次引入相同的数据）。 |
ignoreFirstRecord |
一个布尔值，如果设置为 true，则表示引入应忽略每个文件的第一条记录。 如果文件中的第一条记录是列名，则此属性适用于 CSV和类似格式的文件。 默认情况下，假定 false。 |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
一个布尔值，如果指定，则描述是否对此命令创建的表启用 引入时间策略。 默认值为 true。 |
with (policy_ingestiontime=false) |
recreate_schema |
一个布尔值，如果指定，则描述命令是否可以重新创建表的架构。 此属性仅适用于 .set-or-replace 命令。 如果设置了这两个属性，则此属性优先于 extend_schema 属性。 |
with (recreate_schema=true) |
tags |
要与引入的数据关联的 标记列表，格式为 JSON 字符串 | with (tags="['Tag1', 'Tag2']") |
TreatGzAsUncompressed |
一个布尔值，如果设置为 true，则表示扩展名为 .gz 的文件不会被压缩。 从 Amazon AWS S3 引入时，有时需要此标志。 |
with (treatGzAsUncompressed=true) |
validationPolicy |
一个 JSON 字符串，指示在引入使用 CSV 格式表示的数据期间要运行的验证。 有关不同选项的说明，请参阅 数据引入。 |
with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}')（这是默认策略） |
zipPattern |
从具有 ZIP 存档的存储引入数据时，请使用此属性。 这是一个字符串值，指示选择要在 ZIP 存档中引入的文件时要使用的正则表达式。 将忽略存档中的所有其他文件。 | with (zipPattern="*.csv") |
身份验证和授权
每个存储连接字符串指示用于访问存储的授权方法。 根据授权方法，可能需要向主体授予对外部存储的权限才能执行引入。
下表列出了支持的身份验证方法和从外部存储引入数据所需的权限。
| 身份验证方法 | Azure Blob 存储/Data Lake Storage Gen2 | Data Lake Storage Gen1 |
|---|---|---|
| 模拟 | 存储 Blob 数据读取器 | 读者 |
| 共享访问（SAS）令牌 | 列表 + 读取 | Gen1 不支持此身份验证方法。 |
| Microsoft Entra 访问令牌 | ||
| 存储帐户访问密钥 | Gen1 不支持此身份验证方法。 | |
| 托管标识 | 存储 Blob 数据读取器 | 读者 |
返回
该命令的结果是一个表，其中包含由该命令生成的数据分片（“extents”）数尽可能多的记录。 如果未生成任何数据分片，则会返回一条包含空（零值）盘 ID 的记录。
| 名字 | 类型 | 描述 |
|---|---|---|
| ExtentId | guid |
命令生成的数据分片的唯一标识符。 |
| ItemLoaded | string |
与此记录相关的一个或多个存储文件。 |
| 期间 | timespan |
执行引入需要多长时间。 |
| HasErrors | bool |
此记录是否表示引入失败。 |
| OperationId | guid |
表示操作的唯一 ID。 可与 .show operation 命令一起使用。 |
注意
此命令不会修改要引入的表的架构。 如有必要，在引入期间，数据将“强制”到此架构中，而不是另一种方式（忽略额外的列，并且缺失的列被视为 null 值）。
例子
具有共享访问签名的 Azure Blob 存储
以下示例指示数据库将两个 Blob 从 Azure Blob 存储读取为 CSV 文件，并将其内容引入表 T。
... 表示一个 Azure 存储共享访问签名（SAS），该签名提供对每个 Blob 的读取访问权限。 模糊处理的字符串（字符串值前面的 h）用于确保永远不会记录 SAS。
.ingest into table T (
h'https://contoso.blob.core.windows.net/container/file1.csv?...',
h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)
使用托管标识的 Azure Blob 存储
以下示例演示如何从 Azure Blob 存储读取 CSV 文件，并使用托管标识身份验证将其内容引入表 T。 身份验证使用分配给 Azure 中的 Azure Blob 存储的托管标识 ID（对象 ID）。 有关详细信息，请参阅 为存储容器创建托管标识。
.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')
Azure Data Lake Storage Gen 2
以下示例用于从 Azure Data Lake Storage Gen 2（ADLSv2）引入数据。 此处使用的凭据（...）是存储帐户凭据（共享密钥），我们仅对连接字符串的机密部分使用字符串模糊处理。
.ingest into table T (
'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)
Azure Data Lake Storage
以下示例从 Azure Data Lake Storage（ADLS）引入单个文件。 它使用用户的凭据访问 ADLS（因此无需将存储 URI 视为包含机密）。 它还演示如何指定引入属性。
.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
with (format='csv')
具有访问密钥的 Amazon S3
以下示例使用 访问密钥 ID 和机密访问密钥从 Amazon S3 引入单个文件。
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
with (format='csv')
带有预签名 URL 的 Amazon S3
以下示例使用 预签名 URL从 Amazon S3 引入单个文件。
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')