Items - Refresh Sql Endpoint Metadata

Serviço:
SQLEndpoint
Versão da API:
v1

Atualiza tabelas dentro de um endpoint de análise SQL.
Esta API suporta operações de longa duração (LRO).

Quando tables é fornecido no corpo do pedido, apenas as tabelas especificadas são atualizadas. Quando omitidas ou vazias, todas as tabelas são atualizadas.

Permissões

O chamador deve ter função de colaborador ou superior do espaço de trabalho.

Escopos delegados necessários

Item.ReadWrite.All

Identidades suportadas pelo Entra da Microsoft

Esta API suporta as identidades do Microsoft listadas nesta secção.

Identidade Apoio
Utilizador Sim
Entidade de serviço e identidades geridas Sim

Interfaz

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

Parâmetros do URI

Name Em Obrigatório Tipo Descrição
sqlEndpointId
 path True

string (uuid)

O ID do ponto de extremidade da análise SQL.
workspaceId
 path True

string (uuid)

O ID do espaço de trabalho.

Corpo do Pedido

Name Tipo Descrição
recreateTables

boolean

Quando definida como verdadeira, esta propriedade instrui o sistema a eliminar e recriar todas as tabelas no endpoint de análise SQL durante o processo de atualização. Use esta opção se precisar de reconstruir totalmente as tabelas a partir das suas definições de origem, por exemplo, para resolver inconsistências ou garantir uma atualização limpa. Quando combinado com tables, o reset do estado de sincronização é atribuído apenas às tabelas especificadas. O valor predefinido é false.
tables

TableDefinition[]

Quando fornecida, escopa a atualização apenas para as tabelas listadas. Quando omitidas ou vazias, todas as tabelas são atualizadas. Cada entrada especifica um esquema e um ou mais nomes de tabelas para atualizar sob esse esquema. O número máximo de tabelas que podem ser sincronizadas num único pedido é 25. A resolução da tabela depende de o item-mãe do endpoint SQL estar habilitado para o esquema. Para itens habilitados por esquema, as tabelas são resolvidas usando o esquema fornecido pelo chamador. Para itens não habilitados por esquema, todas as tabelas resolvem-se sob o esquema padrão independentemente do valor do esquema fornecido pelo chamador; Tabelas sob um esquema não padrão não podem ser resolvidas e serão reportadas com um DeltaTableNotFound erro.
timeout

Duration

A duração da solicitação antes do tempo limite. O valor padrão é 15 minutos.

Respostas

Name Tipo Descrição
200 OK

TableSyncStatuses

Pedido concluído com sucesso.
202 Accepted

Solicitação aceita, atualização da tabela de análise SQL em andamento.

Cabeçalhos

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

ErrorResponse

O limite de tarifa de serviço foi ultrapassado. O servidor devolve um Retry-After cabeçalho que indica, em segundos, quanto tempo o cliente deve esperar antes de enviar pedidos adicionais.

Cabeçalhos

Retry-After: integer
Other Status Codes

ErrorResponse

Códigos de erro comuns:

  • ItemNotFound - O item solicitado não foi encontrado.

Exemplos

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

Pedido de amostra

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

Resposta da amostra

Código de estado:
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

Pedido de amostra

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

Resposta da amostra

Código de estado:
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

Pedido de amostra

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

Resposta da amostra

Código de estado:
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

Pedido de amostra

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

Resposta da amostra

Código de estado:
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"
    }
  ]
}

Definições

Name Descrição
Duration

Uma duração.
ErrorRelatedResource

O objeto de detalhes do recurso relacionado ao erro.
ErrorResponse

A resposta de erro.
ErrorResponseDetails

Os detalhes da resposta de erro.
SqlEndpointRefreshMetadataRequest

O payload de pedido para atualizar um endpoint de análise SQL.
SyncStatus

O status da operação de sincronização. Tipos adicionais de SyncStatus podem ser adicionados ao longo do tempo.
TableDefinition

Um par de nomes de esquemas e tabelas para definir o âmbito de uma atualização seletiva.
TableSyncStatus

Um objeto de status de sincronização de tabela.
TableSyncStatuses

Uma lista de status de sincronização de tabela.
TimeUnit

A unidade de tempo para a duração. Tipos de duração adicionais podem ser adicionados ao longo do tempo.

Duration

Object

Uma duração.

Name Tipo Descrição
timeUnit

TimeUnit

A unidade de tempo para a duração. Tipos de duração adicionais podem ser adicionados ao longo do tempo.
value

number

O número de timeUnits na duração.

ErrorRelatedResource

Object

O objeto de detalhes do recurso relacionado ao erro.

Name Tipo Descrição
resourceId

string

A ID do recurso envolvida no erro.
resourceType

string

O tipo de recurso envolvido no erro.

