อ่านและเขียนเมตาดาต้าตารางเพิ่มเติม (ตัวอย่าง)

ใช้ OneLake additional table metadata API เพื่ออ่านและเขียนคําอธิบายและแท็กคีย์-ค่าสําหรับตารางและคอลัมน์ของมัน API นี้ใช้เส้นทาง REST ทั่วไปแทนที่จะใช้เส้นทางที่เข้ากันได้กับ Iceberg REST Catalog หรือ Unity Catalog

ตัวอย่างเช่น เพิ่มคําอธิบายที่อธิบายวัตถุประสงค์ทางธุรกิจของตาราง แท็กตารางด้วยทีมเจ้าของ และอธิบายวิธีการตีความคอลัมน์ การดําเนินการเหล่านี้ทํางานกับเมตาดาต้าเชิงพรรณนา ไม่ใช่แถวของตาราง หากต้องการดึงแถว ให้ใช้ OneLake table read API

ข้อกำหนดเบื้องต้น

• ดําเนินการตามข้อกําหนดเบื้องต้นของ shared table API และขั้นตอนการตรวจสอบสิทธิ์
• ระบุ Workspace ID, Item ID, ชื่อสคีมา และชื่อตารางสําหรับตารางเป้าหมายของคุณ
• ระบุคอลัมน์ที่มีอยู่ที่คุณต้องการอธิบายหรือแท็ก
• ใช้ตัวตนที่มีสิทธิ์ที่จําเป็นสําหรับการอ่านหรือเขียนเมตาดาต้าสําหรับตารางเป้าหมาย

ตัวอย่างใช้ตารางที่ตั้งชื่อ sales ใน dbo สคีมาและคอลัมน์ที่มีอยู่ชื่อ customer_id. แทนที่ชื่อเหล่านี้ด้วยชื่อสําหรับตารางของคุณ

จุดสิ้นสุดและการดําเนินงาน

ใช้ URL ฐานดังต่อไปนี้:

https://onelake.table.fabric.microsoft.com

ทั้งสองปฏิบัติการใช้เส้นทางเดียวกัน:

/common/v1/<WorkspaceID>/<ItemID>/schemas/<SchemaName>/tables/<TableName>/additionalMetadata

ใช้ GUID สําหรับ <WorkspaceID> และ<ItemID> เข้ารหัส URL สคีมาและชื่อตารางเป็นส่วนเส้นทางแยก รวมAuthorization: Bearer <Token>ส่วนหัวที่มีโทเค็นการเข้าถึง Microsoft Entra ID สําหรับhttps://storage.azure.com/กลุ่มเป้าหมาย สําหรับ POST, รวมถึง Content-Type: application/json.

คําอธิบายและแท็กที่รองรับ

ใช้ฟิลด์เหล่านี้ในคําขอ POST :

อ่านข้อมูลเมตาเพิ่มเติม

ส่งคําขอ GET เพื่อรับข้อมูลเมตาระดับตารางและระดับคอลัมน์

GET https://onelake.table.fabric.microsoft.com/common/v1/<WorkspaceID>/<ItemID>/schemas/dbo/tables/sales/additionalMetadata
Authorization: Bearer <Token>
Accept: application/json

คําขอที่สําเร็จจะส่งคืน 200 OK. JSON ต่อไปนี้แสดงรูปแบบการตอบกลับ:

{
  "description": "Sales transactions.",
  "tags": {
    "domain": "sales",
    "owner": "sales-analytics"
  },
  "columns": [
    {
      "columnName": "customer_id",
      "description": "Customer identifier.",
      "tags": {
        "role": "customer-key"
      }
    }
  ]
}

ค่า ชื่อคอลัมน์ และฟิลด์ในคําตอบของคุณขึ้นอยู่กับตารางเป้าหมายและเมตาดาต้าของมัน สัญญาไม่ได้กําหนดให้ทุกฟิลด์ต้องปรากฏ

เขียนข้อมูลเมตาเพิ่มเติม

ส่งคําขอ POST พร้อม JSON body เพื่อแทนที่ข้อมูลเมตาเพิ่มเติมของตาราง

ตัวอย่างนี้ตั้งค่าคําอธิบายตารางและแท็ก รวมถึงคําอธิบายและแท็กสําหรับcustomer_id มันระบุคอลัมน์โดยใช้ columnName.

POST https://onelake.table.fabric.microsoft.com/common/v1/<WorkspaceID>/<ItemID>/schemas/dbo/tables/sales/additionalMetadata
Authorization: Bearer <Token>
Content-Type: application/json
Accept: application/json

เนื้อความของการร้องขอ:

