Items - Refresh Sql Endpoint Metadata

Servicio:
SQLEndpoint
Versión de la API:
v1

Actualiza las tablas dentro de un punto de conexión de SQL Analytics.
Esta API admite operaciones de larga duración (LRO).

Cuando tables se proporciona en el cuerpo de la solicitud, solo se actualizan las tablas especificadas. Cuando se omite o está vacío, se actualizan todas las tablas.

Permissions

El autor de la llamada debe tener rol de colaborador o superior.

Ámbitos delegados necesarios

Item.ReadWrite.All

Identidades admitidas de Microsoft Entra

Esta API admite las identidades de Microsoft enumeradas en esta sección.

Identity Support
User Yes
Entidad de servicio e Identidades administradas Yes

Interface

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

Parámetros de identificador URI

Nombre En Requerido Tipo Description
sqlEndpointId
 path True

string (uuid)

Identificador del punto de conexión de SQL Analytics.
workspaceId
 path True

string (uuid)

El identificador del área de trabajo.

Cuerpo de la solicitud

Nombre Tipo Description
recreateTables

boolean

Cuando se establece en true, esta propiedad indica al sistema que quite y vuelva a crear todas las tablas del punto de conexión de SQL Analytics durante el proceso de actualización. Use esta opción si necesita recompilar completamente las tablas a partir de sus definiciones de origen, por ejemplo, para resolver incoherencias o garantizar una actualización limpia. Cuando se combina con tables, el restablecimiento del estado de sincronización solo se limita a las tablas especificadas. El valor predeterminado es false.
tables

TableDefinition[]

Cuando se proporciona, limita la actualización solo a las tablas enumeradas. Cuando se omite o está vacío, se actualizan todas las tablas. Cada entrada especifica un esquema y uno o varios nombres de tabla que se actualizarán en ese esquema. El número máximo de tablas que se pueden sincronizar en una sola solicitud es 25. La resolución de tablas depende de si el elemento primario del punto de conexión de SQL está habilitado para el esquema. En el caso de los elementos habilitados para esquemas, las tablas se resuelven mediante el esquema proporcionado por el autor de la llamada. Para los elementos no habilitados para esquemas, todas las tablas se resuelven en el esquema predeterminado, independientemente del valor de esquema proporcionado por el autor de la llamada; Las tablas de un esquema no predeterminado no se pueden resolver y se notificarán con un DeltaTableNotFound error.
timeout

Duration

Duración de la solicitud antes de que se agote el tiempo de espera. El valor predeterminado es de 15 minutos.

Respuestas

Nombre Tipo Description
200 OK

TableSyncStatuses

Solicitud completada correctamente.
202 Accepted

Solicitud aceptada, actualización de la tabla de SQL Analytics en curso.

Encabezados

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

ErrorResponse

Se superó el límite de frecuencia de servicio. El servidor devuelve un Retry-After encabezado que indica, en segundos, cuánto tiempo debe esperar el cliente antes de enviar solicitudes adicionales.

Encabezados

Retry-After: integer
Other Status Codes

ErrorResponse

Códigos de error comunes:

  • ItemNotFound: no se encontró el elemento solicitado.

Ejemplos

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

Solicitud de ejemplo

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

Respuesta de muestra

status code:
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

Solicitud de ejemplo

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

Respuesta de muestra

status code:
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

Solicitud de ejemplo

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

Respuesta de muestra

status code:
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

Solicitud de ejemplo

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

Respuesta de muestra

status code:
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"
    }
  ]
}

Definiciones

Nombre Description
Duration

Duración.
ErrorRelatedResource

Objeto de detalles del recurso relacionado con el error.
ErrorResponse

Respuesta de error.
ErrorResponseDetails

Detalles de la respuesta de error.
SqlEndpointRefreshMetadataRequest

Carga de solicitud para actualizar un punto de conexión de SQL Analytics.
SyncStatus

Estado de la operación de sincronización. Se pueden agregar tipos SyncStatus adicionales a lo largo del tiempo.
TableDefinition

Par de nombres de esquema y tabla para determinar el ámbito de una actualización selectiva.
TableSyncStatus

Objeto de estado de sincronización de tabla.
TableSyncStatuses

Lista de estados de sincronización de tablas.
TimeUnit

Unidad de tiempo durante la duración. Se pueden agregar tipos de duración adicionales a lo largo del tiempo.

Duration

Objeto

Duración.

Nombre Tipo Description
timeUnit

TimeUnit

Unidad de tiempo durante la duración. Se pueden agregar tipos de duración adicionales a lo largo del tiempo.
value

number

Número de timeUnits en la duración.

ErrorRelatedResource

Objeto

Objeto de detalles del recurso relacionado con el error.

Nombre Tipo Description
resourceId

string

Identificador de recurso implicado en el error.
resourceType

string

Tipo del recurso implicado en el error.

