Sekrety w katalogu Unity

Important

Ta funkcja jest dostępna w publicznej wersji testowej.

Na tej stronie opisano, jak tworzyć, odczytywać, nadzorować sekretami i zarządzać nimi w Unity Catalog. Sekret w Unity Catalog to obiekt podlegający zabezpieczeniu, który przechowuje informacje poufne, takie jak hasło, token lub klucz API. Notatniki i zadania mogą odwoływać się do sekretu bez ujawniania jego wartości w kodzie.

Wpisy tajne w Unity Catalog korzystają z trójpoziomowej przestrzeni nazw (catalog.schema.secret) i są dostępne we wszystkich przestrzeniach roboczych podłączonych do magazynu metadanych. Regulują je uprawnienia Unity Catalog. Dzięki temu możesz stosować wobec sekretów ten sam model dostępu i audyt, których używasz w przypadku innych zasobów danych.

Note

Sekrety Unity Catalog różnią się od sekretów Azure Databricks na poziomie przestrzeni roboczej, które są zorganizowane w zakresy sekretów. Użyj sekretów Unity Catalog, jeśli chcesz zarządzać nimi za pomocą uprawnień Unity Catalog i odwoływać się do nich przy użyciu trójpoziomowej przestrzeni nazw.

Jak działają sekrety w Unity Catalog

Klucz tajny w Unity Catalog jest obiektem zabezpieczalnym w ramach schematu i ma w pełni kwalifikowaną nazwę catalog.schema.secret. Podobnie jak inne zabezpieczalne obiekty w Unity Catalog, sekrety dziedziczą uprawnienia z katalogu i schematu. Aby uzyskać więcej informacji o obiektach zabezpieczalnych i dziedziczeniu, zobacz informacje o obiektach zabezpieczalnych w Unity Catalog.

Możesz używać klucza tajnego usługi Unity Catalog na następujące sposoby:

• Pobierz wartość w kodzie. Mając dostęp READ SECRET, użytkownicy mogą pobierać wartość wpisu tajnego z notatników i zadań przy użyciu dbutils lub interfejsu API REST usługi Unity Catalog. Następnie mogą używać ich do uwierzytelniania w systemach zewnętrznych lub do szyfrowania i odszyfrowywania danych.
• Odwołuj się do wartości z obiektów Unity Catalog. Obiekty Unity Catalog, takie jak połączenia Unity Catalog, mogą odwoływać się do wpisu tajnego po nazwie, tak aby integracja mogła korzystać z wpisu tajnego bez przyznawania użytkownikom dostępu do jego wartości. W zależności od obiektu, odwołanie do sekretu wymaga użycia elementu REFERENCE SECRET lub READ SECRET.

Azure Databricks przechowuje wartości wpisów tajnych usługi Unity Catalog w postaci zaszyfrowanej i stosuje maskowanie wpisów tajnych, aby ograniczyć ich przypadkowe ujawnienie w danych wyjściowych i dziennikach. Aby rotować wpis tajny, okresowo aktualizuj jego wartość w interfejsie użytkownika lub przy użyciu interfejsu API REST usługi Unity Catalog.

Uprawnienia do sekretów w Unity Catalog

Następujące uprawnienia dotyczą kluczy tajnych. Można je przyznać na poziomie katalogu, schematu lub pojedynczego sekretu, a podlegają one dziedziczeniu uprawnień w Unity Catalog.

Przywilej	Description
CREATE SECRET	Umożliwia użytkownikowi utworzenie wpisu tajnego w schemacie. Przyznane na poziomie katalogu lub schematu.
READ SECRET	Umożliwia użytkownikowi pobranie wartości sekretu.
WRITE SECRET	Umożliwia użytkownikowi aktualizowanie wartości wpisu tajnego.
REFERENCE SECRET	Umożliwia użytkownikowi odwoływanie się do sekretu, na przykład z połączenia Unity Catalog, bez dostępu do jego wartości.

Aby utworzyć sekret w schemacie, użytkownik musi mieć uprawnienie USE CATALOG oraz być właścicielem schematu lub mieć uprawnienia CREATE SECRET i USE SCHEMA do schematu. Aby dowiedzieć się, jak przyznać uprawnienia, zobacz Zarządzanie uprawnieniami w Unity Catalog.

Zanim rozpoczniesz

Aby korzystać z sekretów w Unity Catalog, musisz spełniać następujące wymagania:

