Items - Refresh Sql Endpoint Metadata

Servizio:
SQLEndpoint
Versione API:
v1

Aggiorna le tabelle all'interno di un endpoint di analisi SQL.
Questa API supporta operazioni con esecuzione prolungata (LRO).

Quando tables viene specificato nel corpo della richiesta, vengono aggiornate solo le tabelle specificate. Se omesso o vuoto, tutte le tabelle vengono aggiornate.

Permissions

Il chiamante deve avere ruolo collaboratore o superiore dell'area di lavoro.

Ambiti delegati obbligatori

Item.ReadWrite.All

Identità supportate da Microsoft Entra

Questa API supporta le identità di Microsoft elencate in questa sezione.

Identity Support
User Yes
Principale del servizio e Identità gestite Yes

Interface

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

Parametri dell'URI

Nome In Necessario Tipo Descrizione
sqlEndpointId
 path True

string (uuid)

ID endpoint di analisi SQL.
workspaceId
 path True

string (uuid)

L’ID dell’area di lavoro.

Corpo della richiesta

Nome Tipo Descrizione
recreateTables

boolean

Se impostato su true, questa proprietà indica al sistema di eliminare e ricreare tutte le tabelle nell'endpoint di analisi SQL durante il processo di aggiornamento. Usare questa opzione se è necessario ricompilare completamente le tabelle dalle relative definizioni di origine, ad esempio per risolvere le incoerenze o assicurarsi un aggiornamento pulito. Se combinato con tables, la reimpostazione dello stato di sincronizzazione ha come ambito solo le tabelle specificate. Il valore predefinito è false.
tables

TableDefinition[]

Se specificato, definisce l'ambito dell'aggiornamento solo alle tabelle elencate. Se omesso o vuoto, tutte le tabelle vengono aggiornate. Ogni voce specifica uno schema e uno o più nomi di tabella da aggiornare in tale schema. Il numero massimo di tabelle che è possibile sincronizzare in una singola richiesta è 25. La risoluzione delle tabelle dipende dal fatto che l'elemento padre dell'endpoint SQL sia abilitato per lo schema. Per gli elementi abilitati per lo schema, le tabelle vengono risolte usando lo schema fornito dal chiamante. Per gli elementi non abilitati allo schema, tutte le tabelle vengono risolte nello schema predefinito indipendentemente dal valore dello schema fornito dal chiamante; Le tabelle con uno schema non predefinito non possono essere risolte e verranno segnalate con un DeltaTableNotFound errore.
timeout

Duration

Durata della richiesta prima del timeout. Il valore predefinito è 15 minuti.

Risposte

Nome Tipo Descrizione
200 OK

TableSyncStatuses

Richiesta completata correttamente.
202 Accepted

Richiesta accettata, aggiornamento della tabella di analisi SQL in corso.

Intestazioni

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

ErrorResponse

È stato superato il limite di velocità del servizio. Il server restituisce un'intestazione Retry-After che indica, in secondi, per quanto tempo il client deve attendere prima di inviare richieste aggiuntive.

Intestazioni

Retry-After: integer
Other Status Codes

ErrorResponse

Codici di errore comuni:

  • ItemNotFound: l'elemento richiesto non è stato trovato.

Esempio

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

Esempio di richiesta

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

Risposta di esempio

Codice di stato:
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

Esempio di richiesta

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"
      ]
    }
  ]
}

Risposta di esempio

Codice di stato:
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

Esempio di richiesta

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"
      ]
    }
  ]
}

Risposta di esempio

Codice di stato:
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

Esempio di richiesta

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"
      ]
    }
  ]
}

Risposta di esempio

Codice di stato:
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"
    }
  ]
}

Definizioni

Nome Descrizione
Duration

Durata.
ErrorRelatedResource

Oggetto dettagli risorsa correlato all'errore.
ErrorResponse

Risposta di errore.
ErrorResponseDetails

Dettagli della risposta di errore.
SqlEndpointRefreshMetadataRequest

Payload della richiesta per l'aggiornamento di un endpoint di analisi SQL.
SyncStatus

Stato dell'operazione di sincronizzazione. È possibile aggiungere altri tipi SyncStatus nel tempo.
TableDefinition

Coppia di nomi di schema e tabella per definire l'ambito di un aggiornamento selettivo.
TableSyncStatus

Oggetto stato sincronizzazione tabella.
TableSyncStatuses

Elenco degli stati di sincronizzazione delle tabelle.
TimeUnit

Unità di tempo per la durata. È possibile aggiungere tipi di durata aggiuntivi nel tempo.

Duration

Oggetto

Durata.

Nome Tipo Descrizione
timeUnit

TimeUnit

Unità di tempo per la durata. È possibile aggiungere tipi di durata aggiuntivi nel tempo.
value

number

Numero di timeUnits nella durata.

ErrorRelatedResource

Oggetto

Oggetto dettagli risorsa correlato all'errore.

Nome Tipo Descrizione
resourceId

string

ID risorsa coinvolto nell'errore.
resourceType

string

Tipo della risorsa coinvolta nell'errore.

ErrorResponse

