Unity Catalog 中的密鑰

Important

這項功能目前處於 公開預覽版。

本頁說明如何在 Unity 目錄中建立、讀取、管理及管理秘密。 Unity 目錄秘密是一種可保護的物件，用來儲存敏感資料，例如密碼、權杖或 API 金鑰。 你的筆記本和工作可以參考這個秘密，而不會暴露程式碼中的值。

Unity Catalog 的密鑰使用三級命名空間（catalog.schema.secret），並可供附加至中繼存放區的所有工作區使用。 它們受 Unity Catalog 權限控管。 這讓你能將與其他資料資產相同的存取模式和稽核套用到你的秘密上。

Note

Unity Catalog 的秘密與工作區層級的 Azure Databricks 秘密不同，後者會組織成秘密範圍。 當您想要使用 Unity Catalog 權限來管理密鑰，並以三級命名空間加以引用時，請使用 Unity Catalog 密鑰。

Unity Catalog 密鑰的運作方式

Unity Catalog 密碼是位於結構描述下的可保護物件，其完全限定名稱為 catalog.schema.secret。 與其他 Unity 目錄可保護物件一樣，秘密支援從目錄與結構中繼承特權。 欲了解更多關於可保護物件與繼承的資訊，請參閱 Unity 目錄可安全物件參考。

你可以以下列方式使用 Unity Catalog 祕密：

  • 以程式碼取出該值。 具有 READ SECRET 存取權限的使用者，可以使用 dbutils 或 Unity Catalog REST API，從筆記本和作業中擷取秘密。 他們可以用它與外部系統進行認證，或加密解密資料。
  • 參照 Unity Catalog 物件中的值。 Unity 目錄物件，例如 Unity 目錄連線，可以以名稱參照秘密，讓整合者能使用該秘密，而不會授權使用者存取該值。 根據物件的不同，引用祕密需要 REFERENCE SECRET 或 READ SECRET。

Azure Databricks 會加密儲存 Unity 目錄的秘密值，並套用秘密遮蔽以減少輸出與日誌中的意外暴露。 要輪換秘密，請定期在介面或使用 Unity Catalog REST API 更新其值。

Unity Catalog 機密的權限

以下特權適用於機密。 你可以在目錄、架構或個別秘密層級授予它們，且它們會遵循 Unity 目錄的繼承權限。

特權 描述
CREATE SECRET 允許使用者在結構中建立秘密。 在目錄或架構層級獲得。
READ SECRET 允許使用者取得秘密值。
WRITE SECRET 允許使用者更新秘密值。
REFERENCE SECRET 允許使用者在不存取該值的情況下，參考例如來自 Unity 目錄連線的秘密。

若要在結構描述中建立秘密，使用者必須具有 USE CATALOG 權限，且必須是該結構描述的擁有者，或對該結構描述具有 CREATE SECRET 和 USE SCHEMA 權限。 欲了解如何授予權限，請參閱 Unity 目錄中的權限管理。

開始之前

要使用 Unity 目錄的秘密，您必須符合以下條件：

  • 必須為 Unity 目錄啟用此工作區。 入門介紹請參見《 什麼是 Unity 目錄？》。
  • 你必須從已啟用 Unity Catalog 的運算資源存取機密資料。 Azure Databricks 建議以下其中一項：
    • 使用環境版本 4 或以上的無伺服器作業和筆記本。
    • 經典運算，採用 標準存取模式 ，運行 Databricks Runtime 17.3 LTS 或以上版本。
  • 若要取得帶有 dbutils的秘密，運算必須執行 Databricks Runtime 17.3 LTS 或以上版本，或無伺服器環境版本 4 或以上。

建立密碼

建立秘密時，你必須具有 USE CATALOG 權限，且擁有該結構描述，或者在該結構描述上具有 CREATE SECRET 和 USE SCHEMA 權限。 請參見 Unity 目錄秘密的權限。

目錄檢視器

  1. 在你的 Azure Databricks 工作區中，點選目錄以開啟目錄總管。
  2. 前往您要建立密鑰的結構描述。
  3. 按一下 建立 > 密鑰。
  4. 輸入 一個名字 和 數值。 可選擇性地加上 註解 和 有效期限。 如果秘密過期，目錄瀏覽器會顯示警告。
  5. 點擊 建立。

REST API

使用 /api/2.1/unity-catalog/secrets 端點執行以下 cURL 指令：

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_name": "main",
    "schema_name": "default",
    "name": "example_secret",
    "value": "your_secret_value",
    "comment": "your secret description"
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

閱讀秘密

若要讀取祕密值，您必須對該祕密或其父層目錄或結構描述具有 READ SECRET 權限。

秘密工具程式 （dbutils.secrets）

Azure Databricks 建議使用 dbutils 來讀取祕密，因為它會套用祕密隱碼處理。 此選項需 Databricks Runtime 17.3 LTS 或以上版本，或無伺服器環境版本 4 或以上。

# Read a specific secret
my_secret = dbutils.secrets.get(catalog="main", schema="default", key="example_secret")

欲了解更多資訊，請參閱秘密工具（dbutils.secrets）。

REST API

Warning

使用 Unity Catalog REST API 取得的秘密值不受秘密塗黑限制，但存取權限仍會記錄在稽核日誌中。 Azure Databricks 改為建議使用 dbutils。

要回傳該值，請在回應中設定 include_value=true 並讀取 effective_value 該欄位：

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "include_value=true" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

管理機密的權限

在目錄或綱要層級授與 CREATE SECRET，以控制誰可以建立密鑰。 授予 READ SECRET、 WRITE SECRET，或 REFERENCE SECRET 在目錄、結構或個別秘密層級控制存取權限。 特權繼承適用。 欲了解更多關於授予與撤銷權限的資訊，請參閱 Unity 目錄中的權限管理。

賦予創造秘密的能力

目錄檢視器

  1. 在目錄總管中，前往該結構描述。

  2. 按一下權限索引標籤。

  3. 請按一下 授權。

  4. 選擇要授權存取的主體，然後選擇 建立秘密。

    如果某個主體沒有 USE SCHEMA，系統會顯示警告，提示你授與它。 USE SCHEMA 同時也必須在結構中建立祕密。

  5. 按一下 [確認]。

SQL

GRANT CREATE SECRET, USE SCHEMA ON SCHEMA main.default TO `user@example.com`;

REST API

使用 /api/2.1/unity-catalog/permissions/schema/{schema_name} 端點執行以下 cURL 指令：

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["CREATE_SECRET", "READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/schema/{schema_name}"

授權存取秘密

目錄檢視器

  1. 在 Catalog Explorer 中，前往該密碼，然後按一下它。
  2. 按一下權限索引標籤。
  3. 請按一下 授權。
  4. 選擇要授予的主體和權限，然後點擊 確認。

SQL

GRANT READ SECRET ON SECRET main.default.example_secret TO `user@example.com`;

REST API

使用 /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} 端點執行以下 cURL 指令：

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret}"

列出、更新及刪除秘密

列出機密

目錄檢視器

  1. 在目錄總管中，前往結構描述。
  2. 在 概覽 窗格中，點選 秘密 以查看結構中的所有秘密。

秘密工具程式 （dbutils.secrets）

# List all secrets in a schema
all_secrets = dbutils.secrets.list(catalog="main", schema="default")

REST API

清單請求用 page_size 來控制結果數量：

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

更新機密

要更新秘密值，你必須在秘密上有 WRITE SECRET 。

目錄檢視器

  1. 在目錄總管中，前往結構描述，然後在 概觀 窗格中按一下 密碼。
  2. 點選密鑰以更新。
  3. 在右上角，點選烤肉串選單（直線點），選擇 編輯。
  4. 輸入新的數值或到期日，然後點擊 確認。

REST API

更新請求需要該 update_mask 參數。 只有兩個 update_mask 欄位及請求主體中包含的欄位會被更新：

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value": "new_secret_value"}' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret?update_mask=*"

刪除秘密

目錄檢視器

  1. 在 Catalog Explorer 中，前往該結構描述，然後在 Overview 窗格中按一下 Secrets。
  2. 點選該密碼以刪除。
  3. 在右上角，點選烤肉選單（直線點），選擇 刪除。
  4. 輸入秘密的全名，然後點擊 刪除。

REST API

curl -X DELETE \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Unity Catalog 密碼的稽核事件

system.access.audit 系統資料表會記錄與 Unity Catalog 密鑰相關的事件。 例如，要查看特定日期所有使用者的秘密事件，請執行以下查詢：

SELECT * FROM system.access.audit
WHERE
  user_identity.email = "user@example.com"
  AND event_date = "2026-02-20"
  AND service_name = "unityCatalog"
  AND action_name LIKE "%Secret%";

欲了解更多關於稽核日誌的資訊，請參閱 稽核日誌系統表格參考資料。

用客戶管理的金鑰加密秘密值

預設情況下，Azure Databricks 會用 Databricks 管理的金鑰加密秘密值。 你也可以改用客戶管理金鑰（CMK）。 如果你啟用 CMK 加密的管理目錄功能，並將 CMK 設定附加到你的帳號，Azure Databricks 會用 CMK 來加密秘密值。 欲了解更多資訊，請參閱 Unity 目錄的客戶管理金鑰。

Limitations

Unity Catalog 密鑰有下列限制：

  • 沒有 SQL 倉庫。 SQL 倉儲不支援 Unity Catalog 密鑰。 它們需要在已啟用 Unity Catalog 的運算資源上使用 Databricks Runtime 17.3 LTS 或更新版本，或使用無伺服器。
  • 沒有全球性的發現。 Unity 目錄的秘密不會出現在全域搜尋中。
  • 沒有瀏覽權限支援。套用於目錄的 BROWSE 不適用於 Unity Catalog 密鑰。 若要讓密鑰可被發現，請在個別密鑰或其結構描述上授與 READ SECRET 或 REFERENCE SECRET。
  • 沒有初始化腳本。 你不能在全域或叢集初始化腳本中使用 Unity 目錄的秘密。 Azure Databricks 建議盡可能使用專用功能而非初始化腳本。
  • 沒有資訊圖式。 祕密的資訊結構表尚未提供。 使用目錄總管或 REST API 進行發現。
  • dbutils 執行時範圍。 dbutils 擷取功能支援由 Databricks Runtime 支援的筆記本與作業。 非 Databricks 執行環境，如遠端開發或編譯後的 JAR 執行模式，則不被支援。
  • OAuth API 範圍。 Unity 目錄的秘密 API 僅能透過 unity-catalog OAuth API 範圍存取。 僅將 secrets API 範圍用於工作區層級的 Azure Databricks 祕密。
  • 配額限制。 每個結構最多可有 100 個秘密，每個 metastore 最多可有 1,000 個秘密。
  • Last updated on