• Obszar roboczy musi mieć włączony Unity Catalog. Wprowadzenie znajdziesz w artykule Co to jest Unity Catalog?.
• Musisz uzyskać dostęp do sekretów ze środowiska obliczeniowego z obsługą Unity Catalog. Azure Databricks zaleca jedną z następujących czynności:
  • Zadania bezserwerowe i notatniki korzystające ze środowiska w wersji 4 lub nowszej.
  • Klasyczne obliczenia w standardowym trybie dostępu z uruchomionym środowiskiem Databricks Runtime 17.3 LTS lub nowszym.
• Aby pobierać sekrety za pomocą dbutils, środowisko obliczeniowe musi działać w środowisku Databricks Runtime 17.3 LTS lub nowszym albo w środowisku bezserwerowym w wersji 4 lub nowszej.

Utwórz klucz tajny

Utworzenie sekretu wymaga posiadania uprawnienia USE CATALOG oraz bycia właścicielem schematu lub posiadania uprawnień CREATE SECRET i USE SCHEMA do schematu. Zobacz Uprawnienia dla sekretów w Unity Catalog.

Eksplorator wykazu

1. W obszarze roboczym Azure Databricks kliknij pozycję Wykaz, aby otworzyć Eksploratora wykazu.
2. Przejdź do schematu, w którym chcesz utworzyć klucz tajny.
3. Kliknij pozycję Utwórz > klucz tajny.
4. Wprowadź nazwę i wartość. Opcjonalnie dodaj komentarz i datę wygaśnięcia. Jeśli klucz tajny wygaśnie, w Catalog Explorer zostanie wyświetlone ostrzeżenie.
5. Kliknij pozycję Utwórz.

interfejs API REST

Uruchom następujące polecenie cURL przy użyciu punktu końcowego /api/2.1/unity-catalog/secrets :

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"

Przeczytać sekret

Aby odczytać wartość sekretu, musisz mieć uprawnienie READ SECRET do sekretu albo do katalogu nadrzędnego lub schematu.

Narzędzie Secrets (dbutils.secrets)

Azure Databricks zaleca użycie dbutils do odczytywania sekretów, ponieważ stosuje mechanizm ich ukrywania. Ta opcja wymaga środowiska Databricks Runtime 17.3 LTS lub nowszego albo środowiska bezserwerowego w wersji 4 lub nowszej.

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

Aby uzyskać więcej informacji, zobacz Narzędzie Secrets (dbutils.secrets).

interfejs API REST

Warning

Wartości sekretów pobrane za pomocą interfejsu API REST usługi Unity Catalog nie podlegają maskowaniu sekretów, chociaż dostęp do nich jest nadal rejestrowany w dziennikach audytu. Azure Databricks zaleca dbutils zamiast tego.

Aby uzyskać wartość, ustaw include_value=true i odczytaj pole effective_value w odpowiedzi:

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

Zarządzaj uprawnieniami do sekretów

Przyznaj CREATE SECRET na poziomie katalogu lub schematu, aby kontrolować, kto może tworzyć sekrety. Przyznaj READ SECRET, WRITE SECRET lub REFERENCE SECRET na poziomie katalogu, schematu lub pojedynczego klucza tajnego, aby kontrolować dostęp. Obowiązuje dziedziczenie uprawnień. Aby dowiedzieć się więcej na temat udzielania i cofania uprawnień, zobacz artykuł Zarządzanie uprawnieniami w Unity Catalog.

Przyznaj uprawnienie do tworzenia sekretów

Eksplorator wykazu

1. W Eksploratorze wykazu przejdź do schematu.

2. Kliknij kartę Uprawnienia .

3. Kliknij Grant.

4. Wybierz podmioty, którym chcesz przyznać dostęp, a następnie wybierz UTWÓRZ KLUCZ TAJNY.

   Jeśli podmiot zabezpieczeń nie ma USE SCHEMA, zostanie wyświetlone ostrzeżenie z prośbą o jego przyznanie. USE SCHEMA jest również wymagane do tworzenia sekretów w schemacie.

5. Kliknij przycisk Potwierdź.

SQL

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

interfejs API REST

Uruchom następujące polecenie cURL przy użyciu punktu końcowego /api/2.1/unity-catalog/permissions/schema/{schema_name} :

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

Przyznaj dostęp do sekretu

Eksplorator wykazu

1. W Catalog Explorer przejdź do sekretu i kliknij go.
2. Kliknij kartę Uprawnienia .
3. Kliknij Grant.
4. Wybierz podmioty i uprawnienia, które chcesz przyznać, a następnie kliknij przycisk Potwierdź.

SQL

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

interfejs API REST

Uruchom następujące polecenie cURL przy użyciu punktu końcowego /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} :

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

Wyświetlanie, aktualizowanie i usuwanie wpisów tajnych

Lista tajemnic

Eksplorator wykazu

