Unity Catalog’daki Gizli Bilgiler

Bu sayfada Unity Catalog'da gizli anahtarların nasıl oluşturulacağı, okunacağı, yönetişiminin nasıl sağlanacağı ve yönetileceği açıklanmaktadır. Unity Kataloğu gizli dizisi parola, belirteç veya API anahtarı gibi hassas malzemeleri depolayan güvenli hale getirilebilir bir nesnedir. Notebook’larınız ve işleriniz, değeri kodda açığa çıkarmadan gizli anahtara başvurabilir.

Unity Kataloğu gizli dizileri üç düzeyli ad alanını (catalog.schema.secret) kullanır ve meta veri deposuna eklenen çalışma alanlarında kullanılabilir. Bunlar Unity Catalog izinleri tarafından denetlenir. Bu, gizli dizilerinize diğer veri varlıkları için kullandığınız erişim modelini ve denetimi uygulamanızı sağlar.

Note

Unity Kataloğu gizli dizileri, gizli diziler halinde düzenlenmiş çalışma alanı düzeyinde Azure Databricks gizli dizilerden farklıdır. Gizli bilgileri Unity Catalog ayrıcalıklarıyla yönetmek ve bunlara üç düzeyli ad alanını kullanarak referans vermek istediğinizde Unity Catalog gizli bilgilerini kullanın.

Unity Kataloğu gizli dizileri nasıl çalışır?

Unity Catalog gizli anahtarı, tam nitelikli adı catalog.schema.secret olan, bir şema altında güvenliği yönetilebilen bir nesnedir. Diğer Unity Catalog güvenliği yönetilebilir nesneleri gibi, gizli anahtarlar da katalog ve şemadan ayrıcalıkların devralınmasını destekler. Güvenliği sağlanabilen nesneler ve devralma hakkında daha fazla bilgi için bkz. Unity Catalog güvenliği sağlanabilen nesneler başvurusu.

Unity Catalog gizli anahtarını aşağıdaki şekillerde kullanabilirsiniz:

  • Koddaki değeri alın. READ SECRET erişimine sahip kullanıcılar, dbutils veya Unity Catalog REST API'sini kullanarak not defterlerinden ve işlerden gizli bir değeri alabilir. Daha sonra dış sistemlerle kimlik doğrulaması yapmak veya verileri şifrelemek ve şifresini çözmek için bunu kullanabilirler.
  • Değeri, oturum kapsamındaki bir Python veya Scala UDF’sinde kullanın. Oturum kapsamındaki UDF'lere bakınız.
  • Değeri Unity Catalog Python UDF'sinde kullanın. Skaler veya Batch UDF, her sırrı kendi SECRETS maddesinde ilan eder. Python UDF'lerine bakınız.
  • Değeri Unity Catalog Scala UDF'de kullanın. Skaler bir UDF her sırrı kendi SECRETS maddesinde ilan eder. Scala UDF'lerine bakınız.

UDF türleri arasında gereksinimler ve izin davranışları için bkz. UDF gereksinimleri ve izinleri.

UDF'ler, Azure Databricks tarafından yönetilen sırlar veya harici bir gizli yönetici tarafından desteklenen sırlar kullanabilir. Unity Kataloğundaki Dış Sırlar'a bakınız.

UDF gereksinimleri ve izinleri

Gereksinimler ve izinlerin işleyişi, oturum kapsamındaki UDF'lerle Unity Catalog UDF'leri arasında farklılık gösterir.

Oturum kapsamlı UDF'ler

Oturum kapsamındaki bir Python UDF, databricks.secrets.get() ile bir gizli anahtar alır ve oturum kapsamındaki bir Scala UDF, com.databricks.Secrets.get() ile bir gizli anahtar alır. Gizli erişim, arayanın izinlerini kullanır.

Gizli erişim için hesaplama gereksinimleri UDF diline bağlıdır:

  • Sunucusuz hesaplamada, notebook veya iş oturumu Python ve Scala UDF'ler için ortam sürüm 6 veya üzerini kullanmak zorundadır.
  • Klasik işlemde, oturum kapsamındaki Python UDF'leri, standart veya özel erişim modunda Databricks Runtime 19 veya üzerini gerektirir.
  • Klasik işlem ortamında, oturum kapsamındaki Scala UDF'leri için standart erişim modunda Databricks Runtime 19 veya üzeri gerekir.

