Komma igång med OneLake-tabell-API:er för Iceberg

OneLake erbjuder en REST API-slutpunkt för att interagera med tabeller i Microsoft Fabric. Den här slutpunkten stöder endast läsbara metadataoperationer för Apache Iceberg-tabeller i Fabric. Dessa åtgärder är kompatibla med Isberg REST Catalog (IRC) API open standard.

Viktigt!

Den här funktionen är i förhandsversion.

Förutsättningar

Läs mer om OneLake-tabell-API:er för Iceberg och se till att granska nödvändig information.

Exempel på klientsnabbstart

Granska de här exemplen för att lära dig hur du konfigurerar befintliga IRC-klienter (Iceberg REST Catalog) för användning med den nya OneLake-tabellslutpunkten.

PyIceberg

Använd följande Python-exempelkod för att konfigurera PyIceberg att använda OneLake-tabell-API-slutpunkten. Sedan listar du scheman och tabeller i ett dataobjekt.

Den här koden förutsätter att det finns en Standard AzureCredential tillgänglig för en inloggad användare. Du kan också använda MSAL Python-biblioteket för att hämta en token.

from pyiceberg.catalog import load_catalog
from azure.identity import DefaultAzureCredential

# Iceberg base URL at the OneLake table API endpoint
table_api_url = "https://onelake.table.fabric.microsoft.com/iceberg"

# Entra ID token
credential = DefaultAzureCredential()
token = credential.get_token("https://storage.azure.com/.default").token

# Client configuration options
fabric_workspace_id = "12345678-abcd-4fbd-9e50-3937d8eb1915"
fabric_data_item_id = "98765432-dcba-4209-8ac2-0821c7f8bd91"
warehouse = f"{fabric_workspace_id}/{fabric_data_item_id}"
account_name = "onelake"
account_host = f"{account_name}.blob.fabric.microsoft.com"

# Configure the catalog object for a specific data item
catalog = load_catalog("onelake_catalog", **{
    "uri": table_api_url,
    "token": token,
    "warehouse": warehouse,
    "adls.account-name": account_name,
    "adls.account-host": account_host,
    "adls.credential": credential,
})

# List schemas and tables within a data item
schemas = catalog.list_namespaces()
print(schemas)
for schema in schemas:
    tables = catalog.list_tables(schema)
    print(tables)

Snowflake

Använd följande exempelkod för att skapa en ny kataloglänkad databas i Snowflake. Den här databasen innehåller automatiskt alla scheman och tabeller som finns i det anslutna fabric-dataobjektet. Det handlar om att skapa en katalogintegrering, en extern volym och en databas.

-- Create catalog integration object
CREATE OR REPLACE CATALOG INTEGRATION IRC_CATINT
    CATALOG_SOURCE = ICEBERG_REST
    TABLE_FORMAT = ICEBERG
    REST_CONFIG = (
        CATALOG_URI = 'https://onelake.table.fabric.microsoft.com/iceberg' -- Iceberg base URL at the OneLake table endpoint
        CATALOG_NAME = '12345678-abcd-4fbd-9e50-3937d8eb1915/98765432-dcba-4209-8ac2-0821c7f8bd91' -- Fabric data item scope, in the form `workspaceID/dataItemID`
    )
    REST_AUTHENTICATION = (
        TYPE = OAUTH -- Entra auth
        OAUTH_TOKEN_URI = 'https://login.microsoftonline.com/11122233-1122-4138-8485-a47dc5d60435/oauth2/v2.0/token' -- Entra tenant ID
        OAUTH_CLIENT_ID = '44332211-aabb-4d12-aef5-de09732c24b1' -- Entra application client ID
        OAUTH_CLIENT_SECRET = '[secret]' -- Entra application client secret value
        OAUTH_ALLOWED_SCOPES = ('https://storage.azure.com/.default') -- Storage token audience
    )
    ENABLED = TRUE
;