1. W Eksploratorze wykazu przejdź do schematu.
2. W okienku Przegląd kliknij pozycję Wpisy tajne, aby wyświetlić wszystkie wpisy tajne w schemacie.

Narzędzie Secrets (dbutils.secrets)

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

interfejs API REST

Żądania wyświetlenia listy używają page_size do określania liczby wyników:

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"

Zaktualizuj klucz tajny

Aby zaktualizować wartość sekretu, musisz mieć uprawnienie WRITE SECRET do tego sekretu.

Eksplorator wykazu

1. W Eksploratorze wykazu przejdź do schematu i kliknij pozycję Sekrety w panelu Przegląd.
2. Kliknij wpis tajny, aby zaktualizować.
3. W prawym górnym rogu kliknij menu kebab (kropki pionowe) i wybierz pozycję Edytuj.
4. Wprowadź nową wartość lub datę wygaśnięcia, a następnie kliknij przycisk Potwierdź.

interfejs API REST

Żądania aktualizacji wymagają parametru update_mask . Aktualizowane są tylko pola uwzględnione zarówno w update_mask, jak i w treści żądania:

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

Usuń sekret

Eksplorator wykazu

1. W Eksploratorze wykazu przejdź do schematu i kliknij pozycję Sekrety w panelu Przegląd.
2. Kliknij sekret, aby go usunąć.
3. W prawym górnym rogu kliknij menu kebab (kropki pionowe) i wybierz pozycję Usuń.
4. Wprowadź pełną nazwę sekretu, a następnie kliknij przycisk Usuń.

interfejs API REST

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

Zdarzenia audytu dla sekretów w Unity Catalog

Tabela systemowa system.access.audit rejestruje zdarzenia związane z sekretami w Unity Catalog. Na przykład aby wyświetlić wszystkie zdarzenia dotyczące sekretów dla użytkownika w określonym dniu, uruchom następujące zapytanie:

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

Aby uzyskać więcej informacji na temat dzienników inspekcji, zobacz Dokumentacja tabeli systemu dzienników inspekcji.

Szyfrowanie wartości wpisów tajnych przy użyciu kluczy zarządzanych przez klienta

Domyślnie usługa Azure Databricks szyfruje wartości wpisów tajnych za pomocą kluczy zarządzanych przez Databricks. Zamiast tego możesz użyć kluczy zarządzanych przez klienta (CMK). Jeśli włączysz funkcję zarządzanego katalogu szyfrowanego za pomocą CMK i przypiszesz konfigurację CMK do swojego konta, Azure Databricks użyje CMK do szyfrowania wartości sekretów. Aby uzyskać więcej informacji, zobacz Klucze zarządzane przez klienta dla Unity Catalog.

Limitations

Sekrety w Unity Catalog mają następujące ograniczenia:

• Brak magazynów SQL. Sekrety Unity Catalog nie są obsługiwane w hurtowniach SQL. Wymagane jest środowisko Databricks Runtime 17.3 LTS lub nowsze w środowisku obliczeniowym z obsługą Unity Catalog albo w środowisku bezserwerowym.
• Brak globalnego wykrywania. Sekrety w Unity Catalog nie pojawiają się w wyszukiwaniu globalnym.
• Brak obsługi uprawnień BROWSE. BROWSE w katalogu nie ma zastosowania do sekretów Unity Catalog. Aby umożliwić odnalezienie sekretu, przyznaj READ SECRET lub REFERENCE SECRET dla konkretnego sekretu lub jego schematu.
• Brak skryptów inicjowania. Nie można używać sekretów usługi Unity Catalog w globalnych skryptach inicjalizacyjnych ani skryptach inicjalizacyjnych klastra. Azure Databricks zaleca używanie dedykowanych funkcji zamiast skryptów inicjowania tam, gdzie to możliwe.
• Brak schematu informacji. Tabele schematu informacyjnego dla sekretów nie są jeszcze dostępne. Użyj narzędzia Catalog Explorer lub interfejsu API REST do wyszukiwania.
• dbutils zakres środowiska uruchomieniowego. dbutils Pobieranie jest obsługiwane w notesach i zadaniach opartych na środowisku Databricks Runtime. Konteksty środowiska uruchomieniowego innego niż Databricks, takie jak zdalne programowanie lub skompilowane tryby uruchamiania JAR, nie są obsługiwane.
• Zakres interfejsu API OAuth. Interfejs API sekretów Unity Catalog jest dostępny tylko w zakresie OAuth API unity-catalog. Używaj zakresu interfejsu API secrets tylko dla wpisów tajnych Azure Databricks na poziomie obszaru roboczego.
• Limity przydziału. Maksymalnie 100 sekretów na schemat i 1 000 na magazyn metadanych.