Items - Upgrade Sql Endpoint Metadata Sync

升级指定 SQL 分析终结点的元数据同步。

Note

元数据同步迁移目前为预览版(了解详细信息)。

此 API 支持 长时间运行的作(LRO)。

将终结点的表从 v1 常规表体系结构迁移到 v2 外部表体系结构。 重复调用仅重新尝试未达到 v2 的表。

Permissions

调用方必须对 SQL 分析终结点项具有 写入 权限。

所需的委派范围

Item.ReadWrite.All 或 SQLEndpoint.ReadWrite.All

Microsoft Entra 支持的标识

此 API 支持本节中列出的Microsoft 标识。

Identity 支持
User Yes
服务主体 和 托管标识 Yes

Interface

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlEndpoints/{itemId}/upgradeMetadataSync

URI 参数

名称 在 必需 类型 说明
itemId
path True

string (uuid)

SQL 分析终结点 ID。

workspaceId
path True

string (uuid)

工作区标识符。

响应

名称 类型 说明
200 OK

MetadataSyncMigrationResult

请求成功完成。

202 Accepted

请求接受,正在进行元数据同步升级。


标头:

位置string - 操作状态的 URL,可用于跟踪操作状态。

x-ms-operation-idstring (uuid) - 可用于长时间运行的操作(LRO)API 的操作 ID,用于跟踪操作状态并获取结果。

Retry-Afterinteger - 重试请求之前等待的秒数。

标头

  • Location: string
  • x-ms-operation-id: string
  • Retry-After: integer
429 Too Many Requests

ErrorResponse

超出服务速率限制。 服务器返回一个 Retry-After 标头,指示客户端在发送其他请求之前必须等待的时间(以秒为单位)。

标头

Retry-After: integer

Other Status Codes

ErrorResponse

常见错误代码:

  • ItemNotFound - 找不到请求的项目。

  • LockConflict - SQL 分析终结点正忙于另一个锁定操作。

示例

Upgrade metadata sync example

示例请求

POST https://api.fabric.microsoft.com/v1/workspaces/41ce06d1-d81b-4ea0-bc6d-2ce3dd2f8e87/sqlEndpoints/9b1e77c2-6a4e-4f0b-bd3a-1f2c0d4e5a6b/upgradeMetadataSync

示例响应

{
  "syncArchitectureVersion": "V2",
  "itemMigrationStatus": "PartiallySucceeded",
  "tableStatuses": [
    {
      "schema": "dbo",
      "tableName": "Orders",
      "syncArchitectureVersion": "V2",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:25Z"
    },
    {
      "schema": "dbo",
      "tableName": "OrderDetails",
      "syncArchitectureVersion": "V1",
      "lastSuccessfulSyncDateTime": "2026-06-08T10:15:02Z",
      "error": {
        "errorCode": "DeltaTableNotFound",
        "message": "Delta table 'Tables\\OrderDetails\\_delta_log' was not found."
      }
    }
  ]
}

定义

名称 说明
ErrorParameter

一个结构化参数,提供有关错误的附加计算机可读上下文。

ErrorRelatedResource

与错误相关的资源详细信息对象。

ErrorResponse

错误响应。

ErrorResponseDetails

错误响应详细信息。

ItemMigrationStatus

元数据同步迁移的总体结果。 可能会随着时间的推移添加其他 ItemMigrationStatus 类型。

MetadataSyncMigrationResult

已完成的元数据同步迁移的结果。

MetadataSyncTableMigrationStatus

表的元数据同步迁移状态。

SyncArchitectureVersion

同步体系结构版本。 可能会随着时间的推移添加其他 SyncArchitectureVersion 类型。

ErrorParameter

一个结构化参数,提供有关错误的附加计算机可读上下文。

名称 类型 说明
message

string

参数含义的可读说明。

name

string

参数标识符。

value

string

参数值。

ErrorRelatedResource

与错误相关的资源详细信息对象。

名称 类型 说明
resourceId

string

错误中涉及的资源 ID。

resourceType

string

错误中涉及的资源的类型。

ErrorResponse

错误响应。

名称 类型 说明
errorCode

string

提供有关错误条件的信息的特定标识符,允许服务与其用户之间的标准化通信。

isRetriable

boolean

如果为 true,可以重试请求。 Retry-After使用响应标头确定延迟(如果可用)。

message

string

错误的人工可读表示形式。

moreDetails

ErrorResponseDetails[]

其他错误详细信息的列表。

parameters

ErrorParameter[]

提供有关错误的其他计算机可读上下文的结构化参数。

relatedResource

ErrorRelatedResource

与错误相关的资源详细信息。

requestId

string (uuid)

与错误关联的请求的 ID。

ErrorResponseDetails

错误响应详细信息。

名称 类型 说明
errorCode

string

提供有关错误条件的信息的特定标识符,允许服务与其用户之间的标准化通信。

message

string

错误的人工可读表示形式。

parameters

ErrorParameter[]

提供有关错误的其他计算机可读上下文的结构化参数。

relatedResource

ErrorRelatedResource

与错误相关的资源详细信息。

ItemMigrationStatus

元数据同步迁移的总体结果。 可能会随着时间的推移添加其他 ItemMigrationStatus 类型。

值 说明
Succeeded

迁移已完成,没有表无法转换。

PartiallySucceeded

至少有一个表达到了目标体系结构,至少一个表无法转换。

Failed

需要转换的每个表都失败,终结点仍保留在其以前的体系结构中。

MetadataSyncMigrationResult

已完成的元数据同步迁移的结果。

名称 类型 说明
itemMigrationStatus

ItemMigrationStatus

迁移的总体结果。

syncArchitectureVersion

SyncArchitectureVersion

迁移后终结点的同步体系结构版本。

tableStatuses

MetadataSyncTableMigrationStatus[]

终结点上每个表的迁移状态。

MetadataSyncTableMigrationStatus

表的元数据同步迁移状态。

名称 类型 说明
error

ErrorResponseDetails

已停止或失败表的错误详细信息。 当表没有错误时,省略此属性。

lastSuccessfulSyncDateTime

string (date-time)

如果表从未成功同步,则会省略此属性。 表上次以 UTC 方式成功同步的日期和时间,使用 YYYY-MM-DDTHH:mm:ssZ 格式。

schema

string

表的架构名称。

syncArchitectureVersion

SyncArchitectureVersion

表当前正在使用的同步体系结构版本。

tableName

string

表的非限定名称。

SyncArchitectureVersion

同步体系结构版本。 可能会随着时间的推移添加其他 SyncArchitectureVersion 类型。

值 说明
V1

v1 常规表同步体系结构。

V2

v2 外部表同步体系结构。