Items - Refresh Sql Endpoint Metadata

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

Atualiza tabelas em um ponto de extremidade de análise do SQL.
Essa API dá suporte a LRO (operações de execução longa).

Quando tables for fornecido no corpo da solicitação, somente as tabelas especificadas serão atualizadas. Quando omitidas ou vazias, todas as tabelas são atualizadas.

Permissions

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

Escopos delegados necessários

Item.ReadWrite.All

Identidades com suporte do Microsoft Entra

Esta API dá suporte às identidades do Microsoft listadas nesta seção.

Identity Support
User Yes
Entidade de serviço e identidades gerenciadas Yes

Interface

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

Parâmetros de URI

Nome Em Obrigatório Tipo Description
sqlEndpointId
 path True

string (uuid)

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

string (uuid)

O identificador do espaço de trabalho.

Corpo da solicitação

Nome Tipo Description
recreateTables

boolean

Quando definida como true, essa propriedade instrui o sistema a remover e recriar todas as tabelas no ponto de extremidade de análise do SQL durante o processo de atualização. Use essa opção se precisar recompilar totalmente as tabelas de suas definições de origem, por exemplo, para resolver inconsistências ou garantir uma atualização limpa. Quando combinado com tables, a redefinição de estado de sincronização é definida apenas para as tabelas especificadas. O valor padrão é false.
tables

TableDefinition[]

Quando fornecido, define o escopo da 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 tabela para atualizar sob esse esquema. O número máximo de tabelas que podem ser sincronizadas em uma única solicitação é 25. A resolução da tabela depende se o item pai do ponto de extremidade SQL está habilitado para esquema. Para itens habilitados para esquema, as tabelas são resolvidas usando o esquema fornecido pelo chamador. Para itens não habilitados para esquema, todas as tabelas são resolvidas no esquema padrão, independentemente do valor do esquema fornecido pelo chamador; tabelas em um esquema não padrão não podem ser resolvidas e serão relatadas com um DeltaTableNotFound erro.
timeout

Duration

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

Respostas

Nome Tipo Description
200 OK

TableSyncStatuses

Solicitação concluída com êxito.
202 Accepted

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

Cabeçalhos

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

ErrorResponse

O limite de taxa de serviço foi excedido. O servidor retorna um Retry-After cabeçalho indicando, em segundos, quanto tempo o cliente deve aguardar antes de enviar solicitações 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

Solicitação de exemplo

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

Resposta de exemplo

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

Solicitação de exemplo

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 de exemplo

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

Solicitação de exemplo

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 de exemplo

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

Solicitação de exemplo

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 de exemplo

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

Nome Description
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 conteúdo da solicitação para atualizar um ponto de extremidade de análise de SQL.
SyncStatus

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

Um par de nomes de esquema e tabela para escopo 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 durante a duração. Tipos de duração adicionais podem ser adicionados ao longo do tempo.

Duration

Objeto

Uma duração.

Nome Tipo Description
timeUnit

TimeUnit

A unidade de tempo durante 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

Objeto

O objeto de detalhes do recurso relacionado ao erro.

Nome Tipo Description
resourceId

string

A ID do recurso envolvida no erro.
resourceType

string

O tipo do recurso envolvido no erro.

ErrorResponse

Objeto

A resposta de erro.

Nome Tipo Description
errorCode

string

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

boolean

Quando true, a solicitação pode ser repetida. Use o Retry-After cabeçalho de resposta para determinar o atraso, se disponível.
message

string

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

ErrorResponseDetails[]

Lista de detalhes de erro adicionais.
relatedResource

ErrorRelatedResource

Os detalhes do recurso relacionado ao erro.
requestId

string (uuid)

ID da solicitação associada ao erro.

ErrorResponseDetails

Objeto

Os detalhes da resposta de erro.

Nome Tipo Description
errorCode

string

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

string

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

ErrorRelatedResource

Os detalhes do recurso relacionado ao erro.

SqlEndpointRefreshMetadataRequest

Objeto

O conteúdo da solicitação para atualizar um ponto de extremidade de análise de SQL.

Nome Tipo Description
recreateTables

boolean

Quando definida como true, essa propriedade instrui o sistema a remover e recriar todas as tabelas no ponto de extremidade de análise do SQL durante o processo de atualização. Use essa opção se precisar recompilar totalmente as tabelas de suas definições de origem, por exemplo, para resolver inconsistências ou garantir uma atualização limpa. Quando combinado com tables, a redefinição de estado de sincronização é definida apenas para as tabelas especificadas. O valor padrão é false.
tables

TableDefinition[]

Quando fornecido, define o escopo da 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 tabela para atualizar sob esse esquema. O número máximo de tabelas que podem ser sincronizadas em uma única solicitação é 25. A resolução da tabela depende se o item pai do ponto de extremidade SQL está habilitado para esquema. Para itens habilitados para esquema, as tabelas são resolvidas usando o esquema fornecido pelo chamador. Para itens não habilitados para esquema, todas as tabelas são resolvidas no esquema padrão, independentemente do valor do esquema fornecido pelo chamador; tabelas em um esquema não padrão não podem ser resolvidas e serão relatadas 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 do SyncStatus podem ser adicionados ao longo do tempo.

Valor Description
Success

Indica um êxito.
Failure

Indica uma falha.
NotRun

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

TableDefinition

Objeto

Um par de nomes de esquema e tabela para escopo de uma atualização seletiva.

Nome Tipo Description
schema

string

minLength: 1
maxLength: 128

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

string[]

minLength: 1
maxLength: 128

Um ou mais nomes de tabela a serem atualizados no esquema especificado.

TableSyncStatus

Objeto

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

Nome Tipo Description
endDateTime

string (date-time)

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

ErrorResponseDetails

Os detalhes da resposta de erro
lastSuccessfulSyncDateTime

string (date-time)

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

string (date-time)

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

SyncStatus

Se a tabela foi sincronizada sem erros.
tableName

string

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

TableSyncStatuses

Objeto

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

Nome Tipo Description
value

TableSyncStatus[]

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

TimeUnit

Enumeração

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

Valor Description
Seconds

Duração em segundos.
Minutes

Duração em minutos.
Hours

Duração em horas.
Days

Duração em dias.