Gestire e aggiornare le viste materializzate del lake in Fabric con le API

Le API Microsoft Fabric REST permettono di gestire e aggiornare programmaticamente le visualizzazioni materializzate dei laghi (MLV). Puoi automatizzare le operazioni di aggiornamento della linea e integrarle con altri strumenti e sistemi.

Prerequisiti

Prima di usare le API REST delle viste lake materializzate, completare questi prerequisiti:

  • Registra una domanda con Microsoft Entra ID con l'identità appropriata. Acquisire un token di accesso con i rilevamenti appropriati e passarlo nell'intestazione Authorization di ogni richiesta.
  • Sostituire i segnaposto inclusi {WORKSPACE_ID} e {LAKEHOUSE_ID} con appropriate WorkspaceId e LakehouseId. Per trovare questi ID, apri la casa sul lago nel portale Fabric — l'URL contiene entrambi: https://app.fabric.microsoft.com/groups/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}. In alternativa, puoi elencare gli spazi di lavoro e le case del lago usando le API Fabric REST per accedervi in modo programmativo.

Le seguenti azioni del pianificatore dei lavori sono disponibili per vedere il lago materializzato.

Action Description
Crea un programma di aggiornamento per MLV Crea un programma per il ripasso periodico delle MLV.
Ottieni il calendario per MLV Ottieni dettagli su un programma di aggiornamento esistente.
Elenco degli orari per MLV Elenca tutti i programmi di aggiornamento.
Programma di aggiornamento per MLV Aggiorna un programma di aggiornamento esistente.
Cancella il calendario di aggiornamento per MLV Elimina un programma di aggiornamento.
Aggiornamento Run On Demand per MLV Esegui un aggiornamento immediato delle MLV.
Elenca le istanze di lavoro per MLV Elenca tutte le istanze di aggiornamento dei lavori.
Ottieni dettagli sull'istanza di lavoro per MLV Ottieni dettagli su un lavoro di aggiornamento specifico, come lo stato.
Annulla l'istanza del lavoro per MLV Annulla un lavoro di aggiornamento in corso.

Per maggiori informazioni, consulta job scheduler, dove {item} si trova Lakehouse e {jobType} dove è RefreshMaterializedLakeViews.

Una definizione di esecuzione MLV è una configurazione salvata che specifica quali viste del lago materializzate aggiornare, quali lakehouse a monte includere e quale modalità di aggiornamento e ambiente Spark utilizzare. Definisce un sottoinsieme della linea che può essere aggiornato indipendentemente.

Le seguenti azioni sono disponibili per le definizioni di esecuzione MLV.

Action Description
Crea definizione di esecuzione MLV Crea una nuova definizione di esecuzione MLV.
Elenco delle definizioni di esecuzione MLV Elenca tutte le definizioni di esecuzione MLV.
Ottieni la definizione di esecuzione MLV Ottieni dettagli su una definizione di esecuzione MLV esistente.
Aggiorna la definizione di esecuzione MLV Aggiorna una definizione di esecuzione MLV esistente.
Elimina la definizione di esecuzione MLV Elimina una definizione di esecuzione MLV.

Per ulteriori informazioni, vedi le viste materializzate sul lago.

I diagrammi seguenti mostrano come aggiornare le viste materializzate dei laghi, con o senza una definizione di esecuzione MLV.

Caso d'uso 1: Aggiornare tutti gli MLV in una casa sul lago (predefinito)

Screenshot che mostra il diagramma di sequenza per l'aggiornamento di tutti gli MLV.

Caso d'uso 2: Aggiornare MLV specifici o un sottoinsieme della linea di stirpe

Screenshot che mostra il diagramma di sequenza per l'aggiornamento di specifici MLV.

Annotazioni

Questi scenari riguardano esempi di utilizzo specifici delle viste lake materializzate. Gli esempi per le API degli elementi di Fabric comuni non sono inclusi.

Esempi di aggiornamento di vedute materializzate su laghi utilizzando API

Ogni esempio mostra il metodo HTTP, l'URL dell'endpoint e i payload di richiesta/risposta di esempio.

Crea un programma di aggiornamento per MLV

Crea un programma per il rinnovo periodico della discendenza. Per aggiornare solo un sottoinsieme della lineage, fornire il 'mlvExecutionDefinitionId' in executionData. Per maggiori informazioni, consulta Refresh Materialized Lake View Schedule e Ottieni MLV Execution Definition.

Richiesta di esempio senza definizione di esecuzione 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
  }
}

Richiesta di esempio con definizione di esecuzione 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>"
  }
}