ErrorResponse

Objeto

Respuesta de error.

Nombre Tipo Description
errorCode

string

Identificador específico que proporciona información sobre una condición de error, lo que permite una comunicación estandarizada entre nuestro servicio y sus usuarios.
isRetriable

boolean

Cuando es true, se puede reintentar la solicitud. Use el Retry-After encabezado de respuesta para determinar el retraso, si está disponible.
message

string

Representación legible del error.
moreDetails

ErrorResponseDetails[]

Lista de detalles de error adicionales.
relatedResource

ErrorRelatedResource

Detalles del recurso relacionado con el error.
requestId

string (uuid)

Identificador de la solicitud asociada al error.

ErrorResponseDetails

Objeto

Detalles de la respuesta de error.

Nombre Tipo Description
errorCode

string

Identificador específico que proporciona información sobre una condición de error, lo que permite una comunicación estandarizada entre nuestro servicio y sus usuarios.
message

string

Representación legible del error.
relatedResource

ErrorRelatedResource

Detalles del recurso relacionado con el error.

SqlEndpointRefreshMetadataRequest

Objeto

Carga de solicitud para actualizar un punto de conexión de SQL Analytics.

Nombre Tipo Description
recreateTables

boolean

Cuando se establece en true, esta propiedad indica al sistema que quite y vuelva a crear todas las tablas del punto de conexión de SQL Analytics durante el proceso de actualización. Use esta opción si necesita recompilar completamente las tablas a partir de sus definiciones de origen, por ejemplo, para resolver incoherencias o garantizar una actualización limpia. Cuando se combina con tables, el restablecimiento del estado de sincronización solo se limita a las tablas especificadas. El valor predeterminado es false.
tables

TableDefinition[]

Cuando se proporciona, limita la actualización solo a las tablas enumeradas. Cuando se omite o está vacío, se actualizan todas las tablas. Cada entrada especifica un esquema y uno o varios nombres de tabla que se actualizarán en ese esquema. El número máximo de tablas que se pueden sincronizar en una sola solicitud es 25. La resolución de tablas depende de si el elemento primario del punto de conexión de SQL está habilitado para el esquema. En el caso de los elementos habilitados para esquemas, las tablas se resuelven mediante el esquema proporcionado por el autor de la llamada. Para los elementos no habilitados para esquemas, todas las tablas se resuelven en el esquema predeterminado, independientemente del valor de esquema proporcionado por el autor de la llamada; Las tablas de un esquema no predeterminado no se pueden resolver y se notificarán con un DeltaTableNotFound error.
timeout

Duration

Duración de la solicitud antes de que se agote el tiempo de espera. El valor predeterminado es de 15 minutos.

SyncStatus

Enumeración

Estado de la operación de sincronización. Se pueden agregar tipos SyncStatus adicionales a lo largo del tiempo.

Valor Description
Success

Indica que se ha realizado correctamente.
Failure

Indica un error.
NotRun

Indica que la operación no se ejecutó.

TableDefinition

Objeto

Par de nombres de esquema y tabla para determinar el ámbito de una actualización selectiva.

Nombre Tipo Description
schema

string

minLength: 1
maxLength: 128

Nombre del esquema para la resolución de tablas. No debe ser un esquema del sistema reservado.
tableNames

string[]

minLength: 1
maxLength: 128

Uno o más nombres de tabla para actualizar en el esquema especificado.

TableSyncStatus

Objeto

Objeto de estado de sincronización de tabla.

Nombre Tipo Description
endDateTime

string (date-time)

Fecha y hora en que se completó la sincronización de tablas en UTC, utilizando el formato AAAA-MM-DDTHH:mm:ssZ.
error

ErrorResponseDetails

Detalles de la respuesta de error
lastSuccessfulSyncDateTime

string (date-time)

Fecha y hora en que la sincronización de tablas se realizó correctamente en UTC, usando el formato AAAA-MM-DDTHH:mm:ssZ.
startDateTime

string (date-time)

Fecha y hora en que se inició la sincronización de tablas en UTC, utilizando el formato AAAA-MM-DDTHH:mm:ssZ.
status

SyncStatus

Indica si la tabla se sincroniza sin errores.
tableName

string

Nombre de la tabla que se sincronice. En el caso de los elementos habilitados para esquemas, el nombre de la tabla tiene como prefijo el nombre del esquema (por ejemplo, "schema.tableName").

TableSyncStatuses

Objeto

Lista de estados de sincronización de tablas.

Nombre Tipo Description
value

TableSyncStatus[]

Lista de estados de sincronización de tablas.

TimeUnit

Enumeración

Unidad de tiempo durante la duración. Se pueden agregar tipos de duración adicionales a lo largo del tiempo.

Valor Description
Seconds

Duración en segundos.
Minutes

Duración en minutos.
Hours

Duración en horas.
Days

Duración en días.