Oggetto

Risposta di errore.

Nome Tipo Descrizione
errorCode

string

Identificatore specifico che fornisce informazioni su una condizione di errore, consentendo la comunicazione standardizzata tra il servizio e i relativi utenti.
isRetriable

boolean

Se true, la richiesta può essere ritentata. Usare l'intestazione della Retry-After risposta per determinare il ritardo, se disponibile.
message

string

Rappresentazione leggibile dell'errore.
moreDetails

ErrorResponseDetails[]

Elenco di dettagli aggiuntivi sull'errore.
relatedResource

ErrorRelatedResource

Dettagli della risorsa correlati all'errore.
requestId

string (uuid)

ID della richiesta associata all'errore.

ErrorResponseDetails

Oggetto

Dettagli della risposta di errore.

Nome Tipo Descrizione
errorCode

string

Identificatore specifico che fornisce informazioni su una condizione di errore, consentendo la comunicazione standardizzata tra il servizio e i relativi utenti.
message

string

Rappresentazione leggibile dell'errore.
relatedResource

ErrorRelatedResource

Dettagli della risorsa correlati all'errore.

SqlEndpointRefreshMetadataRequest

Oggetto

Payload della richiesta per l'aggiornamento di un endpoint di analisi SQL.

Nome Tipo Descrizione
recreateTables

boolean

Se impostato su true, questa proprietà indica al sistema di eliminare e ricreare tutte le tabelle nell'endpoint di analisi SQL durante il processo di aggiornamento. Usare questa opzione se è necessario ricompilare completamente le tabelle dalle relative definizioni di origine, ad esempio per risolvere le incoerenze o assicurarsi un aggiornamento pulito. Se combinato con tables, la reimpostazione dello stato di sincronizzazione ha come ambito solo le tabelle specificate. Il valore predefinito è false.
tables

TableDefinition[]

Se specificato, definisce l'ambito dell'aggiornamento solo alle tabelle elencate. Se omesso o vuoto, tutte le tabelle vengono aggiornate. Ogni voce specifica uno schema e uno o più nomi di tabella da aggiornare in tale schema. Il numero massimo di tabelle che è possibile sincronizzare in una singola richiesta è 25. La risoluzione delle tabelle dipende dal fatto che l'elemento padre dell'endpoint SQL sia abilitato per lo schema. Per gli elementi abilitati per lo schema, le tabelle vengono risolte usando lo schema fornito dal chiamante. Per gli elementi non abilitati allo schema, tutte le tabelle vengono risolte nello schema predefinito indipendentemente dal valore dello schema fornito dal chiamante; Le tabelle con uno schema non predefinito non possono essere risolte e verranno segnalate con un DeltaTableNotFound errore.
timeout

Duration

Durata della richiesta prima del timeout. Il valore predefinito è 15 minuti.

SyncStatus

Enumerazione

Stato dell'operazione di sincronizzazione. È possibile aggiungere altri tipi SyncStatus nel tempo.

Valore Descrizione
Success

Indica un esito positivo.
Failure

Indica un errore.
NotRun

Indica che l'operazione non è stata eseguita.

TableDefinition

Oggetto

Coppia di nomi di schema e tabella per definire l'ambito di un aggiornamento selettivo.

Nome Tipo Descrizione
schema

string

minLength: 1
maxLength: 128

Nome dello schema per la risoluzione della tabella. Non deve essere uno schema di sistema riservato.
tableNames

string[]

minLength: 1
maxLength: 128

Uno o più nomi di tabella da aggiornare nello schema specificato.

TableSyncStatus

Oggetto

Oggetto stato sincronizzazione tabella.

Nome Tipo Descrizione
endDateTime

string (date-time)

Data e ora in cui la sincronizzazione della tabella è stata completata in formato UTC, utilizzando il formato AAAA-MM-GGTHH:mm:ssZ.
error

ErrorResponseDetails

Dettagli della risposta di errore
lastSuccessfulSyncDateTime

string (date-time)

Data e ora in cui la sincronizzazione della tabella ha avuto esito positivo in formato UTC, utilizzando il formato AAAA-MM-GGTHH:mm:ssZ.
startDateTime

string (date-time)

Data e ora di inizio della sincronizzazione della tabella in formato UTC, utilizzando il formato AAAA-MM-GGTHH:mm:ssZ.
status

SyncStatus

Indica se la tabella è sincronizzata senza errori.
tableName

string

Nome della tabella sincronizzata. Per gli elementi abilitati per lo schema, il nome della tabella è preceduto dal nome dello schema, ad esempio "schema.tableName".

TableSyncStatuses

Oggetto

Elenco degli stati di sincronizzazione delle tabelle.

Nome Tipo Descrizione
value

TableSyncStatus[]

Elenco degli stati di sincronizzazione delle tabelle.

TimeUnit

Enumerazione

Unità di tempo per la durata. È possibile aggiungere tipi di durata aggiuntivi nel tempo.

Valore Descrizione
Seconds

Durata in secondi.
Minutes

Durata in minuti.
Hours

Durata in ore.
Days

Durata in giorni.