Unity Catalog 中的密鑰

本頁說明如何在 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，從筆記本和作業中擷取秘密。他們可以用它與外部系統進行認證，或加密解密資料。
在有工作階段範圍的 Python 或 Scala UDF 中使用該值。 請參見會話範圍的 UDF。
在 Unity Catalog 的 Python UDF 中使用這個值。 標量或批次 UDF 會在其 SECRETS 子句中宣告各個秘密。請參考 Python UDFs。
在 Unity Catalog 的 Scala UDF 中使用此值。 純量 UDF 會在其 SECRETS 子句中宣告每個祕密值。請參閱 Scala UDFs。

關於不同 UDF 類型的要求與權限行為，請參見 UDF 要求與權限。

UDF 可以使用 Azure Databricks 管理的秘密值，或由外部秘密管理器支援的秘密值。請參見 Unity 目錄中的外部秘密。

UDF 的要求與權限

會話範圍與 Unity 目錄 UDF 的需求與權限行為有所不同。

會話範圍的 UDF

工作階段範圍的 Python UDF 會使用 databricks.secrets.get() 擷取秘密，而工作階段範圍的 Scala UDF 會使用 com.databricks.Secrets.get() 擷取秘密。秘密存取則是利用呼叫者的權限。

秘密存取的計算需求依 UDF 語言而定：

在無伺服器運算中，筆記本或工作會話必須使用環境版本 6 或以上以支援 Python 和 Scala UDF。
在經典運算中，會話範圍的 Python UDF 需要 Databricks Runtime 19 或以上的標準或專用存取模式。
在傳統運算中，工作階段範圍的 Scala UDF 需要 Databricks Runtime 19 或以上版本，且使用標準存取模式。

Unity 目錄 UDF

純量和批次 Unity Catalog Python UDF，以及純量 Unity Catalog Scala UDF，會在 SECRETS 子句中宣告密鑰，且必須明確將 environment_version 設為 6 或更高。它們支援無伺服器運算、無伺服器 SQL 倉庫，以及經典運算，運行 Databricks Runtime 19 或以上，並以標準存取模式運行。

Pro SQL 倉儲支援使用密碼的 Unity Catalog 純量和批次 Python UDF。使用秘密的 Unity Catalog Scala UDF 不受 Pro SQL 倉庫支援。

若要建立或取代宣告秘密的 UDF，執行該陳述式的主體必須對該秘密具有 USE CATALOG，並對其父目錄和結構描述具有 USE SCHEMA 和 READ SECRET。執行時，UDF 會使用目前函式擁有者的權限。呼叫者需要通常的功能權限，包括 EXECUTE，但不需直接存取宣告的秘密。若函式擁有者失去讀取已宣告密鑰的權限，UDF 就會失敗。

在專用計算中使用啟用秘密的 UDF 來進行欄位遮罩

你無法直接在專用存取模式運算資源上叫用使用 SECRETS 子句的 Unity Catalog Python 或 Scala UDF。不過，您可以建立一個 Unity Catalog SQL 函式，用來呼叫支援 secret 的 UDF，並將該 SQL 函式作為屬性式存取控制（ABAC）的欄位遮罩。當查詢在專用運算上執行時，Azure Databricks 會將欄位遮罩的強制執行委派給無伺服器運算。此例外僅在強制執行欄位遮罩時生效;它不會在專用運算中直接調用已啟用秘密的 UDF。請參見不支援的計算版本。

Warning

只在 UDF 實作中使用秘密值。請勿回傳秘密值，也不要將其納入 UDF 結果中。秘密塗黑有助於減少錯誤與日誌中的意外暴露，但並不能阻止 UDF 程式碼在查詢結果中揭露機密內容。

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

Unity Catalog 機密的權限

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

特權	描述
`CREATE SECRET`	允許使用者在結構中建立秘密。在目錄或架構層級獲得。
`READ SECRET`	允許使用者取得秘密值。
`WRITE SECRET`	允許使用者更新秘密值。
`REFERENCE SECRET`	允許使用者在不取得該值的情況下參考祕密。

若要在結構描述中建立秘密，使用者必須具有 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 目錄秘密的權限。

目錄檢視器

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

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"

在程式碼中使用秘密

使用 dbutils.secrets.get 讀取 Unity Catalog 密鑰後，請將傳回的值傳遞給應用程式程式碼。 dbutils 會遮蔽儲存格輸出和日誌中的值，因此你可以在不暴露該值的情況下使用它。

以下範例使用秘密作為承載憑證來呼叫外部 API：

import requests

api_key = dbutils.secrets.get(catalog="main", schema="default", key="service_api_key")

response = requests.get(
    "https://api.example.com/v1/resource",
    headers={"Authorization": f"Bearer {api_key}"},
)
response.raise_for_status()

以下範例取得一個秘密值並傳遞給， dbutils.credentials.getServiceCredentialsProvider 以設定 AWS SDK 的 boto3 會話。服務憑證名稱本身並不敏感，因此此範例將憑證存於秘密中，僅說明如何將取得的秘密值串接到另一個 SDK 呼叫中。欲了解更多服務憑證資訊，請參閱使用 Unity 目錄服務憑證連接外部雲端服務。

import boto3

credential_name = dbutils.secrets.get(catalog="main", schema="default", key="service_credential_name")

boto3_session = boto3.Session(
    botocore_session=dbutils.credentials.getServiceCredentialsProvider(credential_name),
    region_name="your-aws-region",
)
sm = boto3_session.client("secretsmanager")

管理機密的權限

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

賦予創造秘密的能力

目錄檢視器

在目錄總管中，前往該結構描述。
按一下權限索引標籤。
請按一下授權。
選擇要授權存取的主體，然後選擇 建立秘密。

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

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}"

授權存取秘密

目錄檢視器

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

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}"

列出、更新及刪除秘密

列出機密

目錄檢視器

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

秘密工具程式（dbutils.secrets）

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

REST API

用 page_size 來控制每頁的結果數量。若有更多結果，回應包含：next_page_token

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

若要擷取下一頁，請將前一個回應中的 page_token 值作為 next_page_token 參數傳遞：

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

更新機密

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

目錄檢視器

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

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=*"

刪除秘密

目錄檢視器

在目錄總管中，前往結構描述，然後在概觀窗格中按一下密碼。
點選該密碼以刪除。
在右上角，點選烤肉選單（直線點），選擇刪除。
輸入秘密的全名，然後點擊刪除。

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 目錄的客戶管理金鑰。

使用外部秘密管理器來管理機密

你可以不用 Azure Databricks 儲存秘密值，而是用外部秘密管理器來備份結構，讓值保留在雲端秘密管理器中，同時在 Unity Catalog 中可被管理。 AWS Secrets Manager on AWS 和 Azure Key Vault on Azure 都被支援。關於外部秘密的運作方式，請參見 Unity 目錄中的外部秘密。若要支援帶有外部秘密管理器的結構，請參見 Unity 目錄中的外部秘密配置。

Limitations

Unity Catalog 密鑰有下列限制：

僅限從 SQL 倉儲直接存取。 你無法直接從 SQL 倉庫取得 Unity 目錄的機密。純量和批次 Unity Catalog Python UDF 可在 Pro 和無伺服器 SQL 倉儲上存取其 SECRETS 子句中宣告的密鑰。 Scalar Unity Catalog Scala UDF 只能在無伺服器 SQL 倉儲上存取已宣告的秘密。
專用運算無法直接 SECRETS 呼叫 UDF。 你無法在專用存取模式的運算資源上直接叫用使用 SECRETS 子句的純量或批次 Unity Catalog Python UDF，以及純量 Unity Catalog Scala UDF。關於欄位遮罩例外，請參見在專用計算中使用啟用秘密的 UDFs 於欄遮罩中。
沒有全球性的發現。 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 2026-09-30

Unity Catalog 中的密鑰

Unity Catalog 密鑰的運作方式

UDF 的要求與權限

會話範圍的 UDF

Unity 目錄 UDF

在專用計算中使用啟用秘密的 UDF 來進行欄位遮罩

Unity Catalog 機密的權限

開始之前

建立密碼

目錄檢視器

REST API

閱讀秘密

秘密工具程式 （dbutils.secrets）

REST API

在程式碼中使用秘密

管理機密的權限

賦予創造秘密的能力

目錄檢視器

SQL

REST API

授權存取秘密

目錄檢視器

SQL

REST API

列出、更新及刪除秘密

列出機密

目錄檢視器

秘密工具程式 （dbutils.secrets）

REST API

更新機密

目錄檢視器

REST API

刪除秘密

目錄檢視器

REST API

Unity Catalog 密碼的稽核事件

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

使用外部秘密管理器來管理機密

Limitations

意見反應

其他資源

秘密工具程式（dbutils.secrets）

秘密工具程式（dbutils.secrets）