Beheer en vernieuw gematerialiseerde datalakeweergaven in Fabric met behulp van API's

Microsoft Fabric REST API's stellen je in staat om gematerialiseerde lake views (MLV's) programmatisch te beheren en te verversen. Je kunt de vernieuwingsoperaties van je afstamming automatiseren en integreren met andere tools en systemen.

Vereiste voorwaarden

Voordat u de gerealiseerde REST API's van Lake Views gebruikt, moet u deze vereisten voltooien:

  • Registreer een applicatie met Microsoft Entra ID met de juiste identiteit. Verkrijg een toegangstoken met de juiste scopes en geef deze door in de Authorization header van elk verzoek.
  • Vervang de tijdelijke aanduidingen inclusief {WORKSPACE_ID} en {LAKEHOUSE_ID} door de juiste WorkspaceId en LakehouseId. Om deze ID's te vinden, open je het lakehouse in het Fabric-portaal — de URL bevat beide: https://app.fabric.microsoft.com/groups/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}. Alternatief kun je de werkruimtes en lakehouses vermelden met Fabric REST API's om er programmatisch toegang toe te krijgen.

De volgende taken van de taakplanner zijn beschikbaar voor gematerialiseerde meeruitzichten.

Handeling Description
Maak een verversingsschema voor MLV aan Maak een schema voor periodieke verversing van MLV's.
Haal het schema voor MLV op Bekijk details van een bestaand verversingsschema.
Lijstschema's voor MLV Noem alle verversingsschema's.
Update Verversingsschema voor MLV Werk een bestaand verversingsschema bij.
Verwijder Verversingsschema voor MLV Verwijder een verversschema.
Run On Demand Refresh voor MLV's Voer direct een update van MLV's uit.
Lijst van functie-instanties voor MLV Noem alle verversingsinstanties van de taak.
Krijg functiegegevens voor MLV Krijg details van een specifieke refresh-functie, zoals status.
Annuleer Job Instance voor MLV Annuleer een lopende verversingsopdracht.

Voor meer informatie, zie job scheduler, waar {item} is Lakehouse en {jobType} is RefreshMaterializedLakeViews.

Een MLV-uitvoeringsdefinitie is een opgeslagen configuratie die specificeert welke gematerialiseerde meerweergaven vernieuwd moeten worden, welke meerhuizen stroomopwaarts moeten worden opgenomen, en welke verversingsmodus en Spark-omgeving gebruikt moeten worden. Het definieert een deelverzameling van de lijn die onafhankelijk kan worden vernieuwd.

De volgende acties zijn beschikbaar voor MLV-uitvoeringsdefinities.

Handeling Description
Maak een MLV-uitvoeringsdefinitie aan Maak een nieuwe MLV-uitvoeringsdefinitie.
Lijst van MLV-uitvoeringsdefinities Noem alle MLV-uitvoeringsdefinities.
Krijg de MLV-uitvoeringsdefinitie Bekijk details van een bestaande MLV-uitvoeringsdefinitie.
Update de MLV-uitvoeringsdefinitie Werk een bestaande MLV-uitvoeringsdefinitie bij.
MLV uitvoeringsdefinitie verwijderen Verwijder een MLV-uitvoeringsdefinitie.

Voor meer informatie, zie gematerialiseerde meergezichten.

De volgende diagrammen tonen hoe je gematerialiseerde meerweergaven kunt verversen, met of zonder een MLV-uitvoeringsdefinitie.

Gebruik 1: Vernieuw alle MLV's in een lakehouse (standaard)

Screenshot met een sequentiediagram voor het verversen van alle MLV's.

Use case 2: Vernieuw specifieke MLV's of een subset van de afstamming

Screenshot met een sequentiediagram voor het verversen van specifieke mlv's.

Opmerking

Deze scenario's hebben betrekking op gebruiksvoorbeelden die specifiek zijn voor gerealiseerde lakeweergaven. Voorbeelden voor common Fabric-item-API's zijn niet opgenomen.

Voorbeelden van het verversen van gematerialiseerde meerweergaven met behulp van API's

In elk voorbeeld ziet u de HTTP-methode, de eindpunt-URL en de nettoladingen van voorbeeldaanvragen/antwoorden.

Maak een verversingsschema voor MLV aan

Maak een schema voor periodieke vernieuwing van de afstamming. Om slechts een deelverzameling van de lijn te verversen, geef je de 'mlvExecutionDefinitionId' in executionData. Voor meer informatie, zie Create Refresh Materialized Lake Views Schedule en Get MLV Execution Definition.

Voorbeeldverzoek zonder MLV-uitvoeringsdefinitie:

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

Voorbeeldverzoek met MLV Uitvoeringsdefinitie:

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

Voorbeeldantwoord:

Statuscode: 201 gemaakt

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

Haal het schema voor MLV op