Unity Kataloğu UDF'leri

Skaler ve toplu Unity Catalog Python UDF'leri ile skaler Unity Catalog Scala UDF'leri, sırları SECRETS yan tümcesinde bildirir ve 6 değerini açıkça environment_version veya üzerine ayarlamalıdır. Sunucusuz hesaplama, sunucusuz SQL depoları ve standart erişim moduyla Databricks Runtime 19 veya üzeri kullanan klasik hesaplamayı destekler.

Pro SQL depoları, sır kullanan skaler ve Batch Unity Catalog Python UDF'leri destekler. Gizli anahtarlar kullanan Unity Catalog Scala UDF’leri, Pro SQL ambarlarında desteklenmez.

Gizli dizi bildiren bir UDF oluşturmak veya değiştirmek için, deyimi çalıştıran sorumlunun gizli dizi üzerinde USE CATALOG, üst katalog ve şeması üzerinde ise USE SCHEMA ve READ SECRET yetkilerine sahip olması gerekir. Çalışma zamanında, UDF mevcut fonksiyon sahibinin izinlerini kullanır. Çağıranlar, EXECUTE dahil olmak üzere olağan işlev ayrıcalıklarına ihtiyaç duyar, ancak tanımlanan gizli bilgilere doğrudan erişmeleri gerekmez. Fonksiyon sahibi ilan edilen bir sırrı okuma iznini kaybederse, UDF başarısız olur.

Özel hesaplamada sütun maskelerinde gizli özellikli UDF'ler kullanın

SECRETS yan tümcesini kullanan bir Unity Catalog Python veya Scala UDF’sini, özel erişim modu işlem kaynağında doğrudan çağıramazsınız. Ancak, gizli özellikli UDF'yi çağıran bir Unity Kataloğu SQL fonksiyonu oluşturabilir ve SQL fonksiyonunu öznitelik tabanlı erişim kontrolü (ABAC) sütun maskesi olarak kullanabilirsin. Bir sorgu özel hesaplamada çalıştığında, Azure Databricks column maske uygulamasını sunucusuz hesaplamaya delege eder. Bu istisna yalnızca sütun maskesi uygulanırken geçerlidir; özel hesaplamada gizli etkinleştirilmiş UDF'nin doğrudan çağrılmasını mümkün kılmaz. Desteklenmeyen hesaplama sürümleri sayfasına bakınız.

Warning

Gizli değerleri yalnızca UDF uygulaması içinde kullanın. Gizli değerleri geri göndermeyin veya bunları UDF sonuçlarına dahil etmeyin. Gizli redaksiyon, hatalarda ve loglarda kazara ortaya çıkmayı azaltmaya yardımcı olur, ancak UDF kodunun sorgu sonuçlarında gizli materyali açığa çıkarmasını engellemez.

Azure Databricks, Unity Catalog gizli değerlerini şifrelenmiş biçimde depolar ve çıkışlarda ve günlüklerde kazara açığa çıkmayı azaltmak için gizli değer maskelemesi uygular. Gizli diziyi döndürmek için kullanıcı arabirimindeki veya Unity Kataloğu REST API'sindeki değerini düzenli aralıklarla güncelleştirin.

Unity Catalog gizli anahtarları için ayrıcalıklar

Aşağıdaki ayrıcalıklar gizli bilgiler için geçerlidir. Bunları katalog, şema veya tek tek gizler düzeyinde verebilirsiniz ve bunlar Unity Catalog ayrıcalık devralımını izler.

Privilege Description
CREATE SECRET Bir kullanıcının bir şemada secret oluşturmasına olanak tanır. Katalog veya şema düzeyinde verilir.
READ SECRET Bir kullanıcının gizli bir değeri almasına olanak tanır.
WRITE SECRET Bir kullanıcının gizli bir değeri güncellemesine izin verir.
REFERENCE SECRET Kullanıcının değere erişmeden bir sırra referans vermesine izin verir.

