OneLake-Zugriff und -APIs

  • Artikel

Wichtig

Microsoft Fabric befindet sich in der Vorschau.

Überblick

Microsoft OneLake bietet offenen Zugriff auf alle Fabric-Elemente über vorhandene ADLS Gen2-APIs und SDKs. Sie können auf Ihre Daten in OneLake über jedes mit ADLS Gen2 kompatible Tool zugreifen, indem Sie stattdessen einen OneLake-URI verwenden. Sie können Daten über Azure Storage-Explorer in ein Lakehouse hochladen oder eine Deltatabelle über eine Verknüpfung aus Azure Databricks lesen.

Da OneLake Software-as-a-Service (SaaS) ist, müssen einige Vorgänge, z. B. das Verwalten von Berechtigungen oder das Aktualisieren von Elementen, über Fabric-Umgebungen erfolgen und können nicht über ADLS Gen2-APIs ausgeführt werden. Eine vollständige Liste der Änderungen an diesen APIs finden Sie im Abschnitt "Unterstützte API-Vorgänge".

URI-Syntax

Da OneLake in Ihrem gesamten Microsoft Fabric-Mandanten vorhanden ist, können Sie auf alles in Ihrem Mandanten anhand des Arbeitsbereichs, Elements und Pfads verweisen:

https://onelake.dfs.fabric.microsoft.com/<workspace>/<item>.<itemtype>/<path>/<fileName>

Hinweis

Da Elementnamen für mehrere Elementtypen wiederverwendet werden können, müssen Sie den Elementtyp in der Erweiterung angeben. Beispiel: ".lakehouse" für ein Lakehouse und ".datawarehouse" für ein Warehouse.

OneLake unterstützt auch das Verweisen auf Arbeitsbereiche und Elemente mit GUIDs. OneLake weist GUIDs und GUIDs zu, die sich nicht ändern, auch wenn sich der Arbeitsbereichs- oder Elementname ändert. Sie finden die zugeordnete GUID für Ihren Arbeitsbereich oder Ihr Element in der URL im Fabric-Portal. Sie müssen GUIDs sowohl für den Arbeitsbereich als auch für das Element verwenden und benötigen den Elementtyp nicht.

https://onelake.dfs.fabric.microsoft.com/<workspaceGUID>/<itemGUID>/Files/test.csv

Wenn Sie ein Tool für die Verwendung über OneLake anstelle von ADLS Gen2 verwenden, verwenden Sie die folgende Zuordnung:

  • Der Kontoname lautet immer "onelake".
  • Der Containername ist Ihr Arbeitsbereichsname.
  • Der Datenpfad beginnt am Element. Beispiel: "/mylakehouse.lakehouse/Files/".

OneLake- und ADLS Gen2-Parität

OneLake entspricht zwar nach Möglichkeit dem gesamten ADLS Gen2-Verhalten, aber nicht jedes Konzept in ADLS Gen2 weist eine direkte Korrelation mit OneLake auf. In den folgenden Abschnitten wird beschrieben, wie Sich OneLake von ADLS Gen2 unterscheidet, von nicht unterstützten Anforderungsheadern bis hin zu Änderungen an Antwortheadern. Weitere Informationen zu ADLS Gen2-APIs finden Sie unter Azure Data Lake Storage Gen2 REST-APIs.

Geschützte OneLake-Ordner

OneLake unterstützt das Erstellen, Aktualisieren oder Löschen von Arbeitsbereichen oder Elementen über die ADLS Gen2-APIs nicht. Nur HEAD Aufrufe werden auf Arbeitsbereichsebene und Kontoebene unterstützt, da Sie Änderungen am Fabric-Mandanten und an den Fabric-Arbeitsbereichen im Fabric-Verwaltungsportal vornehmen müssen.

OneLake erzwingt die Fabric-Elementstruktur, was bedeutet, dass Sie bestimmte Ordner nicht erstellen, lesen, aktualisieren oder löschen können, selbst wenn Sie der Besitzer des Elements oder Arbeitsbereichs sind. Sie müssen diese Vorgänge über Fabric-Umgebungen wie das Fabric-Portal oder die Fabric-Verwaltungs-APIs ausführen. Fabric-verwaltete Ordner umfassen den Ordner auf oberster Ebene in einem Element (z . B. /MyLakehouse.lakehouse) und die erste Ordnerebene darin (z . B. /MyLakehouse.lakehouse/Files und /MyLakehouse.lakehouse/Tables).

Sie können CRUD-Vorgänge für alle Ordner oder Dateien ausführen, die in diesen verwalteten Ordnern erstellt wurden.

Nicht unterstützte Anforderungsheader und -parameter

