مكتبة عميل Azure Key Vault Keys ل Python - الإصدار 4.8.0
تساعد الأداة «Azure Key Vault» في حل المشكلات التالية:
- إدارة مفاتيح التشفير (هذه المكتبة) - إنشاء المفاتيح المستخدمة لتشفير بياناتك وتخزينها والتحكم فيها
- إدارة الأسرار (azure-keyvault-secrets) - تخزين الوصول إلى الرموز المميزة وكلمات المرور والشهادات ومفاتيح واجهة برمجة التطبيقات والبيانات السرية الأخرى والتحكم فيها بأمان
- إدارة الشهادات (azure-keyvault-certificates) - إنشاء شهادات SSL/TLS العامة والخاصة وإدارتها وتوزيعها
- إدارة المخزن (azure-keyvault-administration) - التحكم في الوصول استنادا إلى الدور (RBAC)، وخيارات النسخ الاحتياطي والاستعادة على مستوى المخزن
التعليمات البرمجية | المصدر الحزمة (PyPI) | حزمة (Conda) | الوثائق | المرجعية لواجهة برمجة التطبيقاتوثائق | المنتج عينات
إخلاء المسئولية
انتهى دعم حزم Azure SDK Python ل Python 2.7 في 01 يناير 2022. لمزيد من المعلومات والأسئلة، يرجى الرجوع إلى https://github.com/Azure/azure-sdk-for-python/issues/20691.
Python 3.7 أو أحدث مطلوب لاستخدام هذه الحزمة. لمزيد من التفاصيل، يرجى الرجوع إلى Azure SDK لنهج دعم إصدار Python.
الشروع في العمل
تثبيت الحِزَمة
تثبيت azure-keyvault-keysوazure-identity باستخدام pip:
pip install azure-keyvault-keys azure-identity
يتم استخدام azure-identity لمصادقة Azure Active Directory كما هو موضح أدناه.
المتطلبات الأساسية
- اشتراك Azure
- Python 3.7 أو أحدث
- Key Vault Azure موجود. إذا كنت بحاجة إلى إنشاء واحد، يمكنك القيام بذلك باستخدام Azure CLI باتباع الخطوات الواردة في هذا المستند.
- إذا كنت تستخدم HSM المدار، Key Vault HSM مدار موجود. إذا كنت بحاجة إلى إنشاء HSM مدار، يمكنك القيام بذلك باستخدام Azure CLI باتباع الخطوات الواردة في هذا المستند.
مصادقة العميل
للتفاعل مع خدمة Azure Key Vault، ستحتاج إلى مثيل KeyClient، بالإضافة إلى عنوان URL للمخزن وكائن بيانات اعتماد. يوضح هذا المستند استخدام DefaultAzureCredential، وهو مناسب لمعظم السيناريوهات، بما في ذلك بيئات التطوير والإنتاج المحلية. نوصي باستخدام هوية مدارة للمصادقة في بيئات الإنتاج.
راجع وثائق azure-identity لمزيد من المعلومات حول الأساليب الأخرى للمصادقة وأنواع بيانات الاعتماد المقابلة لها.
أنشئ عميل
بعد تكوين بيئتك ل DefaultAzureCredential لاستخدام طريقة مصادقة مناسبة، يمكنك القيام بما يلي لإنشاء عميل رئيسي (استبدال قيمة VAULT_URL بعنوان URL الخاص بالمخزن):
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = KeyClient(vault_url=VAULT_URL, credential=credential)
ملاحظه: بالنسبة لعميل غير متزامن، قم باستيراد
azure.keyvault.keys.aio'sKeyClientبدلا من ذلك.
المفاهيم الرئيسية
المفاتيح
يمكن ل Azure Key Vault إنشاء وتخزين مفاتيح المنحنى الناقص وRSA. يمكن حماية كليهما اختياريا بواسطة وحدات أمان الأجهزة (HSMs). يمكن ل Azure Key Vault أيضا تنفيذ عمليات التشفير معهم. لمزيد من المعلومات حول المفاتيح والعمليات والخوارزميات المدعومة، راجع وثائق Key Vault.
يمكن ل KeyClient إنشاء مفاتيح في المخزن، والحصول على مفاتيح موجودة من المخزن، وتحديث بيانات تعريف المفتاح، وحذف المفاتيح، كما هو موضح في الأمثلة أدناه.
أمثلة
يحتوي هذا القسم على قصاصات برمجية تغطي المهام الشائعة:
- إنشاء مفتاح
- استرداد مفتاح
- تحديث مفتاح موجود
- حذف مفتاح
- تكوين التدوير التلقائي للمفتاح
- قائمة المفاتيح
- تنفيذ عمليات التشفير
- واجهة برمجة تطبيقات المزامنة
- إنشاء مفتاح بشكل غير متزامن
- مفاتيح القوائم بشكل غير متزامن
إنشاء مفتاح
create_rsa_keycreate_ec_key إنشاء مفاتيح المنحنى الناقص وRSA في المخزن، على التوالي. إذا كان هناك مفتاح بنفس الاسم موجود بالفعل، يتم إنشاء إصدار جديد من هذا المفتاح.
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# Create an RSA key
rsa_key = key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)
# Create an elliptic curve key
ec_key = key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)
استرداد مفتاح
يسترد get_key مفتاحا تم تخزينه مسبقا في المخزن.
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
key = key_client.get_key("key-name")
print(key.name)
تحديث مفتاح موجود
يقوم update_key_properties بتحديث خصائص مفتاح تم تخزينه مسبقا في Key Vault.
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# we will now disable the key for further use
updated_key = key_client.update_key_properties("key-name", enabled=False)
print(updated_key.name)
print(updated_key.properties.enabled)
حذف مفتاح
begin_delete_key الطلبات Key Vault حذف مفتاح، مما يسمح لك بإنتظار انتهاء الحذف. يعد الانتظار مفيدا عندما يتم تمكين الحذف المبدئي للمخزن، وتريد إزالة المفتاح (حذفه نهائيا) في أقرب وقت ممكن. عند تعطيل الحذف المبدئي ، begin_delete_key يكون نفسه دائما.
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_key = key_client.begin_delete_key("key-name").result()
print(deleted_key.name)
print(deleted_key.deleted_date)
تكوين التدوير التلقائي للمفتاح
يسمح لك update_key_rotation_policy بتكوين التدوير التلقائي للمفاتيح لمفتاح عن طريق تحديد نهج التدوير. بالإضافة إلى ذلك، يسمح لك rotate_key بتدوير مفتاح عند الطلب عن طريق إنشاء إصدار جديد من المفتاح المحدد.
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient, KeyRotationLifetimeAction, KeyRotationPolicyAction
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# Set the key's automated rotation policy to rotate the key 30 days before the key expires
actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE, time_before_expiry="P30D")]
# You may also specify the duration after which the newly rotated key will expire
# In this example, any new key versions will expire after 90 days
updated_policy = key_client.update_key_rotation_policy("key-name", expires_in="P90D", lifetime_actions=actions)
# You can get the current rotation policy for a key with get_key_rotation_policy
current_policy = key_client.get_key_rotation_policy("key-name")
# Finally, you can rotate a key on-demand by creating a new version of the key
rotated_key = key_client.rotate_key("key-name")
قائمة بالمفاتيح
يسرد list_properties_of_keys خصائص جميع المفاتيح في مخزن العميل.
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()
for key in keys:
# the list doesn't include values or versions of the keys
print(key.name)
عمليات التشفير
يمكن CryptographyClient عمليات التشفير (التشفير/فك التشفير، الالتفاف/إلغاء التضمين، التوقيع/التحقق) باستخدام مفتاح معين.
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
key = key_client.get_key("key-name")
crypto_client = CryptographyClient(key, credential=credential)
plaintext = b"plaintext"
result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
decrypted = crypto_client.decrypt(result.algorithm, result.ciphertext)
راجع وثائق الحزمة لمزيد من التفاصيل عن واجهة برمجة تطبيقات التشفير.
واجهة برمجة تطبيقات المزامنة
تتضمن هذه المكتبة مجموعة كاملة من واجهات برمجة التطبيقات غير المتزامنة. لاستخدامها، يجب أولا تثبيت نقل غير متزامن، مثل aiohttp. راجع وثائق azure-core لمزيد من المعلومات.
يجب إغلاق العملاء وبيانات الاعتماد غير المتزامنة عندما لا تكون هناك حاجة إليها. هذه الكائنات هي مديري سياق غير متزامنين وتحدد أساليب غير متزامنة close . على سبيل المثال:
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient
credential = DefaultAzureCredential()
# call close when the client and credential are no longer needed
client = KeyClient(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 = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
async with credential:
...
إنشاء مفتاح بشكل غير متزامن
create_rsa_keycreate_ec_key إنشاء مفاتيح المنحنى الناقص وRSA في المخزن، على التوالي. إذا كان هناك مفتاح بنفس الاسم موجود بالفعل، يتم إنشاء إصدار جديد من المفتاح.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# Create an RSA key
rsa_key = await key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)
# Create an elliptic curve key
ec_key = await key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)
مفاتيح القوائم بشكل غير متزامن
يسرد list_properties_of_keys خصائص جميع المفاتيح في مخزن العميل.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()
async for key in keys:
print(key.name)
استكشاف الأخطاء وإصلاحها
azure-keyvault-keys راجع دليل استكشاف الأخطاء وإصلاحها للحصول على تفاصيل حول كيفية تشخيص سيناريوهات الفشل المختلفة.
عام
Key Vault العملاء رفع استثناءات محددة في azure-core. على سبيل المثال، إذا حاولت الحصول على مفتاح غير موجود في المخزن، فإن KeyClient يرفع ResourceNotFoundError:
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.core.exceptions import ResourceNotFoundError
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
try:
key_client.get_key("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.keys import KeyClient
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
client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential, logging_enable=True)
وبالمثل، logging_enable يمكن تمكين تسجيل مفصل لعملية واحدة، حتى عندما لا يتم تمكين للعميل:
client.get_key("my-key", logging_enable=True)
الخطوات التالية
تتوفر العديد من العينات في Azure SDK لمستودع Python GitHub.
توفر هذه التعليمات البرمجية مثالا لسيناريوهات Key Vault الإضافية: | ملف | الوصف | |-------------|-------------| | hello_world.py (إصدار غير متزامن) | إنشاء/الحصول/التحديث/حذف المفاتيح | | list_operations.py (إصدار غير متزامن) | عمليات القائمة الأساسية للمفاتيح | | backup_restore_operations.py (إصدار غير متزامن) | النسخ الاحتياطي واسترداد المفاتيح | | recover_purge_operations.py (إصدار غير متزامن) | استرداد المفاتيح ومسحها | | send_request.py | send_request استخدام أسلوب العميل |
وثائق إضافية
للحصول على وثائق أكثر شمولا حول Azure Key Vault، راجع الوثائق المرجعية لواجهة برمجة التطبيقات.
المساهمة
هذا المشروع يرحب بالمساهمات والاقتراحات. معظم المساهمات تتطلب منك الموافقة على اتفاقية ترخيص المساهم (CLA) التي تعلن أن لديك الحق في منحنا حق استخدام مساهمتك. لمزيد من التفاصيل، قم بزيارة https://cla.microsoft.com.
عند إرسال طلب سحب، سيحدد روبوت CLA-bot تلقائيًا ما إذا كنت بحاجة إلى تقديم CLA وتزيين العلاقات العامة بشكل مناسب (على سبيل المثال، التسمية أو التعليق). ما عليك سوى اتباع التعليمات التي يقدمها الروبوت. ستحتاج فقط إلى القيام بذلك مرة واحدة عبر جميع عمليات إعادة الشراء باستخدام CLA الخاص بنا.
اعتمد هذا المشروع مدونة السلوك من المصادر المفتوحة من Microsoft. لمزيد من المعلومات، راجع الأسئلة الشائعة حول مدونة قواعد السلوك أو الاتصال بأي أسئلة أو تعليقات opencode@microsoft.com إضافية.
Azure SDK for Python
الملاحظات
قريبًا: خلال عام 2024، سنتخلص تدريجيًا من GitHub Issues بوصفها آلية إرسال ملاحظات للمحتوى ونستبدلها بنظام ملاحظات جديد. لمزيد من المعلومات، راجع https://aka.ms/ContentUserFeedback.
إرسال الملاحظات وعرضها المتعلقة بـ