-- Create external volume object
CREATE OR REPLACE EXTERNAL VOLUME IRC_EXVOL
    STORAGE_LOCATIONS =
    (
        (
            NAME = 'IRC_EXVOL'
            STORAGE_PROVIDER = 'AZURE'
            STORAGE_BASE_URL = 'azure://onelake.dfs.fabric.microsoft.com/12345678-abcd-4fbd-9e50-3937d8eb1915/98765432-dcba-4209-8ac2-0821c7f8bd91'
            AZURE_TENANT_ID='11122233-1122-4138-8485-a47dc5d60435' -- Entra tenant id
        )
    )
    ALLOW_WRITES = FALSE;
;

-- Describe the external volume
DESC EXTERNAL VOLUME IRC_EXVOL;

Svaret från DESC EXTERNAL VOLUME returnerar metadata om den externa volymen, inklusive:

AZURE_CONSENT_URL, som är sidan för behörighetsbegäran som måste följas om det ännu inte har gjorts för din hyresgäst.
AZURE_MULTI_TENANT_APP_NAME, som är namnet på Snowflake-klientprogrammet som behöver åtkomst till dataobjektet. Se till att ge det åtkomst till dataobjektet för att Snowflake ska kunna läsa tabellinnehåll.

-- Create a Snowflake catalog linked database
CREATE OR REPLACE DATABASE IRC_CATALOG_LINKED
    LINKED_CATALOG = (
        CATALOG = 'IRC_CATINT'
    )
    EXTERNAL_VOLUME = 'IRC_EXVOL'
;

SELECT SYSTEM$CATALOG_LINK_STATUS('IRC_CATALOG_LINKED');

SELECT * FROM IRC_CATALOG_LINKED."dbo"."sentiment";

DuckDB

Använd följande Python-exempelkod för att konfigurera DuckDB för att visa scheman och tabeller i ett dataobjekt.

Den här koden förutsätter att det finns en standard AzureCredential som är tillgänglig för en inloggad användare. Du kan också använda MSAL Python-biblioteket för att hämta en token.

import duckdb
from azure.identity import DefaultAzureCredential

# Iceberg API base URL at the OneLake table API endpoint
table_api_url = "https://onelake.table.fabric.microsoft.com/iceberg"

# Entra ID token
credential = DefaultAzureCredential()
token = credential.get_token("https://storage.azure.com/.default").token

# Client configuration options
fabric_workspace_id = "12345678-abcd-4fbd-9e50-3937d8eb1915"
fabric_data_item_id = "98765432-dcba-4209-8ac2-0821c7f8bd91"
warehouse = f"{fabric_workspace_id}/{fabric_data_item_id}"

# Connect to DuckDB
con = duckdb.connect()

# Install & load extensions
con.execute("INSTALL iceberg; LOAD iceberg;")
con.execute("INSTALL azure; LOAD azure;")
con.execute("INSTALL httpfs; LOAD httpfs;")

# --- Auth & Catalog ---
# 1) Secret for the Iceberg REST Catalog (use existing bearer token)
con.execute("""
CREATE OR REPLACE SECRET onelake_catalog (
TYPE ICEBERG,
TOKEN ?
);
""", [token])

# 2) Secret for ADLS Gen2 / OneLake filesystem access via Azure extension
#    (access token audience must be https://storage.azure.com; account name is 'onelake')
con.execute("""
CREATE OR REPLACE SECRET onelake_storage (
TYPE AZURE,
PROVIDER ACCESS_TOKEN,
ACCESS_TOKEN ?,
ACCOUNT_NAME 'onelake'
);
""", [token])

# 3) Attach the Iceberg REST catalog
con.execute(f"""
ATTACH '{warehouse}' AS onelake (
TYPE ICEBERG,
SECRET onelake_catalog,
ENDPOINT '{table_api_url}'
);
""")

# --- Explore & Query ---
display(con.execute("SHOW ALL TABLES").fetchdf())

Exempel på begäranden och svar

