通过 REST API 引入状态（预览版）

引入状态 REST API 允许监视排队引入作的进度和结果。此终结点提供有关引入请求中的每个 Blob 的详细信息，包括成功、失败或正在进行的状态。

Permissions

若要使用 REST API 引入状态，需要：

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

HTTP 终结点

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

参数	类型	必选	Description
`database`	`string`	✔️	目标数据库的名称。
`table`	`string`	✔️	目标表的名称。
`operationId`	`string`	✔️	从排队引入终结点返回的引入作 ID。

查询参数

参数	类型	必选	Description
`details`	`bool`	否	控制是否显示每个 Blob 的详细信息。默认为 `false`。

Example

无详细信息的请求

GET /v1/rest/ingestion/queued/MyDatabase/MyTable/ingest_op_12345
Authorization: Bearer <access_token>

包含详细信息的请求

GET /v1/rest/ingestion/queued/MyDatabase/MyTable/ingest_op_12345?details=true
Authorization: Bearer <access_token>

响应

响应架构

顶级字段

领域	类型	Description
`startTime`	`timestamp`	引入作启动的时间。
`lastUpdated`	`timestamp`	上次更新或完成作的时间。
`status`	`object`	一个对象，其中包含每个状态类别的 blob 计数。
`details`	`array`	Blob 详细信息对象的数组。仅当。`details=true`

Status 对象

领域	类型	Description
`Succeeded`	`integer`	成功引入的 Blob 数。
`Failed`	`integer`	未能引入的 Blob 数。
`InProgress`	`integer`	当前正在引入的 Blob 数。

Blob 详细信息对象

仅当 details 查询参数设置为 true..

领域	类型	Description
`sourceId`	`string`	Blob 的源 ID。
`url`	`string`	Blob 的 URL。
`status`	`string`	Blob 的状态： `InProgress`、 `Succeeded`、 `Failed`或 `Canceled`。
`startTime`	`timestamp`	Blob 引入开始的时间。
`lastUpdated`	`timestamp`	Blob 引入完成或上次更新的时间。
`errorCode`	`string`	描述失败的错误代码。仅当为 `status`.`Failed`
`failureStatus`	`string`	失败分类： `Unknown`、 `Permanent`、 `Transient`或 `Exhausted`。仅当为 `status`.`Failed`
`details`	`string`	描述错误的自由文本。仅当为 `status`.`Failed`

响应示例

仅摘要（details=false）

{
  "startTime": "2025-10-01T12:00:00Z",
  "lastUpdated": "2025-10-01T12:30:00Z",
  "status": {
    "Succeeded": 8,
    "Failed": 1,
    "InProgress": 2,
    "Canceled": 0
  }
}

使用 blob 详细信息（details=true）

{
  "startTime": "2025-10-01T12:00:00Z",
  "lastUpdated": "2025-10-01T12:30:00Z",
  "status": {
    "Succeeded": 1,
    "Failed": 1,
    "InProgress": 1,
    "Canceled": 0
  },
  "details": [
    {
      "sourceId": "123a6999-411e-4226-a333-w79992dd9b95",
      "url": "https://example.com/blob1.csv.gz",
      "status": "Failed",
      "startTime": "2025-10-01T12:00:00Z",
      "lastUpdated": "2025-10-01T12:15:00Z",
      "errorCode": "BadRequest_MissingMappingFailure",
      "failureStatus": "Permanent",
      "details": "Mapping not found"
    },
    {
      "url": "https://example.com/blob2.csv.gz",
      "status": "InProgress",
      "startTime": "2025-10-01T12:05:00Z",
      "lastUpdated": "2025-10-01T12:20:00Z"
    },
    {
      "url": "https://example.com/blob3.csv.gz",
      "status": "Succeeded",
      "startTime": "2025-10-01T12:00:00Z",
      "lastUpdated": "2025-10-01T12:10:00Z"
    }
  ]
}

注释

设置为时，将从ingestionOperationId排队引入终结点获取该终结点enableTrackingtrue。有关详细信息，请参阅通过 REST API 排队引入。

使用提示

定期轮询此终结点以监视长时间运行的引入作。
用于 details=false 快速状态检查以最大程度地减少响应大小。
用于 details=true 排查故障并识别有问题的 Blob。
该 errorCode 字段可用于实现暂时性故障的重试逻辑。
永久失败（例如 BadRequest_MissingMappingFailure）需要在重试之前更改配置。

Last updated on 2025-12-25

通过