Hemligheter i Unity-katalogen

Den här sidan beskriver hur du skapar, läser, styr och hanterar hemligheter i Unity Catalog. En Unity Catalog-hemlighet är ett skyddsbart objekt som lagrar känsligt material, till exempel lösenord, token eller API-nyckel. Dina notebook-filer och jobb kan referera till hemligheten utan att exponera värdet i koden.

Unity Catalog-hemligheter använder namnområdet på tre nivåer (catalog.schema.secret) och är tillgängliga på de arbetsytor som är kopplade till ett metaarkiv. Behörigheter för Unity Catalog styr dem. På så sätt kan du använda samma åtkomstmodell och granskning som du använder för andra datatillgångar för dina hemligheter.

Så här fungerar Unity Catalog-hemligheter

En Unity Catalog-hemlighet är ett skyddsbart objekt under ett schema med det fullständigt kvalificerade namnet catalog.schema.secret. Precis som andra skyddsbara objekt i Unity Catalog stöder hemligheter arv av privilegier från katalogen och schemat. Mer information om skyddsbara objekt och arv finns i Referens för skyddsbara objekt i Unity Catalog.

Du kan använda en Unity Catalog-hemlighet på följande sätt:

• Hämta värdet i koden. Med READ SECRET åtkomst kan användarna hämta ett hemligt värde från notebook-filer och jobb med hjälp av dbutils eller REST-API:et för Unity Catalog. De kan sedan använda den för att autentisera med externa system eller för att kryptera och dekryptera data.
• Använd värdet i en sessionsbegränsad Python- eller Scala-UDF. Se sessionsbaserade UDF.
• Använd värdet i en Unity Catalog Python UDF. En skalär eller batch-UDF deklarerar varje hemlighet i sin SECRETS klausul. Se Python UDFs.
• Använd värdet i en Unity Catalog Scala UDF. En skalär UDF deklarerar varje hemlighet i dess SECRETS klausul. Se Scala UDFs.

För krav och behörighetsbeteende över UDF-typer, se UDF-krav och behörigheter.

UDF:er kan använda Azure Databricks-hanterade hemligheter eller hemligheter som backas upp av en extern hemlig hanterare. Se Externa hemligheter i Unity-katalogen.

UDF-krav och behörigheter

Krav och behörighetsbeteende skiljer sig mellan sessionsbegränsade och Unity Catalog UDF:er.

Sessionsbaserade UDF:er

En sessionsomfattande Python-UDF hämtar en hemlighet med databricks.secrets.get(), och en sessionsomfattande Scala-UDF hämtar en med com.databricks.Secrets.get(). Hemlig åtkomst använder uppringarens behörigheter.

Beräkningskrav för hemlig åtkomst beror på UDF-språket:

• I serverlösa beräkningar måste notebooken eller jobbsessionen använda miljöversion 6 eller senare för Python- och Scala-UDF:er.
• På klassisk beräkning kräver sessionsbegränsade Python UDF:er Databricks Runtime 19 eller högre i standard- eller dedikerat åtkomstläge.
• På klassisk beräkning kräver sessionsbegränsade Scala UDF:er Databricks Runtime 19 eller högre med standardåtkomstläge.

UDF:er i Unity Catalog

Skalära och batchbaserade Unity Catalog Python-UDF:er samt skalära Unity Catalog Scala-UDF:er deklarerar hemligheter i SECRETS-klausulen och måste uttryckligen ange environment_version till 6 eller högre. De har stöd för serverlös databearbetning, SQL-datalager utan server och klassisk databearbetning som kör Databricks Runtime 19 eller senare med standardåtkomstläge.

Pro SQL-lager stödjer skalär och Batch Unity Catalog Python UDF:er som använder hemligheter. Unity Catalog Scala UDF:er som använder hemligheter stöds inte på professionella SQL-lager.