Bir şemada gizli anahtar oluşturmak için, kullanıcının USE CATALOG iznine sahip olması ve ayrıca ya şemanın sahibi olması ya da şema üzerinde CREATE SECRET ve USE SCHEMA izinlerine sahip olması gerekir. Ayrıcalıkların nasıl verileceğini öğrenmek için bkz. Unity Kataloğu'nda ayrıcalıkları yönetme.

Başlamadan önce

Unity Kataloğu gizli dizilerini kullanmak için aşağıdaki gereksinimleri karşılamanız gerekir:

  • Unity Kataloğu için çalışma alanının etkinleştirilmesi gerekir. Giriş için bkz. Unity Kataloğu nedir?.
  • Gizli anahtarlara Unity Catalog etkinleştirilmiş işlem kaynaklarından erişmelisiniz. Azure Databricks aşağıdakilerden birini önerir:
  • dbutils ile gizli anahtarları almak için işlem kaynağının Databricks Runtime 17.3 LTS veya üzeri ya da sunucusuz ortam sürümü 4 veya üzeri üzerinde çalışıyor olması gerekir.

Bir sır oluştur.

Bir gizli oluşturmak için USE CATALOG iznine sahip olmanız ve şemanın sahibi olmanız veya şema üzerinde CREATE SECRET ve USE SCHEMA izinlerine sahip olmanız gerekir. Bkz. Unity Catalog gizli anahtarları için ayrıcalıklar.

Katalog Tarayıcısı

  1. Azure Databricks çalışma alanınızda Katalog'a tıklayarak Katalog Gezgini'ne tıklayın.
  2. Gizli anahtarı oluşturmak istediğiniz şemaya gidin.
  3. Gizli Anahtar >Oluştur seçeneğine tıklayın.
  4. Bir ad ve değer girin. İsteğe bağlı olarak, bir yorum ve bir sona erme tarihi ekleyin. Bir gizli anahtarın süresi dolarsa, Katalog Gezgini bir uyarı gösterir.
  5. Oluştur'utıklayın.

REST API

Uç noktayı kullanarak /api/2.1/unity-catalog/secrets aşağıdaki cURL komutunu çalıştırın:

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"

Bir sırrı oku

Bir gizli değeri okumak için, gizli üzerinde veya üst katalog ya da şema üzerinde READ SECRET iznine sahip olmanız gerekir.

Secrets aracı (dbutils.secrets)

Azure Databricks, gizli bilgileri okumak için dbutils kullanmanızı önerir çünkü gizli bilgilerin sansürlenmesini uygular. Bu seçenek Databricks Runtime 17.3 LTS veya üzeri ya da sunucusuz ortam sürüm 4 veya üzeri gerektirir.

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

Daha fazla bilgi için bkz: Gizli Diziler yardımcı programı (dbutils.secrets).

REST API

Warning

Unity Catalog REST API’si aracılığıyla alınan gizli değerler, gizli bilgi maskelemesine tabi değildir; ancak erişimin kaydı yine de denetim günlüklerinde tutulur. bunun yerine Azure Databricks önerirdbutils.

Değeri döndürmek için include_value=true öğesini ayarlayın ve yanıttaki effective_value alanını okuyun:

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

Kodunda bir sır kullanın

Unity Catalog gizli anahtarını dbutils.secrets.get ile okuduktan sonra, döndürülen değeri uygulama kodunuza iletin. dbutils değeri hücre çıktısında ve loglarda gizler, böylece değeri açığa çıkarmadan kullanabilirsiniz.

Aşağıdaki örnekte, harici bir API’yi çağırmak için bearer token olarak bir secret kullanılır:

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

Aşağıdaki örnek, bir gizli değeri alır ve AWS SDK için bir boto3 oturumunu yapılandırmak üzere bunu dbutils.credentials.getServiceCredentialsProvider öğesine geçirir. Bir hizmet kimlik bilgisi adı tek başına hassas değildir; bu nedenle bu örnek, alınan bir secret değerinin başka bir SDK çağrısına aktarılmasını göstermek amacıyla bunlardan birini yalnızca bir secret içinde saklar. Hizmet kimlik bilgileri hakkında daha fazla bilgi için, Unity Kataloğu hizmet kimlik bilgilerini harici bulut servislerine bağlamak için kullan sayfasına bakınız.

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

