Секреты в каталоге Unity

Important

Эта функция доступна в общедоступной предварительной версии.

На этой странице описано, как создавать, читать, контролировать доступ к секретам и управлять ими в Unity Catalog. Секрет каталога Unity — это защищаемый объект, который хранит конфиденциальный материал, например пароль, маркер или ключ API. Записные книжки и задания могут ссылаться на секрет без предоставления значения в коде.

Секреты каталога Unity используют трехуровневое пространство имен (catalog.schema.secret) и доступны в рабочих областях, подключенных к хранилищу метаданных. Их регулируют привилегии Unity Catalog. Это позволяет применять к секретам ту же модель доступа и тот же аудит, что и для других информационных ресурсов.

Note

Секреты каталога Unity отличаются от секретов на уровне рабочей области Azure Databricks, которые организованы в области секретов. Используйте секреты каталога Unity, если вы хотите управлять секретами с правами каталога Unity и ссылаться на них с пространством имен трех уровней.

Как работают секреты каталога Unity

Секрет в Unity Catalog — это защищаемый объект в схеме, имеющий полное имя catalog.schema.secret. Как и другие защищаемые объекты каталога Unity, секреты поддерживают наследование привилегий из каталога и схемы. Дополнительные сведения о защищаемых объектах и наследовании см. в справочнике по защищаемым объектам каталога Unity.

Секрет каталога Unity можно использовать следующим образом:

Получите значение в коде. При наличии доступа READ SECRET пользователи могут получать секретное значение из ноутбуков и заданий с помощью dbutils или REST API Unity Catalog. Затем они могут использовать его для проверки подлинности с помощью внешних систем или для шифрования и расшифровки данных.
Ссылка на значение из объектов каталога Unity. Объекты Unity Catalog, такие как подключения Unity Catalog, могут ссылаться на секрет по имени, чтобы интеграция могла использовать этот секрет без предоставления пользователям доступа к его значению. В зависимости от объекта, для ссылки на секрет требуется REFERENCE SECRET либо READ SECRET.

Azure Databricks хранит значения секретов Unity Catalog в зашифрованном виде и применяет маскирование секретов, чтобы уменьшить риск их случайного раскрытия в выводе и журналах. Чтобы выполнить ротацию секрета, периодически обновляйте его значение в интерфейсе или с помощью REST API Unity Catalog.

Привилегии для секретов каталога Unity

Следующие привилегии управляют секретами. Их можно предоставить на уровне каталога, схемы или отдельного секрета, и на них распространяется наследование привилегий Unity Catalog.

Привилегия	Описание
`CREATE SECRET`	Позволяет пользователю создавать секрет в схеме. Предоставлено на уровне каталога или схемы.
`READ SECRET`	Позволяет пользователю получить значение секрета.
`WRITE SECRET`	Позволяет пользователю обновлять значение секрета.
`REFERENCE SECRET`	Позволяет пользователю ссылаться на секрет, например из подключения в Unity Catalog, без доступа к его значению.

Чтобы создать секрет в схеме, пользователь должен иметь USE CATALOG разрешение и либо владеть схемой, либо иметь CREATE SECRET и USE SCHEMA в схеме. Сведения о предоставлении привилегий см. в статье "Управление привилегиями" в каталоге Unity.

Перед тем как начать

Чтобы использовать секреты каталога Unity, необходимо выполнить следующие требования:

Рабочая область должна быть активирована для работы с Unity Catalog. Общие сведения см. в разделе "Что такое каталог Unity?".
Необходимо получить доступ к секретам из вычислительных ресурсов с поддержкой каталога Unity. Azure Databricks рекомендует одно из следующих рекомендаций.
- Бессерверные задания и блокноты с версией среды 4 или выше.
- Классические вычисления в стандартном режиме доступа с Databricks Runtime 17.3 LTS или более поздней версии.
Чтобы получать секреты с помощью dbutils, вычислительный ресурс должен использовать Databricks Runtime 17.3 LTS или выше либо бессерверную среду версии 4 или выше.

Создание секрета

Для создания секрета необходимо иметь разрешение USE CATALOG и быть владельцем схемы либо иметь разрешения CREATE SECRET и USE SCHEMA на схему. См. Привилегии для секретов в Unity Catalog.

Обозреватель каталогов

В рабочей области Azure Databricks щелкните каталог, чтобы открыть обозреватель каталогов.
Перейдите к схеме, в которой нужно создать секрет.
Нажмите кнопку "Создать > секрет".
Введите имя и значение. При необходимости добавьте комментарий и дату окончания срока действия. Если срок действия секрета истекает, обозреватель каталогов отображает предупреждение.
Нажмите кнопку Создать.

REST API

Выполните следующую команду cURL, используя конечную точку /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"

Прочитайте секрет

Чтобы прочитать значение секрета, необходимо иметь READ SECRET для секрета или для родительского каталога или схемы.