Auch in benutzerseitig erstellten und im Besitz befindlichen Dateien und Ordnern schränkt OneLake einige Verwaltungsvorgänge über ADLS Gen2-APIs ein. Sie können Berechtigungen nicht aktualisieren, Elemente oder Arbeitsbereiche bearbeiten oder Zugriffsebenen festlegen, da diese Vorgänge über Fabric verwaltet werden müssen.

OneLake lehnt einen API-Aufruf ab oder ignoriert ihn, wenn er einen nicht zulässigen Header- oder Parameterwert enthält. OneLake ignoriert Header, wenn der Header das Verhalten des Aufrufs nicht ändert, und gibt den abgelehnten Header in einem neuen Antwortheader "x-ms-rejected-headers" zurück. OneLake lehnt Anforderungen ab, die nicht zulässige Abfrageparameter enthalten. OneLake lässt die folgenden Verhaltensweisen und die zugehörigen Anforderungsheader und URI-Parameter nicht zu:

  • Festlegen der Zugriffssteuerung
    • URI-Parameter:
      • aktion: setAccessControl (Anforderung abgelehnt)
      • action: setAccessControlRecursive (Anforderung abgelehnt)
    • Anforderungsheader:
      • x-ms-owner (Header ignoriert)
      • x-ms-group (Header ignoriert)
      • x-ms-permissions (Header ignoriert)
      • x-ms-group (Header ignoriert)
      • x-ms-acls (Header ignoriert)
  • Festlegen des Verschlüsselungsbereichs
    • Anforderungsheader:
      • x-ms-encryption-key (Header ignoriert)
      • x-ms-encryption-key (Header ignoriert)
      • x-ms-encryption-algorithm:AES256 (Header ignoriert)
  • Festlegen der Zugriffsebene
    • Anforderungsheader:
      • x-ms-access-tier (Header ignoriert)

Unterschiede im Antwortheader

Da OneLake ein anderes Berechtigungsmodell als ADLS Gen2 verwendet, gibt es Änderungen an den Antwortheadern im Zusammenhang mit Berechtigungen:

  • "x-ms-owner" und "x-ms-group" geben immer "$superuser" zurück, da OneLake keine eigenen Benutzer oder Gruppen hat.
  • "x-ms-permissions" gibt immer "---------] zurück, da OneLake nicht über eigene Benutzer, Gruppen oder öffentliche Zugriffsberechtigungen verfügt.
  • "x-ms-acl" gibt die Fabric-Berechtigungen für den aufrufenden Benutzer zurück, die in eine POSIX-Zugriffssteuerungsliste (Access Control List, ACL) konvertiert wurden, im Format "rwx".

Autorisierung

Sie können OneLake-APIs mithilfe von Microsoft Azure Active Directory (Azure AD) authentifizieren, indem Sie einen Autorisierungsheader durchlaufen. Wenn ein Tool die Anmeldung bei Ihrem Azure-Konto unterstützt, um AAD-Passthrough zu aktivieren, können Sie ein beliebiges Abonnement auswählen. OneLake benötigt nur Ihr AAD-Token und kümmert sich nicht um Ihr Azure-Abonnement.

Datenresidenz

OneLake garantiert derzeit keine Datenresidenz in einer bestimmten Region bei Verwendung des globalen Endpunkts ("'https://onelake.dfs.fabric.microsoft.com"). Wenn Sie Daten in einer anderen Region als die Region Ihres Arbeitsbereichs abfragen, besteht die Möglichkeit, dass Daten Ihre Region während des Endpunktauflösungsprozesses verlassen. Wenn Sie sich Sorgen um die Datenresidenz machen, stellt die Verwendung des richtigen regionalen Endpunkts für Ihren Arbeitsbereich sicher, dass Ihre Daten in der aktuellen Region verbleiben und keine regionalen Grenzen überschreiten. Sie können den richtigen regionalen Endpunkt ermitteln, indem Sie die Region der Kapazität überprüfen, an die der Arbeitsbereich angefügt ist.

Regionale OneLake-Endpunkte haben alle das gleiche Format: "https://< region-onelake.dfs.fabric.microsoft.com>". Auf einen Arbeitsbereich, der an eine Kapazität in der Region USA, Westen 2 angefügt ist, kann beispielsweise über den regionalen Endpunkt zugegriffen werden.https://westus-onelake.dfs.fabric.microsoft.com.

Beispiele

Datei erstellen

Anforderung PUT https://onelake.dfs.fabric.microsoft.com/{workspace}/{item}.{itemtype}/Files/sample?resource=file
Headers Authorization: Bearer <userAADToken>
Antwort ResponseCode:201 Created
Header:
x-ms-version : 2021-06-08
x-ms-request-id : 272526c7-0995-4cc4-b04a-8ea3477bc67b
x-ms-content-crc64 : OAJ6r0dQWP0=
x-ms-request-server-encrypted : true
ETag : 0x8DA58EE365
Text:

Nächste Schritte

  • OneLake-Integration mit Azure Synapse Analytics