Gizli bilgilerin izinlerini yönet

Kimlerin giz oluşturabileceğini denetlemek için katalog veya şema düzeyinde CREATE SECRET izin verin. Erişimi denetlemek için READ SECRET, WRITE SECRET veya REFERENCE SECRET iznini katalog, şema ya da tek tek gizli düzeyinde verin. Ayrıcalık devralma uygulanır. Ayrıcalıkları verme ve iptal etme hakkında daha fazla bilgi edinmek için bkz. Unity Kataloğu'nda ayrıcalıkları yönetme.

Gizli anahtar oluşturma izni tanı

Katalog Tarayıcısı

  1. Katalog Gezgini'nde şemaya gidin.

  2. İzinler sekmesine tıklayın.

  3. İzin ver düğmesine tıklayın.

  4. Erişim izni verilecek yetkilileri seçin, ardından GİZLİ ANAHTAR OLUŞTUR'u seçin.

    Bir sorumluya sahip USE SCHEMAdeğilse, bir uyarı sizden bunu vermenizi ister. USE SCHEMA şemada gizli diziler oluşturmak için de gereklidir.

  5. Onayla'yı tıklatın.

SQL

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

REST API

Uç noktayı kullanarak /api/2.1/unity-catalog/permissions/schema/{schema_name} aşağıdaki cURL komutunu çalıştırın:

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

Bir gizliye erişim izni ver

Katalog Tarayıcısı

  1. Katalog Gezgini'nde gizli anahtara gidin ve üzerine tıklayın.
  2. İzinler sekmesine tıklayın.
  3. İzin ver düğmesine tıklayın.
  4. Vermek istediğiniz sorumluları ve ayrıcalıkları seçin, ardından Onayla'ya tıklayın.

SQL

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

REST API

Uç noktayı kullanarak /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} aşağıdaki cURL komutunu çalıştırın:

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

Gizli anahtarları listeleme, güncelleştirme ve silme

Gizlilikleri listele

Katalog Tarayıcısı

  1. Katalog Gezgini'nde şemaya gidin.
  2. Şemadaki tüm gizli dizileri görmek için Genel Bakış bölmesinde Gizli Diziler'e tıklayın.

Secrets aracı (dbutils.secrets)

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

REST API

Sayfa başına sonuç sayısını kontrol etmek için kullanılır page_size . Daha fazla sonuç mevcutsa, yanıt şunları next_page_tokeniçerir:

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"

Bir sonraki sayfayı almak için, önceki yanıttaki değeri next_page_token parametre olarak page_token aktarın:

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"

Gizli anahtarı güncelle

Bir gizli değeri güncellemek için, gizli üzerinde WRITE SECRET yetkiniz olmalıdır.

Katalog Tarayıcısı

  1. Katalog Gezgini'nde şemaya gidin ve Genel Bakış bölmesinde Gizli Diziler'e tıklayın.
  2. Güncellemek için gizli öğeye tıklayın.
  3. Sağ üst köşede kebap menüsüne (dikey noktalar) tıklayın ve Düzenle'yi seçin.
  4. Yeni bir değer veya son kullanma tarihi girip Onayla'ya tıklayın.

REST API

Güncelleştirme istekleri parametresini update_mask gerektirir. Yalnızca hem update_mask içinde hem de istek gövdesinde yer alan alanlar güncellenir:

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

Bir sırrı sil

Katalog Tarayıcısı

  1. Katalog Gezgini'nde şemaya gidin ve Genel Bakış bölmesinde Gizli Diziler'e tıklayın.
  2. Silmek için gize tıklayın.
  3. Sağ üst köşede kebap menüsüne (dikey noktalar) tıklayın ve Sil'i seçin.
  4. Gizli anahtarın tam adını girin, ardından Sil düğmesine tıklayın.

REST API

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

Unity Catalog gizli anahtarları için denetim olayları

system.access.audit sistem tablosu, Unity Catalog gizli anahtarlarıyla ilgili olayları kaydeder. Örneğin, belirli bir tarihte kullanıcının tüm gizli dizi olaylarını görmek için aşağıdaki sorguyu çalıştırın:

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