För att skapa eller ersätta en UDF som deklarerar en hemlighet måste huvudpersonen som exekverar satsen ha READ SECRET på hemligheten och USE CATALOG och USE SCHEMA på dess föräldrakatalog och schema. Vid körning använder UDF den aktuella funktionsägarens behörigheter. Anropare behöver de vanliga funktionsbehörigheterna, inklusive EXECUTE, men behöver inte direkt åtkomst till de deklarerade hemligheterna. Om funktionsägaren förlorar tillståndet att läsa en deklarerad hemlighet misslyckas UDF:n.

Använd UDF:er med stöd för hemligheter i kolumnmasker på dedikerade beräkningsresurser

Du kan inte anropa en Unity Catalog Python eller Scala UDF som använder klausulen SECRETS direkt i dedikerad åtkomstlägesberäkning. Du kan dock skapa en Unity Catalog SQL-funktion som anropar den hemlighetsaktiverade UDF och använda SQL-funktionen som en attributbaserad åtkomstkontrollmask (ABAC). När en fråga körs på dedikerade beräkningsresurser delegerar Azure Databricks tillämpningen av kolumnmaskering till serverlösa beräkningsresurser. Detta undantag gäller endast vid tillämpning av kolumnmasken; det medger inte att UDF:en med stöd för hemligheter anropas direkt på dedikerade beräkningsresurser. Se Icke-stödda beräkningsversioner.

Azure Databricks lagrar hemliga värden i Unity Catalog krypterade och tillämpar hemlig redigering för att minska oavsiktlig exponering i utdata och loggar. Om du vill rotera en hemlighet uppdaterar du regelbundet dess värde i användargränssnittet eller med REST-API:et för Unity Catalog.

Behörigheter för Unity Catalog-hemligheter

Följande behörigheter styr hemligheter. Du kan ge dem på katalog-, schema- eller nivån för enskilda hemligheter, och de följer Unity Catalogs arv av behörigheter.

Om du vill skapa en hemlighet i ett schema måste en användare ha USE CATALOG behörighet och antingen äga schemat eller ha CREATE SECRET och USE SCHEMA i schemat. Information om hur du beviljar behörigheter finns i Hantera privilegier i Unity Catalog.

Requirements

Om du vill använda Unity Catalog-hemligheter måste du uppfylla följande krav:

• Arbetsytan måste vara aktiverad för Unity Catalog. En introduktion finns i Vad är Unity Catalog?.
• Du måste komma åt hemligheter från Unity Catalog-aktiverad beräkning. Azure Databricks rekommenderar något av följande:
  • Serverlösa jobb och anteckningsböcker som använder miljöversion 4 eller senare.
  • Klassisk beräkning i standardåtkomstläge som kör Databricks Runtime 17.3 LTS eller senare.
• För att hämta hemligheter med dbutilsmåste beräkningen köra Databricks Runtime 17.3 LTS eller senare, eller serverlös miljöversion 4 eller senare.

Skapa en hemlighet

Att skapa en hemlighet kräver att du har USE CATALOG behörighet och äger schemat eller har CREATE SECRET och USE SCHEMA i schemat. Se Behörigheter för Unity Catalog-hemligheter.

Katalogutforskaren

1. I din Azure Databricks arbetsyta klickar du på Katalog för att öppna Katalogutforskaren.
2. Gå till schemat där du vill skapa hemligheten.
3. Klicka på Skapa > en hemlighet.
4. Ange ett namn och värde. Du kan också lägga till en kommentar och ett förfallodatum. Om en hemlighet upphör att gälla visas en varning i Katalogutforskaren.
5. Klicka på Skapa.

REST API

Kör följande cURL-kommando med hjälp av /api/2.1/unity-catalog/secrets slutpunkten:

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"

Läsa en hemlighet

Om du vill läsa ett hemligt värde måste du ha READ SECRET på hemligheten eller i en överordnad katalog eller ett schema.

Secrets-verktyget (dbutils.secrets)

Azure Databricks rekommenderar dbutils att du läser hemligheter eftersom det tillämpar hemlig redigering. Det här alternativet kräver Databricks Runtime 17.3 LTS eller senare, eller serverlös miljöversion 4 eller senare.

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

