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 參數

名稱 位於 必要 類型 Description
sqlEndpointId
 path True

string (uuid)

SQL 分析端點識別碼。
workspaceId
 path True

string (uuid)

工作區識別碼。

要求本文

名稱 類型 Description
recreateTables

boolean

當此屬性設為 true 時，系統會在刷新過程中丟棄並重建 SQL 分析端點上的所有資料表。 例如，如果你需要從資料表的原始定義完全重建，以解決不一致或確保乾淨刷新，請使用此選項。 與 結合 tables時，同步狀態重置僅限於指定的資料表。 預設值為 false。
tables

TableDefinition[]

提供時，刷新範圍僅限於列出的資料表。 當資料表被省略或空置時，所有資料表都會被重新整理。 每個項目都指定一個結構，以及一個或多個表格名稱，需在該架構下重新整理。 單一請求中最多可同步的表格數量為 25 個。 資料表解析取決於 SQL 端點的父項目是否啟用 schema。 對於啟用結構的項目，資料表會透過呼叫者提供的結構來解析。 對於非 schema 啟用的項目，所有資料表都會依預設架構解析，無論呼叫者提供的結構值為何;非預設結構下的表格無法解析，並會以錯誤報告 DeltaTableNotFound 。
timeout

Duration

逾時前的要求持續時間。預設值為15分鐘。

回應

名稱 類型 Description
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"
    }
  ]
}

定義

名稱 Description
Duration

持續時間。
ErrorRelatedResource

錯誤相關的資源詳細資料物件。
ErrorResponse

錯誤回應。
ErrorResponseDetails

錯誤回應詳細數據。
SqlEndpointRefreshMetadataRequest

用於刷新 SQL 分析端點的請求有效載荷。
SyncStatus

同步處理作業的狀態。 可能會隨著時間新增其他 SyncStatus 類型。
TableDefinition

一對結構名稱和資料表名稱，用於設定選擇性刷新範圍。
TableSyncStatus

數據表同步處理狀態物件。
TableSyncStatuses

數據表同步處理狀態的清單。
TimeUnit

持續時間的時間單位。 可能會隨著時間新增其他持續時間類型。

Duration

Object

持續時間。

名稱 類型 Description
timeUnit

TimeUnit

持續時間的時間單位。 可能會隨著時間新增其他持續時間類型。
value

number

持續時間中的 timeUnits 數目。

ErrorRelatedResource

Object

錯誤相關的資源詳細資料物件。

名稱 類型 Description
resourceId

string

發生錯誤的資源識別碼。
resourceType

string

發生錯誤的資源類型。

ErrorResponse

Object

錯誤回應。

名稱 類型 Description
errorCode

string

提供錯誤狀況相關信息的特定標識碼，允許服務與其使用者之間的標準化通訊。
isRetriable

boolean

若屬實，請求可重新嘗試。 如果有延遲，請使用 Retry-After 回應標頭來判斷延遲。
message

string

錯誤的人類可讀取表示法。
moreDetails

ErrorResponseDetails[]

其他錯誤詳細數據的清單。
relatedResource

ErrorRelatedResource

錯誤相關的資源詳細數據。
requestId

string (uuid)

與錯誤相關聯的要求標識碼。

ErrorResponseDetails

Object

錯誤回應詳細數據。

名稱 類型 Description
errorCode

string

提供錯誤狀況相關信息的特定標識碼，允許服務與其使用者之間的標準化通訊。
message

string

錯誤的人類可讀取表示法。
relatedResource

ErrorRelatedResource

錯誤相關的資源詳細數據。

SqlEndpointRefreshMetadataRequest

Object

用於刷新 SQL 分析端點的請求有效載荷。

名稱 類型 Description
recreateTables

boolean

當此屬性設為 true 時，系統會在刷新過程中丟棄並重建 SQL 分析端點上的所有資料表。 例如，如果你需要從資料表的原始定義完全重建，以解決不一致或確保乾淨刷新，請使用此選項。 與 結合 tables時，同步狀態重置僅限於指定的資料表。 預設值為 false。
tables

TableDefinition[]

提供時，刷新範圍僅限於列出的資料表。 當資料表被省略或空置時，所有資料表都會被重新整理。 每個項目都指定一個結構，以及一個或多個表格名稱，需在該架構下重新整理。 單一請求中最多可同步的表格數量為 25 個。 資料表解析取決於 SQL 端點的父項目是否啟用 schema。 對於啟用結構的項目，資料表會透過呼叫者提供的結構來解析。 對於非 schema 啟用的項目，所有資料表都會依預設架構解析，無論呼叫者提供的結構值為何;非預設結構下的表格無法解析，並會以錯誤報告 DeltaTableNotFound 。
timeout

Duration

逾時前的要求持續時間。預設值為15分鐘。

SyncStatus

列舉型別

同步處理作業的狀態。 可能會隨著時間新增其他 SyncStatus 類型。

值 Description
Success

表示成功。
Failure

表示失敗。
NotRun

表示作業未執行。

TableDefinition

Object

一對結構名稱和資料表名稱，用於設定選擇性刷新範圍。

名稱 類型 Description
schema

string

minLength: 1
maxLength: 128

表格解析的結構名稱。 不能是保留系統架構。
tableNames

string[]

minLength: 1
maxLength: 128

在指定的結構下，一個或多個資料表名稱來刷新。

TableSyncStatus

Object

數據表同步處理狀態物件。

名稱 類型 Description
endDateTime

string (date-time)

使用YYYY-MM-DDTHH：mm：ssZ格式，以UTC完成數據表同步處理的日期和時間。
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 的項目，表名稱會以結構名稱作為前綴（例如「schema.tableName」）。

TableSyncStatuses

Object

數據表同步處理狀態的清單。

名稱 類型 Description
value

TableSyncStatus[]

數據表同步處理狀態的清單。

TimeUnit

列舉型別

持續時間的時間單位。 可能會隨著時間新增其他持續時間類型。

值 Description
Seconds

持續時間以秒為單位。
Minutes

以分鐘為單位的持續時間。
Hours

以小時為單位的持續時間。
Days

以天為單位的持續時間。