Items - Refresh Sql Endpoint Metadata

服务:
SQLEndpoint
API 版本:
v1

刷新 SQL 分析终结点中的表。
此 API 支持 长时间运行的作（LRO）。

在请求正文中提供时 tables ，只会刷新指定的表。 省略或为空时，将刷新所有表。

Permissions

调用方必须具有 参与者 或更高版本的工作区角色。

所需的委派范围

Item.ReadWrite.All

Microsoft Entra 支持的标识

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

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

Interface

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlEndpoints/{sqlEndpointId}/refreshMetadata

URI 参数

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

string (uuid)

SQL 分析终结点 ID。
workspaceId
 path True

string (uuid)

工作区 ID。

请求正文

名称 类型 说明
recreateTables

boolean

如果设置为 true，则此属性指示系统在刷新过程中删除并重新创建 SQL 分析终结点上的所有表。 如果需要从源定义中完全重新生成表，例如，若要解决不一致问题或确保刷新干净，请使用此选项。 结合 tables时，同步状态重置的范围仅限定为指定的表。 默认值为 false。
tables

TableDefinition[]

提供时，将刷新范围限定为仅列出的表。 省略或为空时，将刷新所有表。 每个条目指定要在该架构下刷新的架构和一个或多个表名。 单个请求中可同步的最大表数为 25。 表解析取决于 SQL 终结点的父项是否已启用架构。 对于启用架构的项，表是使用调用方提供的架构解析的。 对于未启用架构的项，无论调用方提供的架构值如何，所有表都解析在默认架构下;无法解析非默认架构下的表，并报告有 DeltaTableNotFound 错误。
timeout

Duration

超时前的请求持续时间。默认值为 15 分钟。

响应

名称 类型 说明
200 OK

TableSyncStatuses

请求成功完成。
202 Accepted

请求已接受，SQL 分析表正在进行刷新。

标头

  • 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 - 找不到请求的项目。

示例

Refresh all tables for a specified SQL analytics endpoint in a workspace
Refresh selective tables for a specified SQL analytics endpoint in a workspace
Refresh selective tables with recreate tables for a specified SQL analytics endpoint in a workspace
Refresh selective tables with user defined schemas for a specified SQL analytics endpoint in a workspace

Refresh all tables for a specified SQL analytics endpoint in a workspace

示例请求

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/sqlEndpoints/5b218778-e7a5-4d73-8187-f10824047715/refreshMetadata

示例响应

状态代码:
200 
{
  "value": [
    {
      "tableName": "Table 1",
      "startDateTime": "2025-08-08T10:31:22.2708973Z",
      "endDateTime": "2025-08-08T10:36:54.9651741Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2025-08-08T10:36:54.9651741Z"
    },
    {
      "tableName": "Table 2",
      "startDateTime": "2025-08-08T10:31:22.2708973Z",
      "endDateTime": "2025-08-08T10:43:02.5329616Z",
      "status": "Failure",
      "error": {
        "errorCode": "AdalRetryException",
        "message": "Couldn't run query. There is a problem with the Microsoft Entra ID token. Have the warehouse owner log in again. If they're unavailable, use the takeover feature."
      },
      "lastSuccessfulSyncDateTime": "2025-08-07T10:44:27.2632648Z"
    },
    {
      "tableName": "Table 3",
      "startDateTime": "2025-08-08T10:31:22.2708973Z",
      "endDateTime": "2025-08-08T10:36:59.9183509Z",
      "status": "NotRun",
      "lastSuccessfulSyncDateTime": "2025-08-06T08:32:53.3890146Z"
    }
  ]
}

Refresh selective tables for a specified SQL analytics endpoint in a workspace

示例请求

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/sqlEndpoints/5b218778-e7a5-4d73-8187-f10824047715/refreshMetadata

{
  "tables": [
    {
      "schema": "dbo",
      "tableNames": [
        "Orders",
        "OrderDetails"
      ]
    },
    {
      "schema": "dbo",
      "tableNames": [
        "DailySummary"
      ]
    }
  ]
}

示例响应

状态代码:
200 
{
  "value": [
    {
      "tableName": "Orders",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:25.9651741Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:25.9651741Z"
    },
    {
      "tableName": "OrderDetails",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:26.5329616Z",
      "status": "Failure",
      "error": {
        "errorCode": "DeltaTableNotFound",
        "message": "Delta table 'Tables\\OrderDetails\\_delta_log' not found."
      },
      "lastSuccessfulSyncDateTime": "2026-06-08T10:31:26.5329616Z"
    },
    {
      "tableName": "DailySummary",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:24.9183509Z",
      "status": "NotRun",
      "lastSuccessfulSyncDateTime": "2026-06-08T08:32:53.3890146Z"
    }
  ]
}

Refresh selective tables with recreate tables for a specified SQL analytics endpoint in a workspace

示例请求

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/sqlEndpoints/5b218778-e7a5-4d73-8187-f10824047715/refreshMetadata

{
  "recreateTables": true,
  "tables": [
    {
      "schema": "dbo",
      "tableNames": [
        "Orders",
        "OrderDetails"
      ]
    }
  ]
}

示例响应