Denetim günlükleri hakkında daha fazla bilgi için bkz. Denetim günlüğü sistemi tablo başvurusu.

Gizli değerleri müşteri tarafından yönetilen anahtarlarla şifreleyin

varsayılan olarak, Azure Databricks gizli dizi değerlerini Databricks tarafından yönetilen anahtarlarla şifreler. Bunun yerine müşteri tarafından yönetilen anahtarları (CMK) kullanabilirsiniz. CMK ile şifrelenmiş yönetilen katalog özelliğini etkinleştirir ve hesabınıza bir CMK yapılandırması eklerseniz Azure Databricks gizli dizi değerlerini şifrelemek için CMK kullanır. Daha fazla bilgi için bkz. Unity Kataloğu için müşteri tarafından yönetilen anahtarlar.

Gizli anahtarları harici bir gizli anahtar yöneticisiyle yedekleyin

Azure Databricks gizli değerleri depolamak yerine, bir şemayı harici gizli yöneticiyle destekleyebilirsiniz; böylece değerler bulut gizli yöneticinizde kalırken Unity Catalog'da yönetilebilir kalabilir. AWS Secrets Manager on AWS ve Azure Key Vault on Azure desteklenmektedir. Dış sırlar nasıl çalıştığı için Unity Kataloğu'ndaki Dış Sırlar bölümüne bakınız. Bir şemayı harici gizli yöneticiyle desteklemek için Unity Kataloğunda harici sırları yapılandırma bölümüne bakınız.

Limitations

Unity Kataloğu gizli anahtarları aşağıdaki sınırlamalara sahiptir:

  • SQL depolarından sınırlı doğrudan erişim. Unity Kataloğu sırlarını doğrudan SQL depolarından alamazsınız. Scalar ve Batch Unity Catalog Python UDF'leri, pro ve sunucusuz SQL ambarlarında SECRETS yan tümcelerinde tanımlanan gizli bilgilere erişebilir. Skaler Unity Kataloğu Scala UDF'leri, yalnızca sunucusuz SQL depolarında ilan edilen sırlara erişebilir.
  • Özel hesaplamada doğrudan SECRETS UDF çağırışı yok. Özel erişim modu işlem kaynaklarında, skaler veya Batch Unity Catalog Python UDF'lerini ya da SECRETS yan tümcesini kullanan skaler Unity Catalog Scala UDF'lerini doğrudan çağıramazsınız. Sütun maskesi özel durumu için, Adanmış işlem üzerinde sütun maskelerinde gizli etkinleştirilmiş UDF'leri kullanın bölümüne bakın.
  • Genel keşif yok. Unity Kataloğu gizli anahtarları genel aramada görüntülenmez.
  • BROWSE izni desteklenmiyor. BROWSE katalog üzerindeki Unity Catalog gizli anahtarları için geçerli değildir. Bir gizli bilgiyi bulunabilir hale getirmek için, gizli bilginin kendisi veya şeması üzerinde READ SECRET ya da REFERENCE SECRET yetkisi verin.
  • Başlatma betikleri yok. Unity Kataloğu gizli dizilerini genel veya küme başlatma betiklerinde kullanamazsınız. Azure Databricks mümkün olduğunda başlatma betikleri yerine ayrılmış özelliklerin kullanılmasını önerir.
  • Bilgi şeması yok. Gizli anahtarlar için bilgi şeması tabloları henüz mevcut değildir. Bulma için Katalog Gezgini'ni veya REST API'yi kullanın.
  • dbutils çalışma zamanı kapsamı. dbutils alma, Databricks Runtime destekli not defterlerinde ve işlerde desteklenir. Uzaktan geliştirme veya derlenmiş JAR çalıştırma modları gibi Databricks Runtime dışı bağlamlar desteklenmez.
  • OAuth API kapsamı. Unity Catalog gizli anahtarlar API'sine yalnızca unity-catalog OAuth API kapsamı ile erişilebilir. secrets API kapsamını yalnızca çalışma alanı düzeyinde Azure Databricks gizli dizileri için kullanın.
  • Kota sınırı. Şema başına en fazla 100 gizli anahtar ve metaveri deposu başına 1.000 gizli anahtar.