Administración y actualización de vistas materializadas de lago en Fabric con API

Las APIs REST de Microsoft Fabric permiten gestionar y actualizar las vistas materializadas de lagos (MLVs) de forma programática. Puedes automatizar las operaciones de actualización de linaje e integrarlas con otras herramientas y sistemas.

Prerrequisitos

Antes de usar las API REST materializadas de vistas de lago, complete estos requisitos previos:

Registra una solicitud con el Microsoft Entra ID con la identidad correspondiente. Adquiere un token de acceso con los ámbitos adecuados y pásalo en la Authorization cabecera de cada solicitud.
Sustituye los marcadores de posición incluyendo {WORKSPACE_ID} y {LAKEHOUSE_ID} por apropiados WorkspaceId y LakehouseId. Para encontrar estos IDs, abre la casa del lago en el portal Fabric — la URL contiene ambos: https://app.fabric.microsoft.com/groups/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}. Alternativamente, puedes listar los espacios de trabajo y las casas del lago usando APIs REST de Fabric para acceder a ellos de forma programática.

Las siguientes acciones del planificador de tareas están disponibles para vistas materializadas al lago.

Acción	Description
Crear un calendario de actualización para MLV	Crea un calendario para la actualización periódica de los MLVs.
Consulta el horario de MLV	Obtén detalles sobre un calendario de actualización existente.
Calendarios de lista para MLV	Enumera todos los horarios de actualización.
Calendario de actualización de actualización para MLV	Actualiza un calendario de actualizaciones existente.
Eliminar el calendario de actualización para MLV	Elimina un horario de actualización.
Actualización bajo demanda para MLVs	Haz una actualización inmediata de los MLV.
Listar instancias de trabajos para MLV	Haz una lista de todas las instancias de refresco de trabajos.
Obtén detalles de instancias de trabajo para MLV	Obtén detalles de un trabajo de actualización específico, como el estado.
Cancelar instancia de trabajo para MLV	Cancela un trabajo de actualización en curso.

Para más información, consulta el horario de trabajo, dónde {item} está Lakehouse y {jobType} dónde está RefreshMaterializedLakeViews.

Una definición de ejecución MLV es una configuración guardada que especifica qué vistas de lago materializadas deben actualizarse, qué casas lacustres aguas arriba incluir y qué modo de actualización y entorno Spark utilizar. Define un subconjunto del linaje que puede actualizarse de forma independiente.

Las siguientes acciones están disponibles para las definiciones de ejecución de MLV.

Acción	Description
Crear definición de ejecución MLV	Crea una nueva definición de ejecución MLV.
Lista de definiciones de ejecución de MLV	Enumera todas las definiciones de ejecución de MLV.
Obtén la definición de ejecución MLV	Obtén detalles de una definición existente de ejecución de MLV.
Actualizar la definición de ejecución de MLV	Actualiza una definición existente de ejecución de MLV.
Eliminar definición de ejecución MLV	Elimina una definición de ejecución MLV.

Para más información, véase vistas materializadas del lago.

Los siguientes diagramas muestran cómo actualizar vistas materializadas de lagos, con o sin una definición de ejecución MLV.

Caso de uso 1: Actualizar todas las MLV en una casa de lago (por defecto)

Caso de uso 2: Actualizar MLVs específicos o un subconjunto de la línea

Nota:

En estos escenarios se tratan ejemplos de uso específicos de las vistas materializadas del lago. No se incluyen ejemplos de API de elementos de Fabric comunes.

Ejemplos de refrescar vistas materializadas de lagos usando APIs

En cada ejemplo se muestra el método HTTP, la dirección URL del punto de conexión y las cargas de solicitud y respuesta de ejemplo.

Crear un calendario de actualización para MLV

Crea un calendario para la actualización periódica de linaje. Para actualizar solo un subconjunto del linaje, proporciona el 'mlvExecutionDefinitionId' en executionData. Para más información, consulte Crear Actualizar el Calendario de Vistas Materializadas de Lagos y Obtener la Definición de Ejecución MLV.

Solicitud de ejemplo sin definición de ejecución 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
  }
}

Solicitud de ejemplo con definición de ejecución 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>"
  }
}

Respuesta de ejemplo:

Código de estado: 201 Creado

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

Consulta el horario de MLV

Obtén detalles sobre un calendario de actualización existente. Para más información, consulta los listarios de ítems con {item} como Lakehouse y {jobType} como RefreshMaterializedLakeViews.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 200 Correcto

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

Calendarios de lista para MLV

Enumera todos los horarios de actualización. Para más información, consulte Listar Calendarios de Ítems con {item} como Lakehouse y {jobType} como RefreshMaterializedLakeViews.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 200 Correcto

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

Calendario de actualización de actualización para MLV

Actualiza un calendario de actualizaciones existente. Para más información, consulte Actualizar el Calendario de Vistas Materializadas del Lago.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 200 Correcto

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

Eliminar el calendario de actualización para MLV

