مشاركة عبر

مكتبة عميل Azure Key Vault Secrets ل Python - الإصدار 4.7.0

  • مقالة

تساعد الأداة «Azure Key Vault» في حل المشكلات التالية:

  • إدارة الأسرار (هذه المكتبة) - تخزين الوصول إلى الرموز المميزة وكلمات المرور والشهادات ومفاتيح API والأسرار الأخرى والتحكم فيها بأمان
  • إدارة مفاتيح التشفير (azure-keyvault-keys) - إنشاء وتخزين والتحكم في الوصول إلى المفاتيح المستخدمة لتشفير بياناتك
  • إدارة الشهادات (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-secretsوazure-identity باستخدام pip:

pip install azure-keyvault-secrets azure-identity

يتم استخدام azure-identity لمصادقة Azure Active Directory كما هو موضح أدناه.

المتطلبات الأساسية

مصادقة العميل

للتفاعل مع خدمة Azure Key Vault، ستحتاج إلى مثيل SecretClient، بالإضافة إلى عنوان URL للمخزن وكائن بيانات اعتماد. يوضح هذا المستند استخدام DefaultAzureCredential، وهو مناسب لمعظم السيناريوهات، بما في ذلك بيئات التطوير والإنتاج المحلية. نوصي باستخدام هوية مدارة للمصادقة في بيئات الإنتاج.

راجع وثائق هوية azure لمزيد من المعلومات حول أساليب المصادقة الأخرى وأنواع بيانات الاعتماد المقابلة لها.

أنشئ عميل

بعد تكوين بيئتك ل DefaultAzureCredential لاستخدام طريقة مناسبة للمصادقة، يمكنك القيام بما يلي لإنشاء عميل سري (استبدال قيمة VAULT_URL بعنوان URL الخاص بالمخزن):

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

ملاحظه: بالنسبة لعميل غير متزامن، قم باستيراد azure.keyvault.secrets.aio's SecretClient بدلا من ذلك.

المفاهيم الرئيسية

سري

يتكون السر من قيمة سرية وبيانات التعريف ومعلومات الإدارة المرتبطة بها. تتعامل هذه المكتبة مع القيم السرية كسلاسل، ولكن Azure Key Vault لا يخزنها على هذا النحو. لمزيد من المعلومات حول الأسرار وكيفية تخزينها Key Vault وإدارتها، راجع وثائق Key Vault.

يمكن ل SecretClient تعيين قيم سرية في المخزن، وتحديث بيانات التعريف السرية، وحذف الأسرار، كما هو موضح في الأمثلة أدناه.

أمثلة

يحتوي هذا القسم على قصاصات برمجية تغطي المهام الشائعة:

تعيين سر

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)

واجهة برمجة تطبيقات المزامنة

تتضمن هذه المكتبة مجموعة كاملة من واجهات برمجة التطبيقات غير المتزامنة. لاستخدامها، يجب أولا تثبيت نقل غير متزامن، مثل 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.

يمكن تمكين تسجيل مستوى تتبع الأخطاء المفصل، بما في ذلك هيئات الطلب/الاستجابة والعناوين غير النشطة، على عميل باستخدام الوسيطة 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)

الخطوات التالية

تتوفر العديد من العينات في مستودع Azure SDK ل Python GitHub. توفر هذه التعليمات البرمجية مثالا لسيناريوهات Key Vault الإضافية: | ملف | الوصف | |-------------|-------------| | hello_world.py (إصدار غير متزامن) | إنشاء/الحصول/التحديث/حذف البيانات السرية | | list_operations.py (إصدار غير متزامن) | عمليات القائمة الأساسية للبيانات السرية | | backup_restore_operations.py (إصدار غير متزامن) | نسخ البيانات السرية احتياطيا واستعادتها | | recover_purge_operations.py (إصدار غير متزامن) | استرداد البيانات السرية ومسحها |

وثائق إضافية

للحصول على وثائق أكثر شمولا حول Azure Key Vault، راجع الوثائق المرجعية لواجهة برمجة التطبيقات.

المساهمة

هذا المشروع يرحب بالمساهمات والاقتراحات. معظم المساهمات تتطلب منك الموافقة على اتفاقية ترخيص المساهم (CLA) التي تعلن أن لديك الحق في منحنا حق استخدام مساهمتك. لمزيد من التفاصيل، قم بزيارة https://cla.microsoft.com.

عند إرسال طلب سحب، سيحدد روبوت CLA-bot تلقائيًا ما إذا كنت بحاجة إلى تقديم CLA وتزيين العلاقات العامة بشكل مناسب (على سبيل المثال، التسمية أو التعليق). ما عليك سوى اتباع التعليمات التي يقدمها الروبوت. ستحتاج فقط إلى القيام بذلك مرة واحدة عبر جميع عمليات إعادة الشراء باستخدام CLA الخاص بنا.

اعتمد هذا المشروع مدونة السلوك من المصادر المفتوحة من Microsoft. لمزيد من المعلومات، راجع الأسئلة الشائعة حول مدونة قواعد السلوك أو الاتصال بأي أسئلة أو تعليقات opencode@microsoft.com إضافية.

مرات الظهور