Risposta campione:

Codice di stato: 201 Creato

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

Ottieni il calendario per MLV

Ottieni dettagli su un programma di aggiornamento esistente. Per maggiori informazioni, consulta gli orari degli item con {item} come Lakehouse e {jobType} come RefreshMaterializedLakeViews.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 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"
  }
}

Elenco degli orari per MLV

Elenca tutti i programmi di aggiornamento. Per maggiori informazioni, consulta Elenca Elenchi Elementi con {item} come Lakehouse e {jobType} come RefreshMaterializedLakeViews.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 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"
      }
    }
  ]
}

Programma di aggiornamento per MLV

Aggiorna un programma di aggiornamento esistente. Per ulteriori informazioni, consulta Aggiorna il Programma delle Visualizzazioni Materializzate del Lago.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 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"
  }
}

Cancella il calendario di aggiornamento per MLV

Elimina un programma di aggiornamento. Per ulteriori informazioni, consulta Elimina Aggiorna il Calendario delle Visualizzazioni Materializzate del Lago.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 200 OK

Aggiornamento Run On Demand per MLV

Fai un immediato rinnovo della discendenza. Per aggiornare solo un sottoinsieme della lineage, fornire il 'mlvExecutionDefinitionId' in executionData. Per maggiori informazioni, consulta Run On Demand Refresh Materialized Lake Views e Ottieni la definizione di esecuzione MLV.

Richiesta di esempio senza definizione di esecuzione MLV:

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

Richiesta di esempio con definizione di esecuzione MLV:

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

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

Risposta campione:

Codice di stato: 202 Accettato

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

Con l'intestazione Location puoi usare Ottieni Item Job Instance per controllare lo stato del lavoro o Annulla Item Job Instance per annullare la run.

Elenca le istanze di lavoro per MLV

Elenca tutte le istanze di aggiornamento dei lavori. Per maggiori informazioni, consulta Elenca Istanze di Lavoro con {item} come Lakehouse e {jobType}RefreshMaterializedLakeViews. Lo stato del lavoro riflette lo status nel hub Monitor.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 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
    }
  ]
}

Ottieni dettagli sull'istanza di lavoro per MLV

Ottieni lo stato e i dettagli di un'istanza specifica di aggiornamento del lavoro. Per maggiori informazioni, vedi Ottieni Item Job Instance con {item} come Lakehouse. Lo stato del lavoro riflette lo status nel hub Monitor.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 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
}

Annulla l'istanza del lavoro per MLV

Annulla un lavoro di aggiornamento in corso. Per maggiori informazioni, consulta Annulla Istanza di Lavoro Item con {item} come Lakehouse.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 202 Accettato

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

Esempi di utilizzo di API di definizione di esecuzione MLV

Ogni esempio mostra il metodo HTTP, l'URL dell'endpoint e i payload di richiesta/risposta di esempio.

Crea definizione di esecuzione MLV

Crea una nuova definizione di esecuzione MLV che specifichi quali MLV e le case lacustre a monte includere, insieme alla modalità refresh e all'ambiente Spark. Per maggiori informazioni, vedi Definizione di Esecuzione Crea MLV.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 201 Creato

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

Elenco delle definizioni di esecuzione MLV

Elenca tutte le definizioni di esecuzione MLV. Per ulteriori informazioni, vedi Elenco delle definizioni di esecuzione di MLV.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 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"
      }
    }
  ]
}

Ottieni la definizione di esecuzione MLV

Ottieni dettagli su una definizione di esecuzione MLV esistente, inclusi i MLV da aggiornare, le case lacustre a monte da includere, la modalità di aggiornamento e l'ambiente Spark. Per ulteriori informazioni, vedi Definizione di esecuzione MLV.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 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"
  }
}

Aggiorna la definizione di esecuzione MLV

Aggiorna una definizione di esecuzione MLV esistente. Vengono aggiornati solo i campi forniti nel corpo della richiesta; i campi omessi mantengono i valori esistenti. Per ulteriori informazioni, vedi Aggiorna la Definizione di Esecuzione MLV.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 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>"
      }
    ]
  }
}

Elimina la definizione di esecuzione MLV

Elimina una definizione di esecuzione MLV. Qualsiasi programma collegato ad essa viene anche rimosso. Per ulteriori informazioni, vedi Elimina Definizione di Esecuzione MLV.

Richiesta di esempio:

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

Risposta campione:

Codice di stato: 200 OK

Limitazioni note

Le limitazioni seguenti si applicano alle API REST materializzate lake views: