Tajné kódy v katalogu Unity

Important

Tato stránka popisuje, jak vytvářet, číst, řídit a spravovat tajné kódy v katalogu Unity. Tajný kód katalogu Unity je zabezpečitelný objekt, který ukládá citlivý materiál, například heslo, token nebo klíč rozhraní API. Vaše notebooky a úlohy mohou odkazovat na tajný klíč, aniž by se jeho hodnota odhalila v kódu.

Tajné kódy katalogu Unity používají tříúrovňový obor názvů (catalog.schema.secret) a jsou dostupné napříč pracovními prostory připojenými k metastoru. Řídí se oprávněními katalogu Unity. To vám umožní použít pro tajné údaje stejný model přístupu a audit, jaký používáte pro jiná datová aktiva.

Note

Tajné údaje katalogu Unity se liší od tajných údajů Azure Databricks na úrovni pracovního prostoru, které jsou uspořádány do oblastí tajných údajů. Použijte tajné klíče Unity Catalog, pokud chcete spravovat tajné klíče pomocí oprávnění Unity Catalog a odkazovat na ně pomocí tříúrovňového názvového prostoru.

Jak fungují tajné kódy katalogu Unity

Tajný kód katalogu Unity je zabezpečitelný objekt ve schématu s plně kvalifikovaným názvem catalog.schema.secret. Podobně jako u jiných zabezpečitelných objektů v katalogu Unity podporují tajné údaje dědění oprávnění z katalogu a schématu. Další informace o zabezpečitelných objektech a dědičnosti naleznete v tématu Referenční informace o zabezpečitelných objektech Unity.

Tajný kód katalogu Unity můžete použít následujícími způsoby:

Načtěte hodnotu v kódu. S přístupem READ SECRET mohou uživatelé načíst tajnou hodnotu v poznámkových blocích a úlohách pomocí dbutils nebo rozhraní Unity Catalog REST API. Pak ho můžou použít k ověření v externích systémech nebo k šifrování a dešifrování dat.
Odkazujte na hodnotu z objektů katalogu Unity. Objekty Unity Catalogu, jako jsou připojení Unity Catalogu, můžou odkazovat na tajný klíč podle názvu, aby integrace mohla tajný klíč používat, aniž by uživatelům udělila přístup k jeho hodnotě. V závislosti na objektu vyžaduje odkazování na tajný kód buď REFERENCE SECRET nebo READ SECRET.

Azure Databricks ukládá hodnoty tajných klíčů ve službě Unity Catalog v zašifrované podobě a používá maskování tajných údajů, aby se omezilo jejich náhodné zveřejnění ve výstupech a protokolech. Chcete-li tajný klíč obměnit, pravidelně aktualizujte jeho hodnotu v UI nebo pomocí rozhraní Unity Catalog REST API.

Oprávnění pro tajné kódy katalogu Unity

Následující oprávnění upravují tajné údaje. Můžete je udělit na úrovni katalogu, schématu nebo jednotlivého tajného klíče a vztahuje se na ně dědičnost oprávnění v Unity Catalog.

Oprávnění	Description
`CREATE SECRET`	Umožňuje uživateli vytvořit tajný kód ve schématu. Uděleno na úrovni katalogu nebo schématu.
`READ SECRET`	Umožňuje uživateli načíst tajnou hodnotu.
`WRITE SECRET`	Umožňuje uživateli aktualizovat hodnotu tajného kódu.
`REFERENCE SECRET`	Umožňuje uživateli odkazovat na tajný údaj, například z připojení v Unity Catalog, bez přístupu k jeho hodnotě.

K vytvoření tajného klíče ve schématu musí mít uživatel oprávnění USE CATALOG a buď být vlastníkem schématu, nebo mít pro dané schéma oprávnění CREATE SECRET a USE SCHEMA. Informace o udělení oprávnění najdete v tématu Správa oprávnění v katalogu Unity.

Než začnete

Pokud chcete používat tajné kódy katalogu Unity, musíte splňovat následující požadavky:

Pracovní prostor musí být povolený pro katalog Unity. Úvod najdete v tématu Co je Katalog Unity?.
K tajným klíčům musíte přistupovat z výpočetních prostředků s podporou Unity Catalogu. Azure Databricks doporučuje jednu z následujících možností:
- Bezserverové úlohy a poznámkové bloky používající prostředí verze 4 nebo novější.
- Klasické výpočty v režimu standardního přístupu s Databricks Runtime 17.3 LTS nebo novějším.
Aby bylo možné načíst tajné kódy dbutils, musí výpočetní prostředí spouštět Databricks Runtime 17.3 LTS nebo vyšší nebo bezserverové prostředí verze 4 nebo vyšší.

Vytvořit tajemství

Vytvoření tajného klíče vyžaduje, abyste měli oprávnění USE CATALOG a byli vlastníkem schématu, nebo měli pro schéma oprávnění CREATE SECRET a USE SCHEMA. Viz Oprávnění pro tajné kódy katalogu Unity.

Průzkumník katalogu

V pracovním prostoru Azure Databricks kliknutím na Katalog otevřete Průzkumníka katalogu.
Přejděte do schématu, ve kterém chcete vytvořit tajný klíč.
Klikněte na Vytvořit tajný klíč>.
Zadejte název a hodnotu. Volitelně můžete přidat komentář a datum vypršení platnosti. Pokud vyprší platnost tajného kódu, Zobrazí se v Průzkumníku katalogu upozornění.
Klikněte na Vytvořit.

REST API

Spusťte následující příkaz cURL pomocí koncového /api/2.1/unity-catalog/secrets bodu:

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"

Čtení tajného kódu

Abyste si mohli přečíst tajnou hodnotu, musíte mít READ SECRET k tajnému klíči nebo k nadřazenému katalogu či schématu.

Nástroj pro správu tajných informací (dbutils.secrets)

Azure Databricks doporučuje dbutils pro čtení tajných údajů, protože zajišťuje skrytí tajných údajů. Tato možnost vyžaduje Databricks Runtime 17.3 LTS nebo novější nebo bezserverové prostředí verze 4 nebo vyšší.

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

Další informace najdete v části nástroj Secrets (dbutils.secrets).

REST API

Warning

Tajné hodnoty načtené pomocí rozhraní REST API služby Unity Catalog nepodléhají maskování tajných hodnot, i když se přístup stále zaznamenává v protokolech auditu. Azure Databricks místo toho doporučuje dbutils.

Pokud chcete vrátit hodnotu, nastavte include_value=true a načtěte effective_value pole v odpovědi:

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

Správa oprávnění k tajným kódům

Udělte oprávnění CREATE SECRET na úrovni katalogu nebo schématu, abyste určili, kdo může vytvářet tajné údaje. Udělte READ SECRET, WRITE SECRET, nebo REFERENCE SECRET na úrovni katalogu, schématu nebo jednotlivého tajného klíče pro řízení přístupu. Dědičnost oprávnění platí. Další informace o udělení a odvolání oprávnění najdete v tématu Správa oprávnění v katalogu Unity.

Udělení možnosti vytvářet tajné kódy

Průzkumník katalogu

V Průzkumníku katalogu přejděte na schéma.
Klikněte na kartu Oprávnění .
Klikněte na Povolit.
Vyberte objekty zabezpečení, ke které chcete udělit přístup, a pak vyberte VYTVOŘIT TAJNÝ KÓD.

Pokud objekt zabezpečení nemá USE SCHEMA, zobrazí se upozornění, které vás vyzve k jeho udělení. USE SCHEMA je také nutné k vytvoření tajných kódů ve schématu.
Klikněte na tlačítko Potvrdit.

SQL

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

REST API

Spusťte následující příkaz cURL pomocí koncového /api/2.1/unity-catalog/permissions/schema/{schema_name} bodu:

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

Udělení přístupu k tajnému kódu

Průzkumník katalogu

V nástroji Catalog Explorer přejděte k objektu secret a klikněte na něj.
Klikněte na kartu Oprávnění .
Klikněte na Povolit.
Vyberte objekty zabezpečení a oprávnění, která chcete udělit, a klikněte na tlačítko Potvrdit.

SQL

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

REST API

Spusťte následující příkaz cURL pomocí koncového /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} bodu:

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

Vypsat, aktualizovat a odstranit tajné údaje

Vypsat tajemství

Průzkumník katalogu

V Průzkumníku katalogu přejděte na schéma.
V podokně Přehled klikněte na Tajné kódy a zobrazte tak všechny tajné kódy ve schématu.

Nástroj pro správu tajných informací (dbutils.secrets)

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

REST API

Požadavky na výpis používají page_size k určení počtu výsledků:

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"

Aktualizace tajného kódu

Pokud chcete aktualizovat hodnotu tajného klíče, musíte mít u tajného klíče oprávnění WRITE SECRET.

Průzkumník katalogu

V Průzkumníku katalogu přejděte na schéma a v podokně Přehled klikněte na Tajné kódy.
Kliknutím na tajný klíč aktualizujte.
V pravém horním rohu klikněte na nabídku kebabu (svislé tečky) a vyberte Upravit.
Zadejte novou hodnotu nebo datum vypršení platnosti a klikněte na Potvrdit.

REST API

Požadavky na aktualizaci vyžadují update_mask parametr. Aktualizují se pouze pole zahrnutá jak v update_mask, tak v těle požadavku:

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

Odstranění tajemství

Průzkumník katalogu

V Průzkumníku katalogu přejděte na schéma a v podokně Přehled klikněte na Tajné kódy.
Klikněte na tajný kód, který chcete odstranit.
V pravém horním rohu klikněte na nabídku kebabu (svislé tečky) a vyberte Odstranit.
Zadejte úplný název tajného kódu a klikněte na Odstranit.

REST API

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

Auditní události pro tajné klíče v katalogu Unity

system.access.audit Systémová tabulka zaznamenává události související s tajnými kódy katalogu Unity. Pokud například chcete zobrazit všechny tajné události pro uživatele k určitému datu, spusťte následující dotaz:

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%";

Další informace o protokolech auditu naleznete v dokumentu Referenční příručka k systémové tabulce protokolu auditu.

Šifrování hodnot tajných kódů pomocí klíčů spravovaných zákazníkem

Ve výchozím nastavení Azure Databricks šifruje tajné hodnoty pomocí klíčů spravovaných službou Databricks. Místo toho můžete použít klíče spravované zákazníkem (CMK). Pokud povolíte funkci spravovaného katalogu s šifrováním CMK a připojíte ke svému účtu konfiguraci CMK, Azure Databricks pomocí klíče CMK zašifruje hodnoty tajných kódů. Další informace najdete v tématu Klíče spravované zákazníkem pro Katalog Unity.

Limitations

Tajné kódy katalogu Unity mají následující omezení:

Žádné SQL warehouse. Tajné kódy katalogu Unity nejsou podporovány ve skladech SQL. Vyžadují databricks Runtime 17.3 LTS nebo vyšší na výpočetních prostředcích s podporou katalogu Unity nebo bez serveru.
Žádné globální zjišťování. Tajné kódy katalogu Unity se nezobrazují v globálním vyhledávání.
Žádná podpora oprávnění BROWSE. BROWSE v katalogu se nevztahuje na tajné kódy katalogu Unity. Aby bylo možné tajný klíč objevit, udělte oprávnění READ SECRET nebo REFERENCE SECRET pro konkrétní tajný klíč nebo jeho schéma.
Žádné inicializační skripty. Tajné klíče v Unity Catalogu nelze používat v globálních inicializačních skriptech ani v inicializačních skriptech clusteru. Azure Databricks doporučuje, pokud je to možné, používat vyhrazené funkce místo inicializačních skriptů.
Žádné schéma informací. Tabulky informačního schématu pro tajné údaje ještě nejsou k dispozici. Ke zjišťování použijte Průzkumníka katalogu nebo rozhraní REST API.
dbutils rozsah modulu runtime. dbutils Vyhledávání je podporováno v poznámkových blocích a úlohách využívajících Databricks Runtime. Kontexty modulu runtime mimo Databricks, jako je vzdálený vývoj nebo kompilovaný režim spuštění JAR, nejsou podporovány.
Rozsah rozhraní API OAuth Rozhraní API pro tajné údaje v katalogu Unity je přístupné pouze s rozsahem unity-catalog rozhraní OAuth API. secrets Rozsah rozhraní API použijte pouze pro tajné kódy na úrovni pracovního prostoru Azure Databricks.
Omezení kvót. Až 100 tajných kódů na schéma a 1 000 na metastor.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-17

Tajné kódy v katalogu Unity

Jak fungují tajné kódy katalogu Unity

Oprávnění pro tajné kódy katalogu Unity

Než začnete

Vytvořit tajemství

Průzkumník katalogu

REST API

Čtení tajného kódu

Nástroj pro správu tajných informací (dbutils.secrets)

REST API

Správa oprávnění k tajným kódům

Udělení možnosti vytvářet tajné kódy

Průzkumník katalogu

SQL

REST API

Udělení přístupu k tajnému kódu

Průzkumník katalogu

SQL

REST API

Vypsat, aktualizovat a odstranit tajné údaje

Vypsat tajemství

Průzkumník katalogu

Nástroj pro správu tajných informací (dbutils.secrets)

REST API

Aktualizace tajného kódu

Průzkumník katalogu

REST API

Odstranění tajemství

Průzkumník katalogu

REST API

Auditní události pro tajné klíče v katalogu Unity

Šifrování hodnot tajných kódů pomocí klíčů spravovaných zákazníkem

Limitations

Váš názor

Další materiály