追加のテーブルメタデータの読み書き(プレビュー)

OneLakeの追加テーブルメタデータAPIを使って、テーブルとその列の説明やキー・値タグを読み書きしてください。 このAPIは、Iceberg REST CatalogやUnity Catalog互換ルートではなく、共通のRESTルートを使用します。

例えば、テーブルのビジネス目的を説明する説明を追加し、そのテーブルに所有者チームをタグ付けし、カラムの解釈方法を説明します。 これらの操作は、テーブルの行ではなく記述メタデータを扱います。 行を取得するには、 OneLakeのテーブルリードAPIを使用します。

前提条件

• 共有テーブルAPIの 前提条件と認証ステップを完了してください。
• ターゲットテーブルのワークスペースID、アイテムID、スキーマ名、テーブル名を特定します。
• 説明したい、タグ付けしたい既存の列を特定しましょう。
• ターゲットテーブルのメタデータの読み書きに必要な権限を持つアイデンティティを使いましょう。

例では、salesスキーマ内のdboというテーブルと、既存の列customer_idを使用します。 これらの名前を自分のテーブルの名前に置き換えてください。

エンドポイントとオペレーション

以下の基本URLを使用してください:

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

両方の操作は同じルートを使用しています:

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

<WorkspaceID>と<ItemID>にはGUIDを使いましょう。 スキーマ名とテーブル名を個別のパスセグメントとしてURLエンコードします。 https://storage.azure.com/ヘッダーに、Authorization: Bearer <Token>オーディエンス用の Microsoft Entra ID アクセス トークンを含めます。 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"
      }
    }
  ]
}

応答の値、列名、フィールドはターゲットテーブルとそのメタデータに依存します。 契約書にはすべてのフィールドが揃っている必要はありません。

追加メタデータを書き込む

テーブルの追加メタデータを置き換えるためにJSONボディ付きの POST リクエストを送信します。

この例では、テーブルの説明とタグ、さらに 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 CLIでローカルでサインインするなど、対応可能なAzure Identity認証方法を設定してください。

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テーブルショートカットの場合は、ショートカットのワークスペース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

ショートカットを通じてメタデータを更新するには、同じ URL に POST 要求を送信してください。 置換セマンティクスはターゲットテーブルにも適用されます。ショートカットを通じた説明専用リクエストは、ターゲットテーブルの既存のタグや列メタデータを削除します。 保持したいメタデータを保持するために、読み取り-変更-書き込みシーケンス を使いましょう。

アクセスにはショートカットパスとターゲットテーブルパスの両方の操作権限が必要です。 パススルーショートカットの場合、アイデンティティは両方の権限セットが必要です。ターゲットテーブル権限だけでは不十分です。 委任されたショートカットの場合、ターゲットアクセスは設定された接続 ID を使用します。 詳細は OneLakeショートカットセキュリティをご覧ください。

エラーを処理し、リクエストを診断する

リクエストが失敗した場合は、HTTPステータスとJSONエラーレスポンスを確認してください。 エラー契約の形は以下の通りです。コードやメッセージのプレースホルダーは特定のサービスエラー値ではありません。

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

errorオブジェクトにはtargetやdetails配列も含めることができます。 各詳細には code と messageが含まれ、 targetを含めることもできます。 契約書には、オペレーション固有のエラーコードやステータスコードは記載されていません。

診断のために、GUIDを含むオプションの x-ms-root-activity-id ヘッダーを送信できます。 リクエストのトラブルシューティング時に x-ms-root-activity-id 応答ヘッダーを記録してください。 ベアラートークンをログに記録しないでください。

関連するコンテンツ

• OneLakeテーブルAPIの概要。
• OneLake IcebergメタデータAPIです。
• OneLake DeltaメタデータAPIです。
• OneLakeのショートカット。
• OneLakeのテーブルデータを読みましょう。