{
  "description": "Sales transactions used for revenue reporting.",
  "tags": {
    "domain": "sales",
    "owner": "sales-analytics"
  },
  "columns": [
    {
      "columnName": "customer_id",
      "description": "Identifier of the customer associated with the sale.",
      "tags": {
        "role": "customer-key"
      }
    }
  ]
}

คําขอที่สําเร็จจะส่งคืน 200 OK ด้วยการตอบกลับเมตาดาต้าเพิ่มเติม ตัวอย่างเช่น:

{
  "description": "Sales transactions used for revenue reporting.",
  "tags": {
    "domain": "sales",
    "owner": "sales-analytics"
  },
  "columns": [
    {
      "columnName": "customer_id",
      "description": "Identifier of the customer associated with the sale.",
      "tags": {
        "role": "customer-key"
      }
    }
  ]
}

ส่งคําขออีกครั้ง GET เพื่อตรวจสอบเมตาดาต้าหลังจากเขียน

รักษาข้อมูลเมตาที่มีอยู่

หากต้องการเปลี่ยนคําอธิบายหรือแท็กที่เลือกโดยไม่ลบข้อมูลเมตาอื่น ๆ ให้ใช้ลําดับอ่าน-แก้ไข-เขียน:

1. ส่งคําขอ GET เพื่ออ่านข้อมูลเมตาเพิ่มเติมปัจจุบัน
2. เปลี่ยนคําอธิบายหรือแท็กที่คุณต้องการอัปเดตในเมตาดาต้าที่ส่งคืน เก็บฟิลด์อื่น ๆ กุญแจแท็ก และรายการคอลัมน์ที่คุณต้องการเก็บไว้
3. ส่งข้อมูลเมตาที่อัปเดตทั้งหมดใน POST คําขอ
4. ส่งคําขออีกครั้ง GET เพื่อยืนยันผลลัพธ์

ประสานการอัปเดตเมตาดาต้าพร้อมกันเพื่อไม่ให้เกิดการเขียนซ้ําระหว่างคุณ GET กับ POST คําขอ

อ่านและเขียนเมตาดาต้าด้วย Python

ตัวอย่างต่อไปนี้จะตรวจสอบความถูกต้องด้วย Microsoft Entra ID อ่านข้อมูลเมตาปัจจุบัน อัปเดตคําอธิบายและแท็กที่เลือกโดยยังคงรักษาข้อมูลเมตาอื่น ๆ ไว้ และอ่านข้อมูลเมตาอีกครั้ง มันไม่ได้เรียกใช้ API แคตตาล็อกเฉพาะรูปแบบหรือขอข้อมูลรับรองการจัดเก็บข้อมูล

ติดตั้งการพึ่งพา:

python -m pip install azure-identity requests

กําหนดค่าวิธีการยืนยันตัวตน Azure Identity ที่รองรับ เช่น ลงชื่อเข้าใช้แบบโลคอลด้วย Azure CLI ก่อนที่จะรันตัวอย่าง

import json
from urllib.parse import quote

import requests
from azure.identity import DefaultAzureCredential

workspace_id = "<WorkspaceID>"
item_id = "<ItemID>"
schema_name = "dbo"
table_name = "sales"
column_name = "customer_id"

url = (
    "https://onelake.table.fabric.microsoft.com/common/v1/"
    f"{workspace_id}/{item_id}/schemas/{quote(schema_name, safe='')}/"
    f"tables/{quote(table_name, safe='')}/additionalMetadata"
)

with DefaultAzureCredential() as credential, requests.Session() as session:
    session.headers.update({"Accept": "application/json"})

    def request_metadata(method, **kwargs):
        token = credential.get_token("https://storage.azure.com/.default")
        response = session.request(
            method,
            url,
            headers={"Authorization": f"Bearer {token.token}"},
            timeout=30,
            **kwargs,
        )
        response.raise_for_status()
        return response.json()

    metadata = request_metadata("GET")
    print("Before:")
    print(json.dumps(metadata, indent=2))

    metadata["description"] = "Sales transactions used for revenue reporting."
    metadata.setdefault("tags", {}).update(
        {"domain": "sales", "owner": "sales-analytics"}
    )

    columns = metadata.setdefault("columns", [])
    column = next(
        (entry for entry in columns if entry.get("columnName") == column_name),
        None,
    )
    if column is None:
        column = {"columnName": column_name}
        columns.append(column)

    column["description"] = "Identifier of the customer associated with the sale."
    column.setdefault("tags", {}).update({"role": "customer-key"})

    print("Write response:")
    print(json.dumps(request_metadata("POST", json=metadata), indent=2))

    print("After:")
    print(json.dumps(request_metadata("GET"), indent=2))