ErrorResponse

Object

A resposta de erro.

Name Tipo Descrição
errorCode

string

Um identificador específico que fornece informações sobre uma condição de erro, permitindo uma comunicação padronizada entre nosso serviço e seus usuários.
isRetriable

boolean

Quando confirmado, o pedido pode ser retentado. Use o Retry-After cabeçalho de resposta para determinar o atraso, se disponível.
message

string

Uma representação legível por humanos do erro.
moreDetails

ErrorResponseDetails[]

Lista de detalhes de erro adicionais.
relatedResource

ErrorRelatedResource

Os detalhes do recurso relacionados ao erro.
requestId

string (uuid)

ID da solicitação associada ao erro.

ErrorResponseDetails

Object

Os detalhes da resposta de erro.

Name Tipo Descrição
errorCode

string

Um identificador específico que fornece informações sobre uma condição de erro, permitindo uma comunicação padronizada entre nosso serviço e seus usuários.
message

string

Uma representação legível por humanos do erro.
relatedResource

ErrorRelatedResource

Os detalhes do recurso relacionados ao erro.

SqlEndpointRefreshMetadataRequest

Object

O payload de pedido para atualizar um endpoint de análise SQL.

Name Tipo Descrição
recreateTables

boolean

Quando definida como verdadeira, esta propriedade instrui o sistema a eliminar e recriar todas as tabelas no endpoint de análise SQL durante o processo de atualização. Use esta opção se precisar de reconstruir totalmente as tabelas a partir das suas definições de origem, por exemplo, para resolver inconsistências ou garantir uma atualização limpa. Quando combinado com tables, o reset do estado de sincronização é atribuído apenas às tabelas especificadas. O valor predefinido é false.
tables

TableDefinition[]

Quando fornecida, escopa a atualização apenas para as tabelas listadas. Quando omitidas ou vazias, todas as tabelas são atualizadas. Cada entrada especifica um esquema e um ou mais nomes de tabelas para atualizar sob esse esquema. O número máximo de tabelas que podem ser sincronizadas num único pedido é 25. A resolução da tabela depende de o item-mãe do endpoint SQL estar habilitado para o esquema. Para itens habilitados por esquema, as tabelas são resolvidas usando o esquema fornecido pelo chamador. Para itens não habilitados por esquema, todas as tabelas resolvem-se sob o esquema padrão independentemente do valor do esquema fornecido pelo chamador; Tabelas sob um esquema não padrão não podem ser resolvidas e serão reportadas com um DeltaTableNotFound erro.
timeout

Duration

A duração da solicitação antes do tempo limite. O valor padrão é 15 minutos.

SyncStatus

Enumeração

O status da operação de sincronização. Tipos adicionais de SyncStatus podem ser adicionados ao longo do tempo.

Valor Descrição
Success

Indica um sucesso.
Failure

Indica uma falha.
NotRun

Indica que a operação não foi executada.

TableDefinition

Object

Um par de nomes de esquemas e tabelas para definir o âmbito de uma atualização seletiva.

Name Tipo Descrição
schema

string

minLength: 1
maxLength: 128

O nome do esquema para resolução de tabelas. Não deve ser um esquema de sistema reservado.
tableNames

string[]

minLength: 1
maxLength: 128

Um ou mais nomes de tabelas para atualizar sob o esquema especificado.

TableSyncStatus

Object

Um objeto de status de sincronização de tabela.

Name Tipo Descrição
endDateTime

string (date-time)

A data e a hora em que a sincronização da tabela foi concluída em UTC, usando o formato AAAA-MM-DDTHH:mm:ssZ.
error

ErrorResponseDetails

Os detalhes da resposta ao erro
lastSuccessfulSyncDateTime

string (date-time)

A data e a hora em que a sincronização da tabela foi bem-sucedida no UTC, usando o formato AAAA-MM-DDTHH:mm:ssZ.
startDateTime

string (date-time)

A data e a hora em que a sincronização da tabela começou em UTC, usando o formato AAAA-MM-DDTHH:mm:ssZ.
status

SyncStatus

Se a tabela sincronizou sem erros.
tableName

string

O nome da tabela sincronizada. Para itens habilitados para o esquema, o nome da tabela é prefixado com o nome do esquema (por exemplo, "schema.TableName").

TableSyncStatuses

Object

Uma lista de status de sincronização de tabela.

Name Tipo Descrição
value

TableSyncStatus[]

Uma lista de status de sincronização de tabela.

TimeUnit

Enumeração

A unidade de tempo para a duração. Tipos de duração adicionais podem ser adicionados ao longo do tempo.

Valor Descrição
Seconds

Duração em segundos.
Minutes

Duração em minutos.
Hours

Duração em horas.
Days

Duração em dias.