通过 REST API 队列导入

队列引入 REST API 允许以编程方式将一个或多个 Blob 提交到指定的数据库和表中。此方法非常适合需要动态触发引入的自动化工作流和外部系统。

Permissions

若要使用 REST API 进行排队引入，需要：

具有表范围将数据引入现有表的引入器角色。
用于访问目标数据库的数据库用户角色。
Blob 存储容器上的存储 Blob 数据读取者角色。

HTTP 终结点

URL: /v1/rest/ingestion/queued/{database}/{table}
Method: POST

参数	类型	必选	Description
`database`	`string`	✔️	目标数据库的名称。
`table`	`string`	✔️	目标表的名称。

请求正文参数

请求必须是具有以下结构的 JSON 对象。

顶级字段

领域	类型	必选	Description
`blobs`	`array`	✔️	要引入的 Blob 对象的列表。有关详细信息，请参阅 Blob 对象。
`properties`	`object`	✔️	包含引入属性的对象。请参阅支持的引入属性。
`timestamp`	`datetime`	否	可选时间戳，指示何时创建引入请求。

Blob 对象

数组中的每个 blobs 项都必须遵循以下结构：

领域	类型	必选	Description
`url`	`string`	✔️	要引入的 Blob 的 URL。此服务对此字段执行轻验证。
`sourceId`	`Guid`	否	源 blob 的标识符。
`rawSize`	`integer`	否	压缩前 Blob 的大小（可为 null）。

支持的引入属性

资产	类型	Description
`format`	`string`	数据格式（例如，`csv`）。 `json`
`enableTracking`	`bool`	如果 `true`返回状态跟踪， `ingestionOperationId` 则返回状态跟踪。
`tags`	`array`	要与引入的数据关联的标记列表。
`skipBatching`	`bool`	如果 `true`禁用 Blob 批处理。
`deleteAfterDownload`	`bool`	如果 `true`，则引入后删除 Blob。
`ingestionMappingReference`	`string`	对预定义的引入映射的引用。
`creationTime`	`string`	ISO8601引入的数据区时间戳。
`ingestIfNotExists`	`array`	如果已存在具有匹配标记的数据，则防止引入。
`ignoreFirstRecord`	`bool`	如果 `true`跳过第一条记录（例如标题行）。
`validationPolicy`	`string`	定义验证行为的 JSON 字符串。
`zipPattern`	`string`	用于从压缩 Blob 中提取文件的正则表达式模式。

Example

POST /v1/rest/ingestion/queued/MyDatabase/MyTable
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "timestamp": "2025-10-01T12:00:00Z",
  "blobs": [
    {
      "url": "https://example.com/blob1.csv.gz",
      "sourceId": "123a6999-411e-4226-a333-w79992dd9b95",
      "rawSize": 1048576
    }
  ],
  "properties": {
    "format": "csv",
    "enableTracking": true,
    "tags": ["ingest-by:rest"],
    "ingestionMappingReference": "csv_mapping",
    "creationTime": "2025-10-01T11:00:00Z"
  }
}

注释

设置 "enableTracking": true 将在响应中返回一个非空 ingestionOperationId 值，该响应可用于使用作结果 - 获取监视引入状态。

响应

Condition	响应
已启用跟踪（`enableTracking: true`）	返回 nonempty `ingestionOperationId`。
跟踪已禁用或省略	返回一个空 `ingestionOperationId`。

已启用跟踪

{
  "ingestionOperationId": "ingest_op_12345"
}

已禁用跟踪

{
  "ingestionOperationId": ""
}

性能提示

每个请求最多提交 20 个 Blob 。
不支持在单个请求中提交 20 多个 Blob。
用于 enableTracking 通过状态终结点监视引入状态。
除非引入延迟至关重要，否则请避免设置 skipBatching 。

Last updated on 2025-11-12

通过