อาร์กิวเมนต์นี้ json ตั้งค่าส่วนหัวของ Content-Type: application/json คําขอ ตัวอย่างจะยกข้อยกเว้นสําหรับการตอบกลับ HTTP ที่ไม่สําเร็จ แทนที่จะถือว่าเป็นการอัปเดตเมตาดาต้าที่สําเร็จ

ทํางานกับเมตาดาต้าผ่านทางลัด OneLake

สําหรับทางลัดภายในตาราง OneLake ให้ใช้ Workspace ID, ID รายการ, ชื่อสคีมา และชื่อตารางในเส้นทางเมตาดาต้าเพิ่มเติมเดียวกัน การดําเนินการจะทํางานกับเมตาดาต้าของตารางเป้าหมาย ไม่ใช่สําเนาเมตาดาต้าแยกสําหรับทางลัด:

• GET คืนค่าเมตาดาต้าเพิ่มเติมของตารางเป้าหมาย รวมถึงคําอธิบายและแท็ก
• POST แทนที่เมตาดาต้าเพิ่มเติมของตารางเป้าหมาย การเปลี่ยนแปลงจะเห็นได้เมื่อคุณอ่านข้อมูลเมตาผ่านทางลัดหรือตารางเป้าหมาย

ตัวอย่างเช่น หากทางลัดชื่อ sales_shortcut ชี้ไปที่ sales, อ่านข้อมูลเมตาของตารางต้นทางผ่านทางลัดโดยใช้คําขอนี้:

GET https://onelake.table.fabric.microsoft.com/common/v1/<WorkspaceID>/<ItemID>/schemas/dbo/tables/sales_shortcut/additionalMetadata
Authorization: Bearer <token>
Accept: application/json

หากต้องการอัปเดตเมตาดาต้าผ่านทางลัด ให้ส่ง POST คําขอไปยัง URL เดียวกัน ความหมายของการแทนที่นี้ยังใช้กับตารางเป้าหมายด้วย: การร้องขอเฉพาะคําอธิบายผ่านทางลัดจะลบแท็กและข้อมูลเมตาของคอลัมน์ที่มีอยู่ของตารางเป้าหมาย ใช้ ลําดับอ่าน-แก้ไข-เขียน เพื่อเก็บข้อมูลเมตาที่คุณต้องการเก็บไว้

การเข้าถึงต้องการสิทธิ์สําหรับการดําเนินการทั้งบนเส้นทางทางลัดและเส้นทางตารางเป้าหมาย สําหรับทางลัดแบบ passthrough ตัวตนของคุณต้องมีทั้งสองชุดสิทธิ์;สิทธิ์ในตารางเป้าหมายเพียงอย่างเดียวไม่เพียงพอ สําหรับทางลัดที่ได้รับมอบหมาย การเข้าถึงเป้าหมายจะใช้ตัวตนการเชื่อมต่อที่กําหนดค่าไว้ สําหรับรายละเอียด ดูที่ OneLake shortcut security

จัดการข้อผิดพลาดและวินิจฉัยคําขอ

สําหรับคําขอที่ไม่สําเร็จ ให้ตรวจสอบสถานะ HTTP และการตอบสนองข้อผิดพลาด JSON สัญญาข้อผิดพลาดมีรูปร่างดังนี้;โค้ดและตัวแทนข้อความไม่ใช่ค่าข้อผิดพลาดเฉพาะของบริการ:

{
  "error": {
    "code": "<ErrorCode>",
    "message": "<ErrorMessage>"
  }
}

วัตถุนี้ error ยังสามารถประกอบด้วย a target และ array details ได้ด้วย รายละเอียดแต่ละชิ้นประกอบด้วย และ codemessage, และสามารถรวม target. สัญญาไม่ได้ระบุรหัสข้อผิดพลาดเฉพาะของปฏิบัติการหรือรหัสสถานะ

สําหรับการวินิจฉัย คุณสามารถส่งส่วนหัวเสริม x-ms-root-activity-id ที่มี GUID ได้ บันทึก x-ms-root-activity-id ส่วนหัวการตอบกลับเมื่อคุณแก้ไขปัญหาคําขอ อย่าบันทึกโทเคนผู้ถือ

เนื้อหาที่เกี่ยวข้อง

• ภาพรวมของ OneLake table APIs
• API เมตาดาต้า OneLake Iceberg
• OneLake Delta metadata API
• ทางลัด OneLake
• อ่านข้อมูลตาราง OneLake