หมายเหตุ
การเข้าถึงหน้านี้ต้องได้รับการอนุญาต คุณสามารถลอง ลงชื่อเข้าใช้หรือเปลี่ยนไดเรกทอรีได้
การเข้าถึงหน้านี้ต้องได้รับการอนุญาต คุณสามารถลองเปลี่ยนไดเรกทอรีได้
OneLake มีจุดสิ้นสุด REST API สําหรับการโต้ตอบกับตารางใน Microsoft Fabric จุดสิ้นสุดนี้รองรับการดําเนินการเมตาดาต้าแบบอ่านอย่างเดียวสําหรับตาราง Apache Iceberg ใน Fabric การดําเนินการเหล่านี้เข้ากันได้กับมาตรฐานแบบเปิดของ Iceberg REST Catalog (IRC) API
สําคัญ
คุณลักษณะนี้อยู่ใน แสดงตัวอย่าง
ข้อกําหนดเบื้องต้น
เรียนรู้เพิ่มเติมเกี่ยวกับ API ตาราง OneLake สําหรับ Iceberg และอย่าลืมตรวจสอบข้อมูลเบื้องต้น
ตัวอย่างการเริ่มต้นใช้งานด่วนของลูกค้า
ตรวจสอบตัวอย่างเหล่านี้เพื่อเรียนรู้วิธีตั้งค่าไคลเอ็นต์หรือไลบรารี Iceberg REST Catalog (IRC) ที่มีอยู่เพื่อใช้กับจุดสิ้นสุดตาราง OneLake ใหม่
ไพไอซ์เบิร์ก
ใช้โค้ด Python ตัวอย่างต่อไปนี้เพื่อกําหนดค่า PyIceberg เพื่อใช้ตําแหน่งข้อมูล API ตาราง OneLake จากนั้นแสดงรายการ Schema และตารางภายในรายการข้อมูล
รหัสนี้ถือว่ามี AzureCredential เริ่มต้นที่พร้อมใช้งานสําหรับผู้ใช้ที่ลงชื่อเข้าใช้ในปัจจุบัน หรือคุณสามารถใช้ ไลบรารี MSAL Python เพื่อรับโทเค็น
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
ใช้โค้ดตัวอย่างต่อไปนี้เพื่อสร้าง ฐานข้อมูลที่เชื่อมโยงกับแค็ตตาล็อก ใหม่ใน Snowflake ฐานข้อมูลนี้จะรวม Schema และตารางใดๆ ที่พบภายในรายการข้อมูล Fabric ที่เชื่อมต่อโดยอัตโนมัติ สิ่งนี้เกี่ยวข้องกับการสร้างการรวมแค็ตตาล็อกวอลุ่มภายนอก และฐานข้อมูล
-- 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;
การตอบสนองของ DESC EXTERNAL VOLUME จะส่งคืนข้อมูลเมตาเกี่ยวกับโวลุ่มภายนอก ซึ่งรวมถึง:
-
AZURE_CONSENT_URLซึ่งเป็นหน้าคําขอสิทธิ์ที่ต้องปฏิบัติตามหากยังไม่ได้ดําเนินการสําหรับผู้เช่าของคุณ -
AZURE_MULTI_TENANT_APP_NAMEซึ่งเป็นชื่อของแอปพลิเคชันไคลเอ็นต์ Snowflake ที่ต้องการเข้าถึงรายการข้อมูล ตรวจสอบให้แน่ใจว่าได้ให้สิทธิ์เข้าถึงรายการข้อมูลเพื่อให้ Snowflake สามารถอ่านเนื้อหาของตารางได้
-- 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";
ดั๊กดีบี
ใช้โค้ด Python ตัวอย่างต่อไปนี้เพื่อกําหนดค่า DuckDB ให้แสดงรายการ Schema และตารางภายในรายการข้อมูล
รหัสนี้ถือว่ามีค่าเริ่มต้น AzureCredential ที่พร้อมใช้งานสําหรับผู้ใช้ที่ลงชื่อเข้าใช้ในปัจจุบัน หรือคุณสามารถใช้ ไลบรารี MSAL Python เพื่อรับโทเค็น
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())
ตัวอย่างคําขอและการตอบกลับ
ตัวอย่างคําขอและการตอบสนองเหล่านี้แสดงให้เห็นถึงการใช้การดําเนินการ Iceberg REST Catalog (IRC) ที่รองรับในปัจจุบันที่ตําแหน่งข้อมูล API ตาราง OneLake สําหรับข้อมูลเพิ่มเติมเกี่ยวกับ IRC ให้ดูที่ข้อมูลจําเพาะมาตรฐานแบบเปิด
สําหรับการดําเนินการแต่ละรายการเหล่านี้:
-
<BaseUrl>คือhttps://onelake.table.fabric.microsoft.com/iceberg -
<Warehouse>คือ<Workspace>/<DataItem>ซึ่งสามารถ:-
<WorkspaceID>/<DataItemID>เช่น12345678-abcd-4fbd-9e50-3937d8eb1915/98765432-dcba-4209-8ac2-0821c7f8bd91 -
<WorkspaceName>/<DataItemName>.<DataItemType>MyWorkspace/MyItem.Lakehouseเช่น ตราบใดที่ทั้งสองชื่อไม่มีอักขระพิเศษ
-
-
<Prefix>ถูกส่งคืนโดยการเรียกการกําหนดค่า Get และค่ามักจะเหมือนกับ<Warehouse> -
<Token>คือค่าโทเค็นการเข้าถึงที่ส่งคืนโดย Entra ID เมื่อตรวจสอบสิทธิ์สําเร็จ
รับการกําหนดค่า
แสดงรายการการตั้งค่าคอนฟิกูเรชันแค็ตตาล็อก Iceberg
ขอร้อง
GET <BaseUrl>/v1/config?warehouse=<Warehouse> Authorization: Bearer <Token>การตอบสนอง
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>" } }รายการสคีมา
แสดงรายการ Schema ภายในรายการข้อมูล Fabric
ขอร้อง
GET <BaseUrl>/v1/<Prefix>/namespaces Authorization: Bearer <Token>การตอบสนอง
200 OK { "namespaces": [ [ "dbo" ] ], "next-page-token": null }
รับ Schema
รับรายละเอียด Schema สําหรับ Schema ที่กําหนด
ขอร้อง
GET <BaseUrl>/v1/<Prefix>/namespaces/<SchemaName> Authorization: Bearer <Token>การตอบสนอง
200 OK { "namespace": [ "dbo" ], "properties": { "location": "d892007b-3216-424a-a339-f3dca61335aa/40ef140a-8542-4f4c-baf2-0f8127fd59c8/Tables/dbo" } }
แสดงรายการตาราง
แสดงรายการตารางภายในสคีมาที่กําหนด
ขอร้อง
GET <BaseUrl>/v1/<Prefix>/namespaces/<SchemaName>/tables Authorization: Bearer <Token>การตอบสนอง
200 OK { "identifiers": [ { "namespace": [ "dbo" ], "name": "DIM_TestTime" }, { "namespace": [ "dbo" ], "name": "DIM_TestTable" } ], "next-page-token": null }
รับตาราง
รับรายละเอียดตารางสําหรับตารางที่กําหนด
ขอร้อง
GET <BaseUrl>/v1/<Prefix>/namespaces/<SchemaName>/tables/<TableName> Authorization: Bearer <Token>การตอบสนอง
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" } ] } }
เนื้อหาที่เกี่ยวข้อง
- เรียนรู้เพิ่มเติมเกี่ยวกับ API ตาราง OneLake
- เรียนรู้เพิ่มเติมเกี่ยวกับ API ตาราง OneLake สําหรับ Iceberg
- ตั้งค่าการแปลงรูปแบบ Delta Lake เป็น Iceberg อัตโนมัติ