状态代码:
200 
{
  "value": [
    {
      "tableName": "Orders",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:25.9651741Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:25.9651741Z"
    },
    {
      "tableName": "OrderDetails",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:26.5329616Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:26.5329616Z"
    }
  ]
}

Refresh selective tables with user defined schemas for a specified SQL analytics endpoint in a workspace

示例请求

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/sqlEndpoints/5b218778-e7a5-4d73-8187-f10824047715/refreshMetadata

{
  "tables": [
    {
      "schema": "sales",
      "tableNames": [
        "Orders",
        "OrderDetails"
      ]
    },
    {
      "schema": "analytics",
      "tableNames": [
        "DailySummary"
      ]
    }
  ]
}

示例响应

状态代码:
200 
{
  "value": [
    {
      "tableName": "sales.Orders",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:25.9651741Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:25.9651741Z"
    },
    {
      "tableName": "sales.OrderDetails",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:26.5329616Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:26.5329616Z"
    },
    {
      "tableName": "analytics.DailySummary",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:24.9183509Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:24.9183509Z"
    }
  ]
}

定义

名称 说明
Duration

持续时间。
ErrorRelatedResource

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

错误响应。
ErrorResponseDetails

错误响应详细信息。
SqlEndpointRefreshMetadataRequest

用于刷新 SQL 分析终结点的请求有效负载。
SyncStatus

同步作的状态。 可能会随着时间的推移添加其他 SyncStatus 类型。
TableDefinition

一对架构和表名称，用于确定选择性刷新的范围。
TableSyncStatus

表同步状态对象。
TableSyncStatuses

表同步状态的列表。
TimeUnit

持续时间的时间单位。 可能会随着时间的推移添加其他持续时间类型。

Duration

对象

持续时间。

名称 类型 说明
timeUnit

TimeUnit

持续时间的时间单位。 可能会随着时间的推移添加其他持续时间类型。
value

number

持续时间中的 timeUnits 数。

ErrorRelatedResource

对象

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

名称 类型 说明
resourceId

string

错误中涉及的资源 ID。
resourceType

string

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

ErrorResponse

对象

错误响应。

名称 类型 说明
errorCode

string

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

boolean

如果为 true，可以重试请求。 Retry-After使用响应标头确定延迟（如果可用）。
message

string

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

ErrorResponseDetails[]

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

ErrorRelatedResource

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

string (uuid)

与错误关联的请求的 ID。

ErrorResponseDetails

对象

错误响应详细信息。

名称 类型 说明
errorCode

string

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

string

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

ErrorRelatedResource

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

SqlEndpointRefreshMetadataRequest

对象

用于刷新 SQL 分析终结点的请求有效负载。

名称 类型 说明
recreateTables

boolean

如果设置为 true，则此属性指示系统在刷新过程中删除并重新创建 SQL 分析终结点上的所有表。 如果需要从源定义中完全重新生成表，例如，若要解决不一致问题或确保刷新干净，请使用此选项。 结合 tables时，同步状态重置的范围仅限定为指定的表。 默认值为 false。
tables

TableDefinition[]

提供时，将刷新范围限定为仅列出的表。 省略或为空时，将刷新所有表。 每个条目指定要在该架构下刷新的架构和一个或多个表名。 单个请求中可同步的最大表数为 25。 表解析取决于 SQL 终结点的父项是否已启用架构。 对于启用架构的项，表是使用调用方提供的架构解析的。 对于未启用架构的项，无论调用方提供的架构值如何，所有表都解析在默认架构下;无法解析非默认架构下的表，并报告有 DeltaTableNotFound 错误。
timeout

Duration

超时前的请求持续时间。默认值为 15 分钟。

SyncStatus

枚举

同步作的状态。 可能会随着时间的推移添加其他 SyncStatus 类型。

值 说明
Success

指示成功。
Failure

指示失败。
NotRun

指示作未运行。

TableDefinition

对象

一对架构和表名称，用于确定选择性刷新的范围。

名称 类型 说明
schema

string

minLength: 1
maxLength: 128

表解析的架构名称。 不能是保留的系统架构。
tableNames

string[]

minLength: 1
maxLength: 128

在指定的架构下刷新的一个或多个表名。

TableSyncStatus

对象

表同步状态对象。

名称 类型 说明
endDateTime

string (date-time)

使用 YYYY-MM-DDTHH：mm：ssZ 格式完成表同步的日期和时间。
error

ErrorResponseDetails

错误响应详细信息
lastSuccessfulSyncDateTime

string (date-time)

使用 YYYY-MM-DDTHH：mm：ssZ 格式的表同步成功时的日期和时间。
startDateTime

string (date-time)

使用 YYYY-MM-DDTHH：mm：ssZ 格式启动表同步的日期和时间。
status

SyncStatus

表是否同步而不出错。
tableName

string

同步的表的名称。 对于启用架构的项，表名称以架构名称（例如“schema.tableName”）为前缀。

TableSyncStatuses

对象

表同步状态的列表。

名称 类型 说明
value

TableSyncStatus[]

表同步状态的列表。

TimeUnit

枚举

持续时间的时间单位。 可能会随着时间的推移添加其他持续时间类型。

值 说明
Seconds

持续时间（以秒为单位）。
Minutes

持续时间（以分钟为单位）。
Hours

持续时间（以小时为单位）。
Days

持续时间（以天为单位）。