Клиентская библиотека секретов Azure Key Vault для Python версии 4.7.0

Начало работы

Установка пакетов

Установите azure-keyvault-secrets и azure-identity с помощью pip:

pip install azure-keyvault-secrets azure-identity

Azure-identity используется для проверки подлинности Azure Active Directory, как показано ниже.

Предварительные требования

• Подписка Azure
• Python версии 3.7 или выше
• Существующий Key Vault Azure. Если вам нужно создать ее, вы можете сделать это с помощью Azure CLI, выполнив действия, описанные в этом документе.

Аутентификация клиента

Чтобы взаимодействовать со службой azure Key Vault, вам потребуется экземпляр SecretClient, а также URL-адрес хранилища и объект учетных данных. В этом документе демонстрируется использование DefaultAzureCredential, который подходит для большинства сценариев, включая локальную среду разработки и рабочую среду. Мы рекомендуем использовать управляемое удостоверение для проверки подлинности в рабочих средах.

Дополнительные сведения о других методах проверки подлинности и соответствующих типах учетных данных см. в документации по azure-identity .

Создание клиента

После настройки среды для DefaultAzureCredential для использования подходящего метода проверки подлинности можно сделать следующее, чтобы создать секретный клиент (заменив значение VAULT_URL URL-адресом хранилища):

VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = SecretClient(vault_url=VAULT_URL, credential=credential)

ПРИМЕЧАНИЕ: Вместо этого импортируйте azure.keyvault.secrets.aioдля SecretClient асинхронного клиента.

Основные понятия

Секрет

Секрет состоит из значения секрета и связанных с ним метаданных и сведений об управлении. Эта библиотека обрабатывает значения секретов как строки, но azure Key Vault не сохраняет их как таковые. Дополнительные сведения о секретах и о том, как Key Vault хранит их и управляет ими, см. в документации по Key Vault.

SecretClient может задавать значения секретов в хранилище, обновлять метаданные секретов и удалять секреты, как показано в примерах ниже.

Примеры

В этом разделе содержатся фрагменты кода, охватывающие распространенные задачи:

• Установка секрета
• Получение секрета
• Обновление метаданных секрета
• Удаление секрета
• Вывод списка секретов
• Асинхронный API
• Асинхронное создание секрета
• Асинхронный список секретов

Установка секрета

set_secret создает новые секреты и изменяет значения существующих секретов. Если секрета с заданным именем не существует, set_secret создает новый секрет с этим именем и заданным значением. Если используется заданное имя, set_secret создает новую версию этого секрета с заданным значением.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

Получение секрета

get_secret извлекает секрет, ранее сохраненный в Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.get_secret("secret-name")

print(secret.name)
print(secret.value)

Обновление метаданных секрета

update_secret_properties обновляет метаданные секрета. Он не может изменить значение секрета; используйте set_secret , чтобы задать значение секрета.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Clients may specify the content type of a secret to assist in interpreting the secret data when it's retrieved
content_type = "text/plain"

# We will also disable the secret for further use

updated_secret_properties = secret_client.update_secret_properties("secret-name", content_type=content_type, enabled=False)

print(updated_secret_properties.updated_on)
print(updated_secret_properties.content_type)
print(updated_secret_properties.enabled)

Удаление секрета.

begin_delete_secret запросы Key Vault удалить секрет, возвращая средство опроса, которое позволяет дождаться завершения удаления. Ожидание полезно, если в хранилище включено обратимое удаление , и вы хотите очистить (окончательно удалить) секрет как можно скорее. Если обратимое удаление отключено, begin_delete_secret само по себе является постоянным.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_secret = secret_client.begin_delete_secret("secret-name").result()

print(deleted_secret.name)
print(deleted_secret.deleted_date)

получение списка секретов;

list_properties_of_secrets перечисляет свойства всех секретов в хранилище клиента. Этот список не включает значения секрета.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

Асинхронный API

Эта библиотека включает полный набор асинхронных API. Чтобы использовать их, необходимо сначала установить асинхронный транспорт, например aiohttp. Дополнительные сведения см. в документации по azure-core .

Асинхронные клиенты и учетные данные должны быть закрыты, если они больше не нужны. Эти объекты являются диспетчерами асинхронного контекста и определяют асинхронные close методы. Пример:

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()

# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

Асинхронное создание секрета

set_secret создает секрет в Key Vault с указанными необязательными аргументами.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

secret = await secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

Асинхронный список секретов

list_properties_of_secrets перечисляет свойства всех секретов в хранилище клиента.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

async for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

Устранение неполадок

Дополнительные сведения о диагностике azure-keyvault-secrets различных сценариев сбоя см. в руководстве по устранению неполадок.

Общее

Key Vault клиенты вызывают исключения, определенные в azure-core. Например, если вы пытаетесь получить ключ, который не существует в хранилище, SecretClient вызовет ResourceNotFoundError:

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    secret_client.get_secret("which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.

Подробное ведение журнала на уровне DEBUG, включая тексты запросов и ответов и нередактированные заголовки, можно включить на клиенте с помощью аргумента logging_enable :

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
import sys
import logging

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

credential = DefaultAzureCredential()

# This client will log detailed information about its HTTP sessions, at DEBUG level
secret_client = SecretClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

Аналогичным образом с помощью параметра logging_enable можно включить подробное журналирование для отдельной операции (даже если этот режим не включен в клиенте):

secret_client.get_secret("my-secret", logging_enable=True)

Дальнейшие действия

Несколько примеров доступны в репозитории GitHub пакета AZURE SDK для Python. Ниже приведен пример кода для дополнительных сценариев Key Vault: | Файл | Описание | |-------------|-------------| | hello_world.py (асинхронная версия) | Создание, получение, обновление и удаление секретов | | list_operations.py (асинхронная версия) | Базовые операции со списком для секретов | | backup_restore_operations.py (асинхронная версия) | Резервное копирование и восстановление секретов | | recover_purge_operations.py (асинхронная версия) | восстановление и очистка секретов |

Дополнительная документация

Более подробную документацию по azure Key Vault см. в справочной документации по API.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения: Вопросы и ответы по правилам поведения. С любыми другими вопросами или комментариями обращайтесь по адресу [email protected].