Bekijk details van een bestaand verversingsschema. Voor meer informatie, zie 'get item schedules ' met {item} as Lakehouse en {jobType} as RefreshMaterializedLakeViews.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

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

Lijstschema's voor MLV

Noem alle verversingsschema's. Voor meer informatie, zie Lijstitemsschema's met {item} als Lakehouse en {jobType} als RefreshMaterializedLakeViews.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

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

Update Verversingsschema voor MLV

Werk een bestaand verversingsschema bij. Voor meer informatie, zie Update Refresh Materialized Lake Views Schedule.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

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

Verwijder Verversingsschema voor MLV

Verwijder een verversschema. Voor meer informatie, zie Schedule Delete Refresh Materialized Lake Views.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

Statuscode: 200 OK

Run On Demand Refresh voor MLV's

Voer direct een vernieuwing van de afstamming uit. Om slechts een deelverzameling van de lijn te verversen, geef je de 'mlvExecutionDefinitionId' in executionData. Voor meer informatie, zie Run On Demand Refresh Materialized Lake Views en Get MLV Execution Definition.

Voorbeeldverzoek zonder MLV-uitvoeringsdefinitie:

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

Voorbeeldverzoek met MLV Uitvoeringsdefinitie:

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

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

Voorbeeldantwoord:

Statuscode: 202 Geaccepteerd

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

Met de Location header kun je Get Item Job Instance gebruiken om de status van de job te controleren of Item Job Instance annuleren om de run te annuleren.

Lijst van functie-instanties voor MLV

Noem alle verversingsinstanties van de taak. Voor meer informatie, zie List Item Job Instances met {item} als Lakehouse en {jobType}RefreshMaterializedLakeViews. De taakstatus weerspiegelt de status in de Monitor-hub.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

Statuscode: 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
    }
  ]
}

Krijg functiegegevens voor MLV

Vraag status en details op voor een specifieke vernieuwingsfunctie. Voor meer informatie, zie Get Item Job Instance met {item} als Lakehouse. De taakstatus weerspiegelt de status in de Monitor-hub.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

Statuscode: 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
}

Annuleer Job Instance voor MLV

Annuleer een lopende verversingsopdracht. Voor meer informatie, zie Item Job Instance annuleren met {item} als Lakehouse.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

Statuscode: 202 Geaccepteerd

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

Voorbeelden van het gebruik van MLV-uitvoeringsdefinitie-API's

In elk voorbeeld ziet u de HTTP-methode, de eindpunt-URL en de nettoladingen van voorbeeldaanvragen/antwoorden.

Maak een MLV-uitvoeringsdefinitie aan

Maak een nieuwe MLV-uitvoeringsdefinitie die specificeert welke MLV's en upstream lakehouses moeten worden opgenomen, samen met de refresh-modus en Spark-omgeving. Voor meer informatie, zie Create Mlv Execution Definition.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

Statuscode: 201 gemaakt

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

Lijst van MLV-uitvoeringsdefinities

Noem alle MLV-uitvoeringsdefinities. Voor meer informatie, zie Lijst Mlv Uitvoeringsdefinities.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

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

Krijg de MLV-uitvoeringsdefinitie

Bekijk details van een bestaande MLV-uitvoeringsdefinitie, inclusief de MLV's die vernieuwd moeten worden, upstream lakehouses om te bevatten, de refresh-modus en de Spark-omgeving. Voor meer informatie, zie Get Mlv Execution Definition.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

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

Update de MLV-uitvoeringsdefinitie

Werk een bestaande MLV-uitvoeringsdefinitie bij. Alleen de velden in de aanvraagbody worden bijgewerkt; weggelaten velden behouden hun bestaande waarden. Voor meer informatie, zie Update Mlv Execution Definition.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

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

MLV uitvoeringsdefinitie verwijderen

Verwijder een MLV-uitvoeringsdefinitie. Alle schema's die eraan gekoppeld zijn, worden ook verwijderd. Voor meer informatie, zie Delete Mlv Execution Definition.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

Statuscode: 200 OK

Bekende beperkingen

De volgende beperkingen gelden voor de gerealiseerde REST API's van lake views:

  • Beperkingen van Job Scheduler API's:
    • De job scheduler stelt limieten aan hoeveel schema's per lakehouse kunnen worden geconfigureerd.
    • De job scheduler API geeft een beperkt aantal voltooide en actieve taken terug, wat de zichtbaarheid in historische of gelijktijdige uitvoeringen kan beïnvloeden.
    • De beperkingen voor Fabric publieke API's gelden voor gematerialiseerde lake views API's.
  • Functiestatusweergave: De status die wordt teruggegeven door list item job instances en get item job instance weerspiegelt de status in de Monitor hub. Het kan verschillen van de status van de rungeschiedenis van gematerialiseerde meerweergaven (bijvoorbeeld, Overgeslagen verschijnt als Geannuleerd in de Monitorhub).
  • Verversingslimieten: Voor verversbeperkingen, zie permissies en beperkingen.