Dessa exempelbegäranden och svar illustrerar användningen av Iceberg REST Catalog-åtgärder (IRC) som för närvarande stöds vid API-slutpunkt för OneLake-tabell. Mer information om IRC finns i den öppna standardspecifikationen.

För var och en av dessa åtgärder:

<BaseUrl> är https://onelake.table.fabric.microsoft.com/iceberg
<Warehouse> är <Workspace>/<DataItem>, vilket kan vara:
- <WorkspaceID>/<DataItemID> såsom 12345678-abcd-4fbd-9e50-3937d8eb1915/98765432-dcba-4209-8ac2-0821c7f8bd91
- <WorkspaceName>/<DataItemName>.<DataItemType>, till exempel MyWorkspace/MyItem.Lakehouse, så länge båda namnen inte innehåller specialtecken.
<Prefix> returneras av anropet Hämta konfiguration och dess värde är vanligtvis detsamma som <Warehouse>.
<Token> är värdet för åtkomsttoken som returneras av Entra-ID vid lyckad autentisering.

Hämta konfiguration

Lista konfigurationsinställningar för Iceberg-katalog.

Förfrågan

GET <BaseUrl>/v1/config?warehouse=<Warehouse>
Authorization: Bearer <Token>

Svar

200 OK
{
    "defaults": {},
    "endpoints": [
        "GET /v1/{prefix}/namespaces",
        "GET /v1/{prefix}/namespaces/{namespace}",
        "HEAD /v1/{prefix}/namespaces/{namespace}",
        "GET /v1/{prefix}/namespaces/{namespace}/tables",
        "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
        "HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}"
    ],
    "overrides": {
        "prefix": "<Prefix>"
    }
}

Lista över scheman

Visa en lista över scheman i ett fabric-dataobjekt.

Förfrågan

GET <BaseUrl>/v1/<Prefix>/namespaces
Authorization: Bearer <Token>

Svar

200 OK
{
    "namespaces": [
        [
            "dbo"
        ]
    ],
    "next-page-token": null
}

Hämta schema

Hämta schemainformation för ett visst schema.

Förfrågan

GET <BaseUrl>/v1/<Prefix>/namespaces/<SchemaName>
Authorization: Bearer <Token>

Svar

200 OK
{
    "namespace": [
        "dbo"
    ],
    "properties": {
        "location": "d892007b-3216-424a-a339-f3dca61335aa/40ef140a-8542-4f4c-baf2-0f8127fd59c8/Tables/dbo"
    }
}

Lista tabeller

Lista tabeller inom ett visst schema.

Förfrågan

GET <BaseUrl>/v1/<Prefix>/namespaces/<SchemaName>/tables
Authorization: Bearer <Token>

Svar

200 OK
{
    "identifiers": [
        {
            "namespace": [
                "dbo"
            ],
            "name": "DIM_TestTime"
        },
        {
            "namespace": [
                "dbo"
            ],
            "name": "DIM_TestTable"
        }
    ],
    "next-page-token": null
}

Hämta tabell

Hämta tabellinformation för en viss tabell.

Förfrågan

GET <BaseUrl>/v1/<Prefix>/namespaces/<SchemaName>/tables/<TableName>
Authorization: Bearer <Token>

Svar

