Administrer og oppdater materialiserte innsjøvisninger i Fabric med API-er

Microsoft Fabric REST API-er gjør det mulig å administrere og oppdatere materialiserte lake-visninger (MLV-er) programmatisk. Du kan automatisere linjeoppdateringsoperasjoner og integrere dem med andre verktøy og systemer.

Forhåndskrav

Før du bruker rest-API-ene med materialisert utsikt over innsjøen, må du fullføre disse forutsetningene:

  • Registrer en applikasjon med Microsoft Entra ID med riktig identitet. Skaff en tilgangstoken med passende omfang og send den i Authorization headeren til hver forespørsel.
  • Erstatt plassholderne inkludert {WORKSPACE_ID} og {LAKEHOUSE_ID} med passende WorkspaceId og LakehouseId. For å finne disse ID-ene, åpne lakehouse i Fabric-portalen — URL-en inneholder begge: https://app.fabric.microsoft.com/groups/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}. Alternativt kan du liste arbeidsområder og lakehouses ved hjelp av Fabric REST API-er for å få tilgang til dem programmatisk.

Følgende oppgaveplanlegger er tilgjengelige for materialiserte innsjøutsikter.

Handling Beskrivelse
Lag oppdateringsplan for MLV Lag en tidsplan for periodiske oppdateringer av MLV-er.
Få timeplan for MLV Få detaljer om en eksisterende oppdateringsplan.
Listeoppsett for MLV List opp alle oppdateringsplaner.
Oppdater oppdateringsplan for MLV Oppdater en eksisterende oppdateringsplan.
Slett oppdateringsplanen for MLV Slett en oppdateringsplan.
Kjør On Demand-oppdatering for MLV-er Kjør en umiddelbar oppdatering av MLV-er.
List jobbinstanser for MLV List opp alle oppdateringsinstanser for jobber.
Få detaljer om jobbinstanser for MLV Få detaljer om en spesifikk oppfriskningsjobb, som status.
Avbryt jobbinstans for MLV Avbryt en pågående oppdateringsjobb.

For mer informasjon, se jobbplanlegger, hvor {item} er Lakehouse og {jobType} er RefreshMaterializedLakeViews.

En MLV-utførelsesdefinisjon er en lagret konfigurasjon som spesifiserer hvilke materialiserte innsjøvisninger som skal oppdateres, hvilke innsjøhus oppstrøms som skal inkluderes, og hvilken oppdateringsmodus og Spark-miljø som skal brukes. Den definerer en delmengde av linjen som kan fornyes uavhengig.

Følgende handlinger er tilgjengelige for MLV-utførelsesdefinisjoner.

Handling Beskrivelse
Opprett MLV-utførelsesdefinisjon Lag en ny MLV-utførelsesdefinisjon.
Liste over MLV-utførelsesdefinisjoner List opp alle MLV-utførelsesdefinisjoner.
Få MLV-utførelsesdefinisjon Få detaljer om en eksisterende MLV-utførelsesdefinisjon.
Oppdater MLV-utførelsesdefinisjonen Oppdater en eksisterende MLV-utførelsesdefinisjon.
Slett MLV-eksekveringsdefinisjon Slett en MLV-utførelsesdefinisjon.

For mer informasjon, se materialiserte innsjøutsikter.

Følgende diagrammer viser hvordan man kan oppdatere materialiserte innsjøutsikter, med eller uten en MLV-utførelsesdefinisjon.

Bruk 1: Oppdater alle MLV-er i et innsjøhus (standard)

Skjermbilde som viser sekvensdiagram for oppdatering av alle MLV-er.

Bruk 2: Oppdater spesifikke MLV-er eller et delsett av linjen

Skjermbilde som viser sekvensdiagram for oppdatering av spesifikke MLV-er.

Note

Disse scenariene dekker brukseksempler som er spesifikke for materialisert utsikt over innsjøen. Eksempler på vanlige API-er for stoffelementer er ikke inkludert.

Eksempler på oppdatering av materialiserte innsjøvisninger ved bruk av API-er

Hvert eksempel viser HTTP-metoden, URL-adressen for endepunktet og eksempel på nyttelaster for forespørsel/svar.

Lag oppdateringsplan for MLV

Lag en plan for periodisk oppfriskning av slektslinjen. For å oppdatere kun et delsett av linjen, oppgi 'mlvExecutionDefinitionId' i executionData. For mer informasjon, se Oppfrisk materialisert innsjøvisningsplan og Få MLV-utførelsesdefinisjon.

Eksempelforespørsel uten MLV-utførelsesdefinisjon:

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

Eksempelforespørsel med MLV-utførelsesdefinisjon:

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

Eksempel på svar:

Statuskode: 201 Opprettet

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

Få timeplan for MLV

Få detaljer om en eksisterende oppdateringsplan. For mer informasjon, se få vareskjemaer med {item} as Lakehouse og {jobType} som RefreshMaterializedLakeViews.

Eksempel på forespørsel:

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

Eksempel på svar:

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

Listeoppsett for MLV

List opp alle oppdateringsplaner. For mer informasjon, se List Item Schedules with {item} as Lakehouse og {jobType} as RefreshMaterializedLakeViews.

