Azure Key Vault Secrets-Clientbibliothek für Python– Version 4.7.0

Erste Schritte

Installieren von Paketen

Installieren Sie azure-keyvault-secrets und azure-identity mit pip:

pip install azure-keyvault-secrets azure-identity

azure-identity wird für die Azure Active Directory-Authentifizierung verwendet, wie unten gezeigt.

Voraussetzungen

• Ein Azure-Abonnement
• Python 3.7 oder höher
• Eine vorhandene Azure Key Vault. Wenn Sie eine erstellen müssen, können Sie dies mithilfe der Azure CLI tun, indem Sie die Schritte in diesem Dokument ausführen.

Authentifizieren des Clients

Für die Interaktion mit dem Azure Key Vault-Dienst benötigen Sie eine Instanz eines SecretClient sowie eine Tresor-URL und ein Anmeldeinformationsobjekt. In diesem Dokument wird die Verwendung von DefaultAzureCredential veranschaulicht, die für die meisten Szenarien geeignet ist, einschließlich lokaler Entwicklungs- und Produktionsumgebungen. Es wird empfohlen, eine verwaltete Identität für die Authentifizierung in Produktionsumgebungen zu verwenden.

Weitere Informationen zu anderen Authentifizierungsmethoden und den entsprechenden Anmeldeinformationstypen finden Sie in der Dokumentation zu azure-identity .

Erstellen eines Clients

Nachdem Sie Ihre Umgebung für defaultAzureCredential für die Verwendung einer geeigneten Authentifizierungsmethode konfiguriert haben, können Sie wie folgt vorgehen, um einen geheimen Client zu erstellen (indem Sie den Wert von durch VAULT_URL die URL Ihres Tresors ersetzen):

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

HINWEIS: Für einen asynchronen Client importieren Sie azure.keyvault.secrets.aiostattdessen die von SecretClient .

Wichtige Begriffe

`Secret`

Ein Geheimnis besteht aus einem Geheimniswert und den zugehörigen Metadaten und Verwaltungsinformationen. Diese Bibliothek verarbeitet Geheimwerte als Zeichenfolgen, aber Azure Key Vault speichert sie nicht als solche. Weitere Informationen zu Geheimnissen und wie Key Vault sie speichert und verwaltet, finden Sie in der Key Vault-Dokumentation.

SecretClient kann Geheimniswerte im Tresor festlegen, geheime Metadaten aktualisieren und Geheimnisse löschen, wie in den folgenden Beispielen gezeigt.

Beispiele

Dieser Abschnitt enthält Codeausschnitte zu allgemeinen Aufgaben:

• Festlegen eines Geheimnisses
• Abrufen eines Geheimnisses
• Aktualisieren von Geheimnismetadaten
• Löschen eines Geheimnisses
• Auflisten von Geheimnissen
• Asynchrone API
• Asynchrones Erstellen eines Geheimnisses
• Asynchrones Auflisten von Geheimnissen

Festlegen eines Geheimnisses

set_secret erstellt neue Geheimnisse und ändert die Werte vorhandener Geheimnisse. Wenn kein Geheimnis mit dem angegebenen Namen vorhanden ist, set_secret erstellt ein neues Geheimnis mit diesem Namen und dem angegebenen Wert. Wenn der angegebene Name verwendet wird, set_secret erstellt eine neue Version dieses Geheimnisses mit dem angegebenen Wert.

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)

Abrufen eines Geheimnisses

get_secret ruft ein Geheimnis ab, das zuvor im Key Vault gespeichert wurde.

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)

Aktualisieren von Geheimnismetadaten

update_secret_properties aktualisiert die Metadaten eines Geheimnisses. Der Wert des Geheimnisses kann nicht geändert werden. verwenden Sie set_secret , um den Wert eines Geheimnisses festzulegen.

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)

Löschen eines Geheimnisses

begin_delete_secret Anforderungen Key Vault Löschen eines Geheimnisses und geben einen Abruf zurück, mit dem Sie auf den Abschluss des Löschvorgangs warten können. Warten ist hilfreich, wenn für den Tresor vorläufiges Löschen aktiviert ist und Sie das Geheimnis so schnell wie möglich löschen (dauerhaft löschen) möchten. Wenn vorläufiges Löschen deaktiviert ist, begin_delete_secret ist selbst dauerhaft.

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)

Auflisten geheimer Schlüssel

list_properties_of_secrets listet die Eigenschaften aller Geheimnisse im Tresor des Clients auf. Diese Liste enthält nicht die Werte des Geheimnisses.

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)

Asynchrone API

Diese Bibliothek enthält einen vollständigen Satz von asynchronen APIs. Um sie verwenden zu können, müssen Sie zunächst einen asynchronen Transport installieren, z. B. aiohttp. Weitere Informationen finden Sie in der Dokumentation zu azure-core .

Asynchrone Clients und Anmeldeinformationen sollten geschlossen werden, wenn sie nicht mehr benötigt werden. Diese Objekte sind asynchrone Kontext-Manager und definieren asynchrone close Methoden. Beispiel:

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:
    ...

Asynchrones Erstellen eines Geheimnisses

set_secret erstellt ein Geheimnis im Key Vault mit den angegebenen optionalen Argumenten.

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)

Asynchrones Auflisten von Geheimnissen

list_properties_of_secrets listet die Eigenschaften aller Geheimnisse im Tresor des Clients auf.

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)

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie im azure-keyvault-secretsLeitfaden zur Problembehandlung .

Allgemein

Key Vault Clients lösen ausnahmen aus, die in azure-core definiert sind. Wenn Sie beispielsweise versuchen, einen Schlüssel abzurufen, der nicht im Tresor vorhanden ist, löst SecretClientResourceNotFoundError aus:

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)

Protokollierung

Diese Bibliothek verwendet die Standardprotokollbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Die detaillierte Protokollierung auf DEBUG-Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf einem Client mit dem logging_enable -Argument aktiviert werden:

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
)

Ebenso kann über logging_enable die ausführliche Protokollierung für einen einzelnen Vorgang aktiviert werden, auch wenn diese Funktion für den Client nicht aktiviert ist:

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

Nächste Schritte

Im GitHub-Repository azure SDK für Python sind mehrere Beispiele verfügbar. Diese bieten Beispielcode für zusätzliche Key Vault Szenarien: | Datei | Beschreibung | |-------------|-------------| | hello_world.py (asynchrone Version) | Erstellen/Abrufen/Aktualisieren/Löschen von Geheimnissen | | list_operations.py (asynchrone Version) | grundlegende Listenvorgänge für Geheimnisse | | backup_restore_operations.py (asynchrone Version) | Sichern und Wiederherstellen von Geheimnissen | | recover_purge_operations.py (asynchrone Version) | Wiederherstellen und Bereinigen von Geheimnissen |

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zu Azure Key Vault finden Sie in der API-Referenzdokumentation.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Kommentare haben.