200 OK
{
    "metadata-location": "abfss://...@onelake.dfs.fabric.microsoft.com/.../Tables/DIM_TestTime/metadata/v3.metadata.json",
    "metadata": {
        "format-version": 2,
        "table-uuid": "...",
        "location": "abfss://...@onelake.dfs.fabric.microsoft.com/.../Tables/DIM_TestTime",
        "last-sequence-number": 2,
        "last-updated-ms": ...,
        "last-column-id": 4,
        "current-schema-id": 0,
        "schemas": [
            {
                "type": "struct",
                "schema-id": 0,
                "fields": [
                    {
                        "id": 1,
                        "name": "id",
                        "required": false,
                        "type": "int"
                    },
                    {
                        "id": 2,
                        "name": "name",
                        "required": false,
                        "type": "string"
                    },
                    {
                        "id": 3,
                        "name": "age",
                        "required": false,
                        "type": "int"
                    },
                    {
                        "id": 4,
                        "name": "i",
                        "required": false,
                        "type": "boolean"
                    }
                ]
            }
        ],
        "default-spec-id": 0,
        "partition-specs": [
            {
                "spec-id": 0,
                "fields": []
            }
        ],
        "last-partition-id": 999,
        "default-sort-order-id": 0,
        "sort-orders": [
            {
                "order-id": 0,
                "fields": []
            }
        ],
        "properties": {
            "schema.name-mapping.default": "[ {\n  \"field-id\" : 1,\n  \"names\" : [ \"id\" ]\n}, {\n  \"field-id\" : 2,\n  \"names\" : [ \"name\" ]\n}, {\n  \"field-id\" : 3,\n  \"names\" : [ \"age\" ]\n}, {\n  \"field-id\" : 4,\n  \"names\" : [ \"i\" ]\n} ]",
            "write.metadata.delete-after-commit.enabled": "true",
            "write.data.path": "abfs://...@onelake.dfs.fabric.microsoft.com/.../Tables/DIM_TestTime",
            "XTABLE_METADATA": "{\"lastInstantSynced\":\"...\",\"instantsToConsiderForNextSync\":[],\"version\":0,\"sourceTableFormat\":\"DELTA\",\"sourceIdentifier\":\"3\"}",
            "write.parquet.compression-codec": "zstd"
        },
        "current-snapshot-id": ...,
        "refs": {
            "main": {
                "snapshot-id": ...,
                "type": "branch"
            }
        },
        "snapshots": [
            {
                "sequence-number": 2,
                "snapshot-id": ...,
                "parent-snapshot-id": ...,
                "timestamp-ms": ...,
                "summary": {
                    "operation": "overwrite",
                    "XTABLE_METADATA": "{\"lastInstantSynced\":\"...\",\"instantsToConsiderForNextSync\":[],\"version\":0,\"sourceTableFormat\":\"DELTA\",\"sourceIdentifier\":\"3\"}",
                    "added-data-files": "1",
                    "deleted-data-files": "1",
                    "added-records": "1",
                    "deleted-records": "1",
                    "added-files-size": "2073",
                    "removed-files-size": "2046",
                    "changed-partition-count": "1",
                    "total-records": "6",
                    "total-files-size": "4187",
                    "total-data-files": "2",
                    "total-delete-files": "0",
                    "total-position-deletes": "0",
                    "total-equality-deletes": "0"
                },
                "manifest-list": "abfss://...@onelake.dfs.fabric.microsoft.com/.../Tables/DIM_TestTime/metadata/snap-....avro",
                "schema-id": 0
            }
        ],
        "statistics": [],
        "snapshot-log": [
            {
                "timestamp-ms": ...,
                "snapshot-id": ...
            }
        ],
        "metadata-log": [
            {
                "timestamp-ms": ...,
                "metadata-file": "abfss://...@onelake.dfs.fabric.microsoft.com/.../Tables/DIM_TestTime/metadata/v1.metadata.json"
            },
            {
                "timestamp-ms": ...,
                "metadata-file": "abfss://...@onelake.dfs.fabric.microsoft.com/.../Tables/DIM_TestTime/metadata/v2.metadata.json"
            }
        ]
    }
}

Läs mer om OneLake-tabell-API:er.
Läs mer om OneLake-tabell-API:er för Iceberg.
Konfigurera automatisk konvertering av Delta Lake till Iceberg-format.

Feedback

Var den här sidan till hjälp?

Last updated on 2025-10-27

Dela via

Komma igång med OneLake-tabell-API:er för Iceberg

Förutsättningar

Exempel på klientsnabbstart

PyIceberg

Snowflake

DuckDB

Exempel på begäranden och svar

Hämta konfiguration

Lista över scheman

Hämta schema

Lista tabeller

Hämta tabell

Relaterat innehåll

Feedback

Ytterligare resurser