Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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
Authorizationdi ogni richiesta. - Sostituire i segnaposto inclusi
{WORKSPACE_ID}e{LAKEHOUSE_ID}con appropriateWorkspaceIdeLakehouseId. 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)
Caso d'uso 2: Aggiornare MLV specifici o un sottoinsieme della linea di stirpe
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:
-
Limiti delle API del Job Scheduler:
- Il scheduler dei lavori applica limiti su quanti orari possono essere configurati per ogni lakehouse.
- L'API del pianificatore di lavoro restituisce un numero limitato di lavori completati e attivi, il che può influire sulla visibilità delle esecuzioni storiche o concorrenti.
- I limiti di throttling per le API pubbliche Fabric si applicano alle API di visualizzazioni dei laghi materializzati.
- Visualizzazione dello stato del lavoro: Lo stato restituito da istanze di lavoro di item di lista e istanza di job di oggetto di item riflette lo stato nel hub Monitor. Potrebbe differire dallo stato di cronologia delle visualizzazioni materializzate dei laghi (ad esempio, Saltata appare come Cancellato nel Monitor hub).
- Limiti di refresh: Per i vincoli di aggiornamento, vedi permessi e limitazioni.