Mer information finns i Verktyget Hemligheter (dbutils.secrets).

REST API

För att returnera värdet anger du include_value=true och läser fältet effective_value i svaret:

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

Använd en hemlighet i din kod

Efter att du läst en Unity-kataloghemlighet med dbutils.secrets.get, skicka det returnerade värdet till din applikationskod. dbutils Redigerar värdet i cellutdata och loggar, så att du kan använda det utan att exponera det.

Följande exempel använder en hemlighet som bärartoken för att anropa ett externt 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()

Följande exempel hämtar ett hemligt värde och skickar det till dbutils.credentials.getServiceCredentialsProvider för att konfigurera en boto3-session för AWS SDK. Ett tjänstelegitimationsnamn är inte känsligt i sig, så detta exempel lagrar ett i en hemlighet endast för att illustrera hur man kedjar ett återhämtat hemligt värde till ett annat SDK-anrop. För mer information om tjänsteuppgifter, se Använd Unity Catalog tjänsteuppgifter för att ansluta till externa molntjänster.

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

Hantera behörigheter för hemligheter

Bevilja CREATE SECRET på katalog- eller schemanivå för att styra vem som kan skapa hemligheter. Bevilja READ SECRET, WRITE SECRET, eller REFERENCE SECRET på katalog-, schema- eller enskild hemlig nivå för att kontrollera åtkomsten. Privilegiearv gäller. Mer information om hur du beviljar och återkallar privilegier finns i Hantera privilegier i Unity Catalog.

Ge möjlighet att skapa hemligheter

Katalogutforskaren

1. Gå till schemat i Katalogutforskaren.

2. Klicka på fliken Behörigheter .

3. Klicka på Tillåt.

4. Välj de huvudkonton som du vill bevilja åtkomst till och välj sedan SKAPA HEMLIGHET.

   Om ett huvudnamn inte har USE SCHEMAuppmanas du att bevilja en varning. USE SCHEMA krävs också för att skapa hemligheter i schemat.

5. Klicka på Bekräfta.

SQL

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

REST API

Kör följande cURL-kommando med hjälp av /api/2.1/unity-catalog/permissions/schema/{schema_name} slutpunkten:

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

Bevilja åtkomst till en hemlighet

Katalogutforskaren

1. I Katalogutforskaren går du till hemligheten och klickar på den.
2. Klicka på fliken Behörigheter .
3. Klicka på Tillåt.
4. Välj de huvudkonton och behörigheter som ska beviljas och klicka sedan på Bekräfta.

SQL

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

REST API

Kör följande cURL-kommando med hjälp av /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} slutpunkten:

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

Lista, uppdatera och ta bort hemligheter

Lista hemligheter

Katalogutforskaren

1. Gå till schemat i Katalogutforskaren.
2. I fönstret Översikt klickar du på Hemligheter för att se alla hemligheter i schemat.

Secrets-verktyget (dbutils.secrets)

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

REST API

Använd page_size för att kontrollera antalet resultat per sida. Om fler resultat finns tillgängliga inkluderar svaret en 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"

För att hämta nästa sida, skicka next_page_token värdet från föregående svar som page_token parametern:

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"

Uppdatera en hemlighet

Om du vill uppdatera ett hemligt värde måste du ha WRITE SECRET på hemligheten.

Katalogutforskaren

1. I Katalogutforskaren går du till schemat och klickar på Hemligheter i fönstret Översikt .
2. Klicka på hemligheten för att uppdatera.
3. I det övre högra hörnet klickar du på menyn för kebab (lodräta punkter) och väljer Redigera.
4. Ange ett nytt värde eller förfallodatum och klicka sedan på Bekräfta.

REST API

Uppdateringsbegäranden kräver parametern update_mask . Endast fält som ingår i båda update_mask och begärandetexten uppdateras:

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

Ta bort en hemlighet

Katalogutforskaren

