Gerenciar e atualizar exibições de lago materializadas no Fabric com APIs

As APIs REST do Microsoft Fabric permitem que você gerencie e atualize visualizações de lagos materializados (MLVs) programaticamente. Você pode automatizar operações de atualização de linhagem e integrá-las com outras ferramentas e sistemas.

Pré-requisitos

Antes de usar as APIs REST de exibição de lago materializadas, conclua estes pré-requisitos:

Registre uma aplicação com o Microsoft Entra ID com a identidade apropriada. Adquira um token de acesso com os escopos apropriados e o passe no Authorization cabeçalho de cada solicitação.
Substitua os marcadores incluindo {WORKSPACE_ID} e {LAKEHOUSE_ID} por apropriados WorkspaceId e LakehouseId. Para encontrar esses IDs, abra a casa do lago no portal Fabric — a URL contém ambos: https://app.fabric.microsoft.com/groups/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}. Alternativamente, você pode listar os espaços de trabalho e lakehouses usando APIs Fabric REST para acessá-los programaticamente.

As seguintes ações do agendador de tarefas estão disponíveis para vistas materializadas do lago.

Ação	Description
Criar um cronograma de atualização para MLV	Crie um cronograma para atualização periódica dos MLVs.
Obtenha a Escala do MLV	Obtenha detalhes sobre um cronograma de renovação existente.
Listas de Cronogramas para MLV	Liste todos os cronogramas de renovação.
Cronograma de atualização para MLV	Atualize um cronograma de atualização existente.
Delete Refresh Schedule para MLV	Exclua um cronograma de atualização.
Atualização Sob Demanda para MLVs	Faça uma atualização imediata dos MLVs.
Listar Instâncias de Emprego para MLV	Liste todas as instâncias de atualização de trabalhos.
Obtenha detalhes da instância de trabalho para MLV	Obtenha detalhes de um emprego específico de atualização, como status.
Cancelar Instância de Trabalho para MLV	Cancele um trabalho de atualização em andamento.

Para mais informações, veja agendador de tarefas, onde {item} fica Lakehouse e {jobType} onde é RefreshMaterializedLakeViews.

Uma definição de execução MLV é uma configuração salva que especifica quais vistas de lago materializadas devem ser atualizadas, quais casas de lago a montante incluir e qual modo de atualização e ambiente Spark usar. Ele define um subconjunto da linhagem que pode ser atualizado independentemente.

As seguintes ações estão disponíveis para definições de execução de MLV.

Ação	Description
Criar Definição de Execução MLV	Crie uma nova definição de execução MLV.
Lista de Definições de Execução MLV	Liste todas as definições de execução de MLV.
Obtenha a Definição de Execução MLV	Obtenha detalhes de uma definição existente de execução de MLV.
Atualizar a Definição de Execução MLV	Atualize uma definição de execução MLV existente.
Excluir Definição de Execução MLV	Exclua uma definição de execução MLV.

Para mais informações, veja vistas materializadas do lago.

Os diagramas a seguir mostram como atualizar vistas de lagos materializadas, com ou sem definição de execução MLV.

Caso de uso 1: Atualizar todos os MLVs em uma casa de lago (padrão)

Caso de uso 2: Atualizar MLVs específicos ou um subconjunto da linhagem

Observação

Esses cenários abrangem exemplos de uso específicos para exibições de lago materializadas. Exemplos de APIs comuns de item do Fabric não estão incluídos.

Exemplos de refrescar vistas de lagos materializadas usando APIs

Cada exemplo mostra o método HTTP, a URL do ponto de extremidade e os conteúdos de solicitação/resposta de exemplo.

Criar um cronograma de atualização para MLV

Crie um cronograma para renovação periódica da linhagem. Para atualizar apenas um subconjunto da linhagem, forneça o 'mlvExecutionDefinitionId' em executionData. Para mais informações, veja Criar Atualizar o Cronograma de Visualizações Materializadas do Lago e Obter a Definição de Execução MLV.

Exemplo de requisição sem definição de Execução MLV:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules

{
  "enabled": true,
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  }
}

Solicitação de exemplo com definição de execução MLV:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules

{
  "enabled": true,
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  },
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  }
}

Resposta de exemplo:

Código de status: 201 Criado

Location: https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules/<scheduleId>

{
  "id": "<scheduleId>",
  "enabled": true,
  "createdDateTime": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  },
  "owner": {
    "id": "<ownerId>",
    "type": "User"
  }
}

Obtenha a Escala do MLV

Obtenha detalhes sobre um cronograma de renovação existente. Para mais informações, veja os cronogramas de itens com {item} as Lakehouse e {jobType} como RefreshMaterializedLakeViews.

