Gerencie e atualize vistas materializadas de lago no Fabric com APIs

As APIs REST do Microsoft Fabric permitem-lhe gerir e atualizar as visualizações materializadas de lagos (MLVs) de forma programática. 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 materializadas para vistas de lago, cumpra estes pré-requisitos:

Registar uma candidatura com o Microsoft Entra ID com a identidade apropriada. Adquira um token de acesso com os escopos apropriados e envie-o no Authorization cabeçalho de cada pedido.
Substitua os marcadores de lugar incluindo {WORKSPACE_ID} e {LAKEHOUSE_ID} por apropriados WorkspaceId e LakehouseId. Para encontrar estes IDs, abra a casa do lago no portal Fabric — o URL contém ambos: https://app.fabric.microsoft.com/groups/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}. Em alternativa, pode listar os espaços de trabalho e as casas de lago usando APIs Fabric REST para aceder a eles programaticamente.

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

Ação	Description
Criar Calendário de Atualização para MLV	Crie um calendário para atualização periódica dos MLVs.
Obtenha o Horário do MLV	Obtenha detalhes sobre um calendário de renovações existente.
Listas de Calendários para MLV	Liste todos os horários de renovação.
Atualização do Calendário de Atualização para MLV	Atualize um calendário de atualização existente.
Apagar o Calendário de Atualização para MLV	Apaga um calendário de atualizações.
Atualização Run On Demand para MLVs	Faz 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 Emprego para MLV	Obtenha detalhes de um emprego específico de atualização, como o estatuto.
Cancelar Instância de Trabalho para MLV	Cancelar um trabalho de atualização em andamento.

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

Uma definição de execução MLV é uma configuração guardada que especifica quais as vistas materializadas do lago a atualizar, quais as casas de lago a montante a incluir, e qual modo de atualização e ambiente Spark utilizar. Define um subconjunto da linhagem que pode ser atualizado de forma independente.

As seguintes ações estão disponíveis para definições de execução 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.
Obter a Definição de Execução MLV	Obtenha detalhes de uma definição existente de execução MLV.
Atualização da Definição de Execução MLV	Atualize uma definição de execução MLV existente.
Eliminar Definição de Execução MLV	Apague uma definição de execução MLV.

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

Os diagramas seguintes mostram como atualizar as vistas materializadas do lago, com ou sem uma definição de execução MLV.

Caso de Uso 1: Atualizar todos os MLVs numa casa de lago (por defeito)

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

Observação

Estes cenários abrangem exemplos de utilização específicos para vistas materializadas de lagos. Exemplos de APIs comuns de itens do Fabric não estão incluídos.

Exemplos de refrescar vistas materializadas de lagos usando APIs

Cada exemplo mostra o método HTTP, a URL do endpoint e os payloads de pedido/resposta de exemplo.

Criar Calendário de Atualização para MLV

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

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

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

Exemplo de resposta:

Código de estado: 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 o Horário do MLV

Obtenha detalhes sobre um calendário de renovações existente. Para mais informações, consulte os tabelos de itens com {item} as Lakehouse e {jobType} como RefreshMaterializedLakeViews.

Pedido de amostra:

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

Exemplo de resposta:

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 Calendários para MLV

Liste todos os horários de renovação. Para mais informações, consulte Listar Listas de Itens com {item} como Lakehouse e {jobType} como RefreshMaterializedLakeViews.

Pedido de amostra:

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

Exemplo de resposta:

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

Atualização do Calendário de Atualização para MLV

Atualize um calendário de atualização existente. Para mais informações, consulte Atualizar o Calendário de Materialized Lake Views.

Pedido de amostra:

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

Exemplo de resposta:

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

Apagar o Calendário de Atualização para MLV

Apaga um calendário de atualizações. Para mais informações, consulte Apagar Atualizar Calendário de Visualizações Materializadas do Lago.

Pedido de amostra:

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

Exemplo de resposta:

Código de status: 200 OK

Atualização Run On Demand para MLVs

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

Pedido de exemplo sem definição de execução MLV:

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

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

Exemplo de resposta:

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, podes usar o Get Item Job Instance para verificar o estado do job ou Cancelar Item Job Instance para cancelar a sequência.

Listar Instâncias de Emprego para MLV

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

Pedido de amostra:

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

Exemplo de resposta:

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 Emprego para MLV

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

Pedido de amostra:

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

Exemplo de resposta:

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

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

Pedido de amostra:

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

Exemplo de resposta:

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 utilização de APIs de definição de execução MLV

Cada exemplo mostra o método HTTP, a URL do endpoint e os payloads de pedido/resposta de exemplo.

Criar Definição de Execução MLV

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

Pedido de amostra:

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

Exemplo de resposta:

Código de estado: 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, consulte Lista de Definições de Execução MLV.

Pedido de amostra:

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

Exemplo de resposta:

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

Obter 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, consulte Obter Definição de Execução MLV.

Pedido de amostra:

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

Exemplo de resposta:

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

Atualização da Definição de Execução MLV

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

Pedido de amostra:

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

Exemplo de resposta:

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

Eliminar Definição de Execução MLV

Apague uma definição de execução MLV. Quaisquer horários ligados a ela também são removidos. Para mais informações, consulte Delete TMLV Execution Definition.

Pedido de amostra:

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

Exemplo de resposta:

Código de status: 200 OK

Limitações conhecidas

As seguintes limitações aplicam-se às APIs REST materializadas das vistas de lagos:

Limites das APIs do Agendador de Tarefas:
- O agendador de tarefas impõe limites sobre quantos horários podem ser configurados por casa do lago.
- A API do agendador de trabalhos devolve 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 aplicam-se às APIs de visualizações de lagos materializadas.
Exibição do estado do cargo: O estado devolvido por listas de instâncias de job item e obter instância de job item reflete o estado no hub Monitor. Pode diferir do estado de histórico de visualizações materializadas do lago (por exemplo, Saltado aparece como Cancelado no hub de Monitor).
Limites de atualização: Para restrições de atualização, consulte permissões e limitações.

Comentários

Esta página foi útil?

Last updated on 2026-07-01

Gerencie e atualize vistas materializadas de lago no Fabric com APIs

Pré-requisitos

Exemplos de refrescar vistas materializadas de lagos usando APIs

Criar Calendário de Atualização para MLV

Obtenha o Horário do MLV

Listas de Calendários para MLV

Atualização do Calendário de Atualização para MLV

Apagar o Calendário de Atualização para MLV

Atualização Run On Demand para MLVs

Listar Instâncias de Emprego para MLV

Obtenha Detalhes da Instância de Emprego para MLV

Cancelar Instância de Trabalho para MLV

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

Criar Definição de Execução MLV

Lista de definições de execução MLV

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

Atualização da Definição de Execução MLV

Eliminar Definição de Execução MLV

Limitações conhecidas

Conteúdo relacionado

Comentários

Recursos adicionais