Elimina un horario de actualización. Para más información, consulte Eliminar Actualizar Calendario de Vistas Materializadas del Lago.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 200 Correcto

Actualización bajo demanda para MLVs

Haz una actualización inmediata de la línea genealógica. Para actualizar solo un subconjunto del linaje, proporciona el 'mlvExecutionDefinitionId' en executionData. Para más información, consulte Run On Demand Refresh Materialized Lake Views y Obtén MLV Execution Definition.

Solicitud de ejemplo sin definición de ejecución MLV:

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

Solicitud de ejemplo con definición de ejecución MLV:

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

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

Respuesta de ejemplo:

Código de estado: 202 Aceptado

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

Con el Location encabezado, puedes usar Obtener Instancia de Trabajo de Elemento para comprobar el estado del trabajo o Cancelar Instancia de Trabajo de Elemento para cancelar la partida.

Listar instancias de trabajos para MLV

Haz una lista de todas las instancias de refresco de trabajos. Para más información, consulte Listar instancias de empleo con{item} como Lakehouse y {jobType}RefreshMaterializedLakeViews. El estado del puesto refleja el estado en el hub de Monitor.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 200 Correcto

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

Obtén detalles de instancias de trabajo para MLV

Obtén el estado y los detalles de una instancia específica de refresco de trabajo. Para más información, consulta Obtener Instancia de Trabajo de Ítem con {item} como Lakehouse. El estado del puesto refleja el estado en el hub de Monitor.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 200 Correcto

{
  "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 instancia de trabajo para MLV

Cancela un trabajo de actualización en curso. Para más información, consulta Cancelar Instancia de Trabajo de Item con {item} como Lakehouse.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 202 Aceptado

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

Ejemplos de uso de APIs de definición de ejecución MLV

En cada ejemplo se muestra el método HTTP, la dirección URL del punto de conexión y las cargas de solicitud y respuesta de ejemplo.

Crear definición de ejecución MLV

Crear una nueva definición de ejecución MLV que especifique qué MLVs y casas lacustres aguas arriba incluir, junto con el modo de actualización y el entorno Spark. Para más información, consulte Definición de Creación de Ejecución MLV.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 201 Creado

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 definiciones de ejecución de MLV

Enumera todas las definiciones de ejecución de MLV. Para más información, consulte Lista de definiciones de ejecución de MLV.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 200 Correcto

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

Obtén la definición de ejecución MLV

Obtén detalles de una definición existente de ejecución de MLV, incluyendo los MLVs para refrescar, casas lacustres aguas arriba para incluir, modo de actualización y entorno Spark. Para más información, véase Definición de Ejecución de Mlv.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 200 Correcto

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

Actualizar la definición de ejecución de MLV

Actualiza una definición existente de ejecución de MLV. Solo se actualizan los campos proporcionados en el cuerpo de la solicitud; Los campos omitidos conservan sus valores existentes. Para más información, consulte Actualizar la Definición de Ejecución de MLV.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 200 Correcto

{
  "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 definición de ejecución MLV

Elimina una definición de ejecución MLV. Cualquier calendario vinculado también se elimina. Para más información, consulte Eliminar Definición de Ejecución MLV.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

Código de estado: 200 Correcto

Limitaciones conocidas

Las siguientes limitaciones se aplican a las API REST materializadas de vistas de lago:

Límites de las APIs del planificador de trabajos:
- El planificador de tareas impone límites sobre cuántos horarios se pueden configurar por casa del lago.
- La API del planificador de trabajos devuelve un número limitado de trabajos completados y activos, lo que puede afectar la visibilidad de ejecuciones históricas o concurrentes.
- Los límites de limitación para las APIs públicas de Fabric se aplican a las APIs de vistas de lago materializadas.
Visualización del estado del puesto: El estado devuelto por instancias de trabajo de ítems de lista y instancia de trabajo de elemento obtener refleja el estado en el hub de Monitor. Puede diferir del estado de historial de recorrido de vistas materializadas de lagos (por ejemplo, Saltado aparece como Cancelado en el centro de monitores).
Límites de refresco: Para las restricciones de refresco, consulta permisos y limitaciones.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-07-01

Administración y actualización de vistas materializadas de lago en Fabric con API

Prerrequisitos

Ejemplos de refrescar vistas materializadas de lagos usando APIs

Crear un calendario de actualización para MLV

Consulta el horario de MLV

Calendarios de lista para MLV

Calendario de actualización de actualización para MLV

Eliminar el calendario de actualización para MLV

Actualización bajo demanda para MLVs

Listar instancias de trabajos para MLV

Obtén detalles de instancias de trabajo para MLV

Cancelar instancia de trabajo para MLV

Ejemplos de uso de APIs de definición de ejecución MLV

Crear definición de ejecución MLV

Lista de definiciones de ejecución de MLV

Obtén la definición de ejecución MLV

Actualizar la definición de ejecución de MLV

Eliminar definición de ejecución MLV

Limitaciones conocidas

Contenido relacionado

Comentarios

Recursos adicionales