Solicitação de exemplo:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules/{scheduleId}

Resposta de exemplo:

Código de status: 200 OK

{
  "id": "<scheduleId>",
  "enabled": true,
  "createdDateTime": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  },
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  },
  "owner": {
    "id": "<ownerId>",
    "type": "User"
  }
}

Listas de Cronogramas para MLV

Liste todos os cronogramas de renovação. Para mais informações, veja Listar Agendas de Itens com {item} como Lakehouse e {jobType} como RefreshMaterializedLakeViews.

Solicitação de exemplo:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules

Resposta de exemplo:

Código de status: 200 OK

{
  "value": [
    {
      "id": "<scheduleId_1>",
      "enabled": true,
      "createdDateTime": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "configuration": {
        "startDateTime": "YYYY-MM-DDTHH:mm:ss",
        "endDateTime": "YYYY-MM-DDTHH:mm:ss",
        "localTimeZoneId": "Central Standard Time",
        "type": "Weekly",
        "weekdays": [
          "Monday",
          "Tuesday"
        ],
        "times": [
          "HH:mm",
          "HH:mm"
        ]
      },
      "owner": {
        "id": "<ownerId>",
        "type": "User"
      }
    },
    {
      "id": "<scheduleId_2>",
      "enabled": true,
      "createdDateTime": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "configuration": {
        "startDateTime": "YYYY-MM-DDTHH:mm:ss",
        "endDateTime": "YYYY-MM-DDTHH:mm:ss",
        "localTimeZoneId": "Central Standard Time",
        "type": "Daily",
        "times": [
          "HH:mm",
          "HH:mm"
        ]
      },
      "owner": {
        "id": "<ownerId>",
        "type": "User"
      }
    }
  ]
}

Cronograma de atualização para MLV

Atualize um cronograma de atualização existente. Para mais informações, consulte o Update Refresh Materialized Lake View Schedule.

Solicitação de exemplo:

PATCH https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules/{scheduleId}

{
  "enabled": true,
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  },
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  }
}

Resposta de exemplo:

Código de status: 200 OK

{
  "id": "<scheduleId>",
  "enabled": true,
  "createdDateTime": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  },
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  },
  "owner": {
    "id": "<ownerId>",
    "type": "User"
  }
}

Delete Refresh Schedule para MLV

Exclua um cronograma de atualização. Para mais informações, veja Atualizar Atualizar o Cronograma de Vistas Materializadas do Lago.

Solicitação de exemplo:

DELETE https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules/{scheduleId}

Resposta de exemplo:

Código de status: 200 OK

Atualização Sob Demanda para MLVs

Faça uma atualização imediata da linhagem. Para atualizar apenas um subconjunto da linhagem, forneça o 'mlvExecutionDefinitionId' em executionData. Para mais informações, veja Run On Demand Refresh Materialized Lake Views e Obtenha a Definição de Execução MLV.

Exemplo de requisição sem definição de Execução MLV:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/instances

Solicitação de exemplo com definição de execução MLV:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/instances

{
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  }
}

Resposta de exemplo:

Código de status: 202 Aceito

Location: https://api.fabric.microsoft.com/v1/workspaces/<WORKSPACE_ID>/lakehouses/<LAKEHOUSE_ID>/jobs/instances/<jobInstanceId>
Retry-After: 60

Com o Location cabeçalho, você pode usar o Get Item Job Instance para verificar o status do job ou Cancelar Item Job Instance para cancelar a execução.

Listar Instâncias de Emprego para MLV

Liste todas as instâncias de atualização de trabalhos. Para mais informações, veja Listar Item Job Instances com {item} como Lakehouse e {jobType}RefreshMaterializedLakeViews. O status do cargo reflete o status no hub Monitor.

Solicitação de exemplo:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/instances

Resposta de exemplo:

Código de status: 200 OK

{
  "value": [
    {
      "id": "<jobInstanceId_1>",
      "itemId": "<LAKEHOUSE_ID>",
      "jobType": "RefreshMaterializedLakeViews",
      "invokeType": "Manual",
      "status": "<status>",
      "rootActivityId": "<rootActivityId_1>",
      "startTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "endTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "failureReason": null
    },
    {
      "id": "<jobInstanceId_2>",
      "itemId": "<LAKEHOUSE_ID>",
      "jobType": "RefreshMaterializedLakeViews",
      "invokeType": "Scheduled",
      "status": "<status>",
      "rootActivityId": "rootActivityId_2",
      "startTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "endTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "failureReason": null
    }
  ]
}

Obtenha detalhes da instância de trabalho para MLV

Obtenha status e detalhes de uma instância específica de atualização de vaga. Para mais informações, veja Obter Item Job Instance com {item} as Lakehouse. O status do cargo reflete o status no hub Monitor.

Solicitação de exemplo:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/instances/{jobInstanceId}

Resposta de exemplo:

Código de status: 200 OK

{
  "id": "<id>",
  "itemId": "<itemId>",
  "jobType": "RefreshMaterializedLakeViews",
  "invokeType": "<invokeType>",
  "status": "<status>",
  "rootActivityId": "<rootActivityId>",
  "startTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "endTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "failureReason": null
}

Cancelar Instância de Trabalho para MLV

Cancele um trabalho de atualização em andamento. Para mais informações, veja Cancelar Item Job Instance com {item} como Lakehouse.

Solicitação de exemplo:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/instances/{jobInstanceId}/cancel

Resposta de exemplo:

Código de status: 202 Aceito

Location: https://api.fabric.microsoft.com/v1/workspaces/<WORKSPACE_ID>/lakehouses/<LAKEHOUSE_ID>/jobs/instances/<jobInstanceId>
Retry-After: 60

Exemplos de uso de APIs de definição de execução MLV

Cada exemplo mostra o método HTTP, a URL do ponto de extremidade e os conteúdos de solicitação/resposta de exemplo.

Criar Definição de Execução MLV

Crie uma nova definição de execução de MLV que especifique quais MLVs e casas de lago a montante incluir, junto com o modo de atualização e o ambiente Spark. Para mais informações, veja Definição de Execução de Criar MLV.

Solicitação de exemplo:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions

{
  "displayName": "Gold Chain – Sales",
  "description": "Nightly refresh for the Sales gold-layer views",
  "settings": {
    "environment": {
      "referenceType": "ById",
      "itemId": "<ENVIRONMENT_ID>",
      "workspaceId": "<ENVIRONMENT_WORKSPACE_ID>"
    },
    "refreshMode": "Optimal"
  },
  "currentLakehouseExecutionContext": {
    "mode": "Selected",
    "selectedMlvs": [
      "dbo.gold_sales_summary",
      "dbo.gold_sales_daily"
    ]
  },
  "extendedLineageExecutionContext": {
    "mode": "All"
  }
}

Resposta de exemplo:

Código de status: 201 Criado

Location: https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions/<mlvExecutionDefinitionId>

{
  "id": "<mlvExecutionDefinitionId>",
  "displayName": "Gold Chain – Sales",
  "description": "Nightly refresh for the Sales gold-layer views",
  "settings": {
    "environment": {
      "referenceType": "ById",
      "itemId": "<ENVIRONMENT_ID>",
      "workspaceId": "<ENVIRONMENT_WORKSPACE_ID>"
    },
    "refreshMode": "Optimal"
  },
  "currentLakehouseExecutionContext": {
    "mode": "Selected",
    "selectedMlvs": [
      "dbo.gold_sales_summary",
      "dbo.gold_sales_daily"
    ]
  },
  "extendedLineageExecutionContext": {
    "mode": "All"
  }
}

Lista de Definições de Execução MLV

Liste todas as definições de execução de MLV. Para mais informações, veja Listar Definições de Execução de MLV.

Solicitação de exemplo:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions

Resposta de exemplo:

Código de status: 200 OK

{
  "value": [
    {
      "id": "<mlvExecutionDefinitionId_1>",
      "displayName": "Gold Chain – Sales",
      "description": "Nightly refresh for the Sales gold-layer views",
      "settings": {
        "environment": {
          "referenceType": "ById",
          "itemId": "<ENVIRONMENT_ID>",
          "workspaceId": "<ENVIRONMENT_WORKSPACE_ID>"
        },
        "refreshMode": "Optimal"
      },
      "currentLakehouseExecutionContext": {
        "mode": "Selected",
        "selectedMlvs": [
          "dbo.gold_sales_summary",
          "dbo.gold_sales_daily"
        ]
      },
      "extendedLineageExecutionContext": {
        "mode": "All"
      }
    },
    {
      "id": "<mlvExecutionDefinitionId_2>",
      "displayName": "Silver Chain – Customers",
      "currentLakehouseExecutionContext": {
        "mode": "All"
      }
    }
  ]
}

Obtenha a Definição de Execução MLV

Obtenha detalhes de uma definição de execução MLV existente, incluindo os MLVs para atualizar, casas de lago a montante, modo de atualização e ambiente Spark. Para mais informações, veja Definição de Execução do MLV.

Solicitação de exemplo:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions/{mlvExecutionDefinitionId}

Resposta de exemplo:

Código de status: 200 OK

{
  "id": "<mlvExecutionDefinitionId>",
  "displayName": "Gold Chain – Sales",
  "description": "Nightly refresh for the Sales gold-layer views",
  "settings": {
    "environment": {
      "referenceType": "ById",
      "itemId": "<ENVIRONMENT_ID>",
      "workspaceId": "<ENVIRONMENT_WORKSPACE_ID>"
    },
    "refreshMode": "Optimal"
  },
  "currentLakehouseExecutionContext": {
    "mode": "Selected",
    "selectedMlvs": [
      "dbo.gold_sales_summary",
      "dbo.gold_sales_daily"
    ]
  },
  "extendedLineageExecutionContext": {
    "mode": "All"
  }
}

Atualizar a Definição de Execução MLV

Atualize uma definição de execução MLV existente. Somente os campos fornecidos no corpo da solicitação são atualizados; os campos omitidos mantêm seus valores existentes. Para mais informações, veja Atualizar Definição de Execução do MLV.

Solicitação de exemplo:

PATCH https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions/{mlvExecutionDefinitionId}

{
  "displayName": "Updated Gold Chain – Sales",
  "settings": {
    "refreshMode": "Full"
  },
  "currentLakehouseExecutionContext": {
    "mode": "All"
  },
  "extendedLineageExecutionContext": {
    "mode": "Selected",
    "selectedLakehouses": [
      {
        "referenceType": "ById",
        "itemId": "<UPSTREAM_LAKEHOUSE_ID>",
        "workspaceId": "<UPSTREAM_WORKSPACE_ID>"
      }
    ]
  }
}

Resposta de exemplo:

Código de status: 200 OK

{
  "id": "<mlvExecutionDefinitionId>",
  "displayName": "Updated Gold Chain – Sales",
  "description": "Nightly refresh for the Sales gold-layer views",
  "settings": {
    "environment": {
      "referenceType": "ById",
      "itemId": "<ENVIRONMENT_ID>",
      "workspaceId": "<ENVIRONMENT_WORKSPACE_ID>"
    },
    "refreshMode": "Full"
  },
  "currentLakehouseExecutionContext": {
    "mode": "All"
  },
  "extendedLineageExecutionContext": {
    "mode": "Selected",
    "selectedLakehouses": [
      {
        "referenceType": "ById",
        "itemId": "<UPSTREAM_LAKEHOUSE_ID>",
        "workspaceId": "<UPSTREAM_WORKSPACE_ID>"
      }
    ]
  }
}

Excluir Definição de Execução MLV

Exclua uma definição de execução MLV. Quaisquer cronogramas vinculadas a ela também foram removidas. Para mais informações, veja Delete Definição de Execução MLV.

Solicitação de exemplo:

DELETE https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions/{mlvExecutionDefinitionId}

Resposta de exemplo:

Código de status: 200 OK

Limitações conhecidas

As seguintes limitações se aplicam às APIs REST de exibições de lago materializadas:

Limites das APIs do Agendador de Tarefas:
- O agendador de tarefas impõe limites sobre quantos cronogramas podem ser configurados por casa do lago.
- A API do agendador de trabalhos retorna um número limitado de trabalhos concluídos e ativos, o que pode afetar a visibilidade de execuções históricas ou concorrentes.
- Os limites de limitação para APIs públicas do Fabric se aplicam às APIs de vistas de lago materializadas.
Exibição do status do cargo: O status retornado por instâncias de job item listadas e instância de job item recebe reflete status no hub Monitor. Pode diferir do status de histórico de visualizações materializadas do lago (por exemplo, Pulado aparece como Cancelado no hub do Monitor).
Limites de atualização: Para restrições de atualização, veja permissões e limitações.

Comentários

Esta página foi útil?

Last updated on 2026-07-01

Gerenciar e atualizar exibições de lago materializadas no Fabric com APIs

Pré-requisitos

Exemplos de refrescar vistas de lagos materializadas usando APIs

Criar um cronograma de atualização para MLV

Obtenha a Escala do MLV

Listas de Cronogramas para MLV

Cronograma de atualização para MLV

Delete Refresh Schedule para MLV

Atualização Sob Demanda para MLVs

Listar Instâncias de Emprego para MLV

Obtenha detalhes da instância de trabalho para MLV

Cancelar Instância de Trabalho para MLV

Exemplos de uso de APIs de definição de execução MLV

Criar Definição de Execução MLV

Lista de Definições de Execução MLV

Obtenha a Definição de Execução MLV

Atualizar a Definição de Execução MLV

Excluir Definição de Execução MLV

Limitações conhecidas

Conteúdo relacionado

Comentários

Recursos adicionais