Eksempel på forespørsel:

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

Eksempel på svar:

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

Oppdater oppdateringsplan for MLV

Oppdater en eksisterende oppdateringsplan. For mer informasjon, se Oppdatering Oppdatering av materialiserte innsjøvisninger.

Eksempel på forespørsel:

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

Eksempel på svar:

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

Slett oppdateringsplanen for MLV

Slett en oppdateringsplan. For mer informasjon, se Delete Refresh Materialized Lake Views Schedule.

Eksempel på forespørsel:

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

Eksempel på svar:

Statuskode: 200 OK

Kjør On Demand-oppdatering for MLV-er

Kjør en umiddelbar oppfriskning av slektslinjen. For å oppdatere kun et delsett av linjen, oppgi 'mlvExecutionDefinitionId' i executionData. For mer informasjon, se Run On Demand Refresh Materialized Lake Views og få MLV Execution Definition.

Eksempelforespørsel uten MLV-utførelsesdefinisjon:

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

Eksempelforespørsel med MLV-utførelsesdefinisjon:

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

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

Eksempel på svar:

Statuskode: 202 Godkjent

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

Med headeren Location kan du bruke Get Item Job Instance for å sjekke jobbstatus eller Cancel Item Job Instance for å avbryte kjøringen.

List jobbinstanser for MLV

List opp alle oppdateringsinstanser for jobber. For mer informasjon, se List item Job Instances med {item} som Lakehouse og {jobType}RefreshMaterializedLakeViews. Jobbstatusen gjenspeiler statusen i Monitor-huben.

Eksempel på forespørsel:

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

Eksempel på svar:

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

Få detaljer om jobbinstanser for MLV

Få status og detaljer for en spesifikk oppdateringsjobb. For mer informasjon, se Get Item Job Instance med {item} som Lakehouse. Jobbstatusen gjenspeiler statusen i Monitor-huben.

Eksempel på forespørsel:

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

Eksempel på svar:

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

Avbryt jobbinstans for MLV

Avbryt en pågående oppdateringsjobb. For mer informasjon, se Cancel Item Job Instance med {item} som Lakehouse.

Eksempel på forespørsel:

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

Eksempel på svar:

Statuskode: 202 Godkjent

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

Eksempler på bruk av MLV-utførelsesdefinisjons-API-er

Hvert eksempel viser HTTP-metoden, URL-adressen for endepunktet og eksempel på nyttelaster for forespørsel/svar.

Opprett MLV-utførelsesdefinisjon

Lag en ny MLV-utførelsesdefinisjon som spesifiserer hvilke MLV-er og oppstrøms innsjøhus som skal inkluderes, sammen med oppdateringsmodus og Spark-miljø. For mer informasjon, se Create Mlv Execution Definition.

Eksempel på forespørsel:

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

Eksempel på svar:

Statuskode: 201 Opprettet

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

Liste over MLV-utførelsesdefinisjoner

List opp alle MLV-utførelsesdefinisjoner. For mer informasjon, se Liste MLV-utførelsesdefinisjoner.

Eksempel på forespørsel:

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

Eksempel på svar:

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

Få MLV-utførelsesdefinisjon

Få detaljer om en eksisterende MLV-utførelsesdefinisjon, inkludert hvilke MLV-er som skal oppdateres, oppstrøms innsjøhus som skal inkluderes, oppdateringsmodus og Spark-miljø. For mer informasjon, se Get Mlv Execution Definition.

Eksempel på forespørsel:

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

Eksempel på svar:

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

Oppdater MLV-utførelsesdefinisjonen

Oppdater en eksisterende MLV-utførelsesdefinisjon. Bare feltene som er angitt i brødteksten for forespørselen, oppdateres. Utelatte felt beholder eksisterende verdier. For mer informasjon, se Update Mlv Execution Definition.

Eksempel på forespørsel:

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

Eksempel på svar:

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

Slett MLV-eksekveringsdefinisjon

Slett en MLV-utførelsesdefinisjon. Alle tidsplaner knyttet til den fjernes også. For mer informasjon, se Delete Mlv Execution Definition.

Eksempel på forespørsel:

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

Eksempel på svar:

Statuskode: 200 OK

Kjente begrensninger

Følgende begrensninger gjelder for rest-API-er med materialisert utsikt over innsjøen:

  • Begrensninger ved jobbplanlegger-API-er:
    • Jobbplanleggeren håndhever grenser for hvor mange planer som kan konfigureres per innsjøhus.
    • Jobbplanlegger-API-et returnerer et begrenset antall fullførte og aktive jobber, noe som kan påvirke innsikten i historiske eller samtidige kjøringer.
    • Begrensningene for Fabric offentlige API-er gjelder for materialiserte innsjøvisnings-API-er.
  • Stillingsstatusvisning: Statusen som returneres av listitem-jobbinstanser og get item-jobbinstansen gjenspeiler status i Monitor-huben. Det kan avvike fra materialiserte innsjøvisningers kjørehistorikk (for eksempel vises Hoppet som Kansellert i Monitor-huben).
  • Oppdateringsgrenser: For oppdateringsbegrensninger, se tillatelser og begrensninger.