Утилита Secrets (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")

Дополнительные сведения см. в разделе Служебная программа Secrets (dbutils.secrets).

REST API

Предупреждение

Значения секретов, полученные с помощью REST API каталога Unity, не подлежат повторному удалению секрета, хотя доступ по-прежнему записывается в журналы аудита. 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"

Управление разрешениями на доступ к секретам

Предоставьте разрешение CREATE SECRET на уровне каталога или схемы, чтобы управлять тем, кто может создавать секреты. Предоставьте READ SECRET, WRITE SECRET или REFERENCE SECRET на уровне каталога, схемы или отдельного секрета, чтобы управлять доступом. Применяется наследование привилегий. Дополнительные сведения о предоставлении и отмене привилегий см. в разделе "Управление привилегиями" в каталоге Unity.

Предоставление возможности создавать секреты

Обозреватель каталогов

В обозревателе каталогов перейдите к схеме.
Выберите вкладку Разрешения .
Нажмите Grant.
Выберите субъекты, которым нужно предоставить доступ, затем выберите CREATE SECRET.

Если у субъекта нет USE SCHEMA, появится предупреждение с предложением предоставить его. USE SCHEMA также требуется для создания секретов в схеме.
Нажмите кнопку "Подтвердить".

SQL

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

REST API

Выполните следующую команду cURL, используя конечную точку /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}"

Предоставление доступа к секрету

Обозреватель каталогов

В обозревателе каталогов перейдите к секрету и щелкните его.
Выберите вкладку Разрешения .
Нажмите Grant.
Выберите субъекты и привилегии для предоставления, а затем нажмите кнопку "Подтвердить".

SQL

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

REST API

Выполните следующую команду cURL, используя конечную точку /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}"

Просматривать, обновлять и удалять секреты

Список секретов

Обозреватель каталогов

В обозревателе каталогов перейдите к схеме.
В области "Обзор " щелкните "Секреты" , чтобы просмотреть все секреты в схеме.

Утилита Secrets (dbutils.secrets)

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

REST API

Запросы на получение списка используют page_size для управления количеством результатов:

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"

Обновление секрета

Чтобы обновить значение секрета, необходимо иметь 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

Системная system.access.audit таблица записывает события, связанные с секретами каталога Unity. Например, чтобы просмотреть все секретные события для пользователя по определенной дате, выполните следующий запрос:

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.

Limitations

Секреты каталога Unity имеют следующие ограничения:

Нет хранилищ SQL. Секреты каталога Unity не поддерживаются в хранилищах SQL. Для этого требуется Databricks Runtime версии 17.3 LTS или выше на вычислительных ресурсах с поддержкой Unity Catalog либо в бессерверной среде.
Нет глобального обнаружения. Секреты каталога Unity не отображаются в глобальном поиске.
Разрешение BROWSE не поддерживается. BROWSE в каталоге не применяется к секретам каталога Unity. Чтобы сделать секрет доступным для обнаружения, предоставьте READ SECRET или REFERENCE SECRET для отдельного секрета или его схемы.
Нет скриптов инициализации. Секреты каталога Unity нельзя использовать в глобальных или кластерных скриптах инициализации. Azure Databricks рекомендует использовать выделенные функции вместо сценариев инициализации по возможности.
Схема информации отсутствует. Таблицы схемы информации с данными о секретах пока недоступны. Используйте обозреватель каталогов или REST API для обнаружения.
dbutils область выполнения. dbutils Извлечение поддерживается в записных книжках и заданиях, поддерживаемых средой выполнения Databricks. Контексты среды выполнения, отличные от Databricks, такие как удаленные режимы разработки или скомпилированные режимы выполнения JAR, не поддерживаются.
Область API OAuth. API секретов каталога Unity доступен только в unity-catalog области API OAuth. secrets Используйте область API только для секретов уровня рабочей области Azure Databricks.
Ограничения квот. До 100 секретов на схему и 1000 на хранилище метаданных.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-07-17

Секреты в каталоге Unity

Как работают секреты каталога Unity

Привилегии для секретов каталога Unity

Перед тем как начать

Создание секрета

Обозреватель каталогов

REST API

Прочитайте секрет

Утилита Secrets (dbutils.secrets)

REST API

Управление разрешениями на доступ к секретам

Предоставление возможности создавать секреты

Обозреватель каталогов

SQL

REST API

Предоставление доступа к секрету

Обозреватель каталогов

SQL

REST API

Просматривать, обновлять и удалять секреты

Список секретов

Обозреватель каталогов

Утилита Secrets (dbutils.secrets)

REST API

Обновление секрета

Обозреватель каталогов

REST API

Удалить секрет

Обозреватель каталогов

REST API

События аудита для секретов каталога Unity

Шифрование значений секретов с помощью ключей, управляемых клиентом

Limitations

Обратная связь

Дополнительные ресурсы