1. I Katalogutforskaren går du till schemat och klickar på Hemligheter i fönstret Översikt .
2. Klicka på hemligheten för att ta bort.
3. I det övre högra hörnet klickar du på menyn för kebab (lodräta punkter) och väljer Ta bort.
4. Ange det fullständiga namnet på hemligheten och klicka sedan på Ta bort.

REST API

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

Granska händelser för Unity Catalog-hemligheter

Systemtabellen system.access.audit registrerar händelser relaterade till Unity Catalog-hemligheter. Om du till exempel vill se alla hemliga händelser för en användare på ett visst datum kör du följande fråga:

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

Mer information om granskningsloggar finns i Systemtabellreferens för granskningsloggar.

Kryptera hemliga värden med kundhanterade nycklar

Som standard krypterar Azure Databricks hemliga värden med Databricks-hanterade nycklar. Du kan i stället använda kundhanterade nycklar (CMK). Om du aktiverar funktionen cmk-krypterad hanterad katalog och kopplar en CMK-konfiguration till ditt konto använder Azure Databricks CMK för att kryptera hemliga värden. Mer information finns i Kundhanterade nycklar för Unity Catalog.

Hemligheter med en extern hemlig chef

Istället för att Azure Databricks lagrar hemliga värden kan du backa upp ett schema med en extern hemlig hanterare så att värdena stannar i din molnhemlighetshanterare samtidigt som de kan styras i Unity Catalog. AWS Secrets Manager på AWS och Azure Key Vault på Azure stöds. För hur externa hemligheter fungerar, se Externa hemligheter i Unity-katalogen. För att backa ett schema med en extern hemlig hanterare, se Konfigurera externa hemligheter i Unity Catalog.

Limitations

Unity Catalog-hemligheter har följande begränsningar:

• Begränsad direktåtkomst från SQL-lager. Du kan inte hämta Unity-katalogens hemligheter direkt från SQL-lager. Skalära och batchbaserade Unity Catalog Python-UDF:er kan få åtkomst till hemliga värden som deklareras i sina SECRETS-satser i pro- och serverless SQL-datalager. Scalar Unity Catalog Scala UDF:er kan endast komma åt deklarerade hemligheter på serverlösa SQL-lager.
• Direkt SECRETS UDF-anrop stöds inte på dedikerade beräkningsresurser. Du kan inte anropa skalära eller batchbaserade Unity Catalog Python-UDF:er eller skalära Unity Catalog Scala-UDF:er som använder satsen SECRETS direkt på beräkningsresurser med dedikerat åtkomstläge. För undantaget för kolumnmasker, se Använd UDF:er med stöd för hemligheter i kolumnmasker med dedikerad beräkning.
• Ingen global upptäckt. Unity Catalog-hemligheter visas inte i global sökning.
• Inget stöd för BROWSE-behörighet. BROWSE i en katalog gäller inte för Unity Catalog-hemligheter. För att göra en hemlighet upptäckbar, ge READ SECRET eller REFERENCE SECRET för den specifika hemligheten eller dess schema.
• Inga init-skript. Du kan inte använda Unity Catalog-hemligheter i globala skript eller kluster-init-skript. Azure Databricks rekommenderar att du använder dedikerade funktioner i stället för init-skript där det är möjligt.
• Inget informationsschema. Informationsschematabeller för hemligheter är ännu inte tillgängliga. Använd Katalogutforskaren eller REST-API:et för identifiering.
• dbutils körningsomfång. dbutils hämtning stöds i Databricks Runtime-säkerhetskopierade notebook-filer och jobb. Icke-Databricks Runtime-kontexter, till exempel fjärrutveckling eller kompilerade JAR-körningslägen, stöds inte.
• OAuth API-omfång. API:et unity-catalog för unity-kataloghemligheter är endast tillgängligt med OAuth API-omfånget. Använd API-omfånget secrets endast för Azure Databricks hemligheter på arbetsytenivå.
• Kvotgränser. Upp till 100 hemligheter per schema och 1 000 per metaarkiv.