بدء استخدام Azure Cosmos DB ل NoSQL باستخدام Python

ينطبق على: NoSQL

توضح هذه المقالة كيفية الاتصال ب Azure Cosmos DB ل NoSQL باستخدام Python SDK. بمجرد الاتصال، يمكنك إجراء عمليات على قواعد البيانات والحاويات والعناصر.

Package (PyPi) | Samples | API reference | Library source code | Give Feedback

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

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• Azure Cosmos DB لحساب NoSQL. إنشاء واجهة برمجة تطبيقات لحساب NoSQL.
• Python 3.7 أو أحدث
• واجهة سطر الأوامر من Azure (واجهة مستوى الاستدعاء) أو Azure PowerShell

إعداد مشروعك

إنشاء بيئة يمكنك تشغيل تعليمة Python البرمجية فيها.

البيئة الظاهرية

مع بيئة ظاهرية، يمكنك تثبيت حزم Python في بيئة معزولة دون التأثير على بقية النظام الخاص بك.

تثبيت Azure Cosmos DB ل NoSQL Python SDK في البيئة الظاهرية.

pip install azure-cosmos

حاوية التطوير

حاوية التطوير هي بيئة مكونة مسبقا يمكنك استخدامها لتشغيل التعليمات البرمجية ل Python.

لتشغيل حاوية تطوير، يمكنك استخدام:

• Visual Studio Code: انسخ هذا المستودع إلى جهازك المحلي وافتح المجلد باستخدام ملحق حاويات Dev.

• GitHub Codespaces: افتح هذا المستودع في المتصفح باستخدام GitHub codespace.

قم بتثبيت Azure Cosmos DB ل NoSQL Python SDK في حاوية التطوير.

pip install azure-cosmos

إنشاء تطبيق Python

في بيئتك، قم بإنشاء ملف app.py جديد وأضف التعليمات البرمجية التالية إليه:

import json
import os
import sys
import uuid

from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey

تستورد التعليمات البرمجية السابقة الوحدات النمطية التي ستستخدمها في بقية المقالة.

الاتصال ب Azure Cosmos DB ل NoSQL

للاتصال بواجهة برمجة التطبيقات ل NoSQL ل Azure Cosmos DB، أنشئ مثيلا لفئة CosmosClient . هذه الفئة هي نقطة البداية لتنفيذ جميع العمليات الخاصة بقواعد البيانات. هناك ثلاث طرق للاتصال بواجهة برمجة تطبيقات لحساب NoSQL باستخدام فئة CosmosClient :

• الاتصال بمعرف Microsoft Entra (مستحسن)
• الاتصال بواجهة برمجة تطبيقات لنقطة نهاية NoSQL ومفتاح القراءة/الكتابة
• الاتصال بواجهة برمجة تطبيقات ل NoSQL سلسلة الاتصال

الاتصال بإحدى نقاط النهاية وأحد المفاتيح

يحتوي المنشئ ل CosmosClient على معلمتين مطلوبتين:

المعلمة‬	قيمة المثال	‏‏الوصف
url	متغير البيئة COSMOS_ENDPOINT	واجهة برمجة التطبيقات لنقطة نهاية NoSQL لاستخدامها لجميع الطلبات.
credential	متغير البيئة COSMOS_KEY	مفتاح الحساب أو الرمز المميز للمورد لاستخدامه عند المصادقة.

استرداد نقطة نهاية حسابك ومفتاحه

Azure CLI

1. إنشاء متغير shell لدى resourceGroupName.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-python-howto-rg"
   

2. استخدم الأمر az cosmosdb list لاسترداد اسم حساب Azure Cosmos DB الأول في مجموعة الموارد وتخزينه في متغير accountName shell.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

3. احصل على واجهة برمجة التطبيقات لنقطة نهاية NoSQL URI للحساب باستخدام az cosmosdb show الأمر .

   az cosmosdb show \
       --resource-group $resourceGroupName \
       --name $accountName \
       --query "documentEndpoint"
   

4. ابحث عن PRIMARY KEY من قائمة مفاتيح الحساب باستخدام الأمر az-cosmosdb-keys-list.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "keys" \
       --query "primaryMasterKey"
   

5. سجل قيم URI وPRIMARY KEY. سوف تستخدم بيانات الاعتماد هذه لاحقًا.

بوويرشيل

1. إنشاء متغير shell لدى RESOURCE_GROUP_NAME.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos-python-howto-rg"
   

2. استخدم الأمر Get-AzCosmosDBAccount cmdlet لاسترداد اسم حساب Azure Cosmos DB الأول في مجموعة الموارد وتخزينه في متغير ACCOUNT_NAME shell.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

3. احصل على واجهة برمجة التطبيقات لنقطة نهاية NoSQL URI للحساب باستخدام Get-AzCosmosDBAccount cmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
   }
   Get-AzCosmosDBAccount @parameters |
       Select-Object -Property "DocumentEndpoint"
   

4. ابحث عن PRIMARY KEY من قائمة مفاتيح الحساب باستخدام الأمر Get-AzCosmosDBAccountKey cmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "Keys"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "PrimaryMasterKey"
   

5. سجل قيم URI وPRIMARY KEY. سوف تستخدم بيانات الاعتماد هذه لاحقًا.

بوابة

تلميح

نوصي باستخدام اسم مجموعة الموارد msdocs-cosmos-python-howto-rgفي هذا الدليل.

1. قم بتسجيل الدخول إلى بوابة Azure.

2. انتقل إلى صفحة حساب Azure Cosmos DB for NoSQL الموجودة.

3. من صفحة حساب Azure Cosmos DB for NoSQL، حدد خيار قائمة التنقل Keys .

   

4. سجل القيم من حقلي URI وPRIMARY KEY. سوف تستخدم هذه القيم في خطوة لاحقة.

   

لاستخدام قيم URI و PRIMARY KEY داخل التعليمات البرمجية ل Python، استمر في استخدام متغيرات البيئة الجديدة على الجهاز المحلي الذي يقوم بتشغيل التطبيق.

Windows

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Linux / macOS

export COSMOS_ENDPOINT="<cosmos-account-URI>"
export COSMOS_KEY="<cosmos-account-PRIMARY-KEY>"

إنشاء CosmosClient باستخدام نقطة نهاية الحساب ومفتاحه

إنشاء مثيل جديد من فئة CosmosClient مع متغيرات البيئة COSMOS_ENDPOINT وCOSMOS_KEY كمعلمات.

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
KEY = os.environ["COSMOS_KEY"]

client = CosmosClient(url=ENDPOINT, credential=KEY)

الاتصال بسلسلة الاتصال

تحتوي فئة CosmosClient على أسلوب from_connection_string يمكنك استخدامه للاتصال بمعلمة واحدة مطلوبة:

المعلمة‬	قيمة المثال	‏‏الوصف
conn_str	متغير البيئة COSMOS_CONNECTION_STRING	سلسلة الاتصال إلى API لحساب NoSQL.
credential	متغير البيئة COSMOS_KEY	مفتاح حساب بديل اختياري أو رمز مميز للمورد لاستخدامه بدلا من مفتاح الحساب في سلسلة الاتصال.

استرداد سلسلة الاتصال حسابك

Azure CLI

1. استخدم الأمر az cosmosdb list لاسترداد اسم حساب Azure Cosmos DB الأول في مجموعة الموارد وتخزينه في متغير accountName shell.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

2. ابحث عن سلسلة الاتصال PRIMARY CONNECTION STRING من قائمة سلاسل الاتصال للحساب باستخدام الأمر az-cosmosdb-keys-list.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "connection-strings" \
       --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
   

بوويرشيل

1. استخدم الأمر Get-AzCosmosDBAccount cmdlet لاسترداد اسم حساب Azure Cosmos DB الأول في مجموعة الموارد وتخزينه في متغير ACCOUNT_NAME shell.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

2. ابحث عن سلسلة الاتصال PRIMARY CONNECTION STRING من قائمة سلاسل الاتصال للحساب باستخدام Get-AzCosmosDBAccountKey cmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary SQL Connection String" -First 1    
   

بوابة

تلميح

نوصي باستخدام اسم مجموعة الموارد msdocs-cosmos-python-howto-rgفي هذا الدليل.

1. قم بتسجيل الدخول إلى بوابة Azure.

2. انتقل إلى صفحة حساب Azure Cosmos DB for NoSQL الموجودة.

3. من صفحة حساب Azure Cosmos DB for NoSQL، حدد خيار قائمة التنقل Keys .

4. سجل القيمة من حقل PRIMARY CONNECTION STRING.

لاستخدام قيمة PRIMARY CONNECTION STRING ضمن التعليمات البرمجية ل Python، استمر في ذلك إلى متغير بيئة جديد على الجهاز المحلي الذي يقوم بتشغيل التطبيق.

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

إنشاء CosmosClient باستخدام سلسلة الاتصال

إنشاء مثيل جديد من فئة CosmosClient باستخدام متغير البيئة COSMOS_CONNECTION_STRING باعتباره المعلمة الوحيدة.

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

الاتصال باستخدام النظام الأساسي للهويات في Microsoft (مستحسن)

للاتصال بواجهة برمجة التطبيقات الخاصة بك لحساب NoSQL باستخدام النظام الأساسي للهويات في Microsoft ومعرف Microsoft Entra، استخدم أساس أمان. سيعتمد النوع الدقيق للحساب الأساسي على المكان الذي تستضيف فيه التعليمات البرمجية للتطبيق الخاص بك. الجدول التالي دليل مرجعي سريع.

مكان تشغيل التطبيق	أساس الأمان
جهاز محلي (تطوير واختبار)	هوية المستخدم أو كيان الخدمة
Azure	الهوية المُدارة
الخوادم أو العملاء خارج Azure	كيان الخدمة

قم باستيراد حزمة Azure.Identity

تحتوي حزمة azure-identity على وظيفة المصادقة الأساسية التي تتم مشاركتها بين جميع مكتبات Azure SDK.

استيراد حزمة azure-identity إلى بيئتك.

pip install azure-identity

قم بإنشاء CosmosClient عن طريق تنفيذ بيانات الاعتماد الافتراضية

إذا كنت تجري الاختبار على جهاز محلي، أو سيتم تشغيل تطبيقك على خدمات Azure بدعم مباشر للهويات المدارة، فاحصل على رمز OAuth المميز عن طريق إنشاء مثيل DefaultAzureCredential.

في app.py:

• احصل على نقطة النهاية للاتصال كما هو موضح في القسم أعلاه للاتصال بنقطة نهاية ومفتاح وتعيين ذلك كمتغير COSMOS_ENDPOINTالبيئة .

• استيراد DefaultAzureCredential وإنشاء مثيل له.

• إنشاء مثيل جديد من فئة CosmosClient باستخدام نقطة النهاية وبيانات الاعتماد كمعلمات.

from azure.identity import DefaultAzureCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]

credential = DefaultAzureCredential()

client = CosmosClient(ENDPOINT, credential)

هام

للحصول على تفاصيل حول كيفية إضافة الدور الصحيح لتمكين DefaultAzureCredential العمل، راجع تكوين التحكم في الوصول المستند إلى الدور باستخدام معرف Microsoft Entra لحساب Azure Cosmos DB الخاص بك. على وجه الخصوص، راجع القسم الخاص بإنشاء الأدوار وتعيينها إلى معرف أساسي.

قم بإنشاء CosmosClient عن طريق تنفيذ بيانات الاعتماد المخصصة

إذا كنت تخطط لنشر التطبيق من Azure، يمكنك الحصول على رمز OAuth المميز باستخدام فئات أخرى في مكتبة عميل Azure.Identity ل Python. هذه الفئات الأخرى مشتقة من الفئة TokenCredential أيضاً.

على سبيل المثال، نقوم بإنشاء مثيل ClientSecretCredential باستخدام معرفات العميل والمستأجر، بالإضافة إلى سر العميل.

في app.py:

• احصل على معلومات بيانات الاعتماد من متغيرات البيئة لمدير الخدمة. يمكنك الحصول على معرف العميل ومعرف المستأجر وسر العميل عند تسجيل تطبيق في معرف Microsoft Entra. لمزيد من المعلومات حول تسجيل تطبيقات Microsoft Entra، راجع تسجيل تطبيق مع النظام الأساسي للهويات في Microsoft.

• استيراد ClientSecretCredential وإنشاء مثيل مع CLIENT_IDTENANT_IDمتغيرات البيئة و و CLIENT_SECRET كمعلمات.

• إنشاء مثيل جديد من فئة CosmosClient باستخدام نقطة النهاية وبيانات الاعتماد كمعلمات.

from azure.identity import ClientSecretCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
TENANT_ID = os.environ["TENANT_ID"]
CLIENT_ID = os.environ["CLIENT_ID"]
CLIENT_SECRET = os.environ["CLIENT_SECRET"]

credential = ClientSecretCredential(
    tenant_id=TENANT_ID, client_id=CLIENT_ID, client_secret=CLIENT_SECRET
)

client = CosmosClient(ENDPOINT, credential)

إنشاء التطبيق الخاص بك

في أثناء إنشاء تطبيقك، سوف تتفاعل التعليمة البرمجية الخاصة بك في المقام الأول مع أربعة أنواع من الموارد:

• واجهة برمجة التطبيقات لحساب NoSQL، وهي مساحة الاسم الفريدة ذات المستوى الأعلى لبيانات Azure Cosmos DB.

• قواعد البيانات، وهي تنظم الحاويات في حسابك.

• الحاويات، وهي تحتوي على مجموعة من العناصر الفردية في قاعدة البيانات الخاصة بك.

• العناصر، وهي تمثل مستند JSON في الحاوية الخاصة بك.

يعرض الرسم التخطيطي التالي العلاقة بين هذه الموارد.

رسم تخطيطي هرمي يظهر حساب قاعدة بيانات Azure Cosmos في الأعلى. يحتوي الحساب على عقدتين تابعتين لقاعدة البيانات. تتضمن إحدى عُقد قاعدة البيانات عقدتين تابعتين للحاوية. تتضمن عقدة قاعدة البيانات الأخرى عقدة حاوية تابعة واحدة. تحتوي عقدة الحاوية المفردة على ثلاث عُقد عناصر تابعة.

يتم تمثيل كل نوع من أنواع الموارد بفئة Python مقترنة واحدة أو أكثر. فيما يلي قائمة بالفئات الأكثر شيوعا للبرمجة المتزامنة. (هناك فئات مماثلة للبرمجة غير المتزامنة ضمن مساحة الاسم azure.cosmos.aio .)

الفصل	‏‏الوصف
CosmosClient	توفر هذه الفئة تمثيلاً منطقياً من جانب العميل لخدمة Azure Cosmos DB. يتم استخدام كائن العميل لتكوين الطلبات وتنفيذها على الخدمة.
DatabaseProxy	واجهة لقاعدة بيانات قد تكون موجودة أو لا توجد في الخدمة حتى الآن. لا يجب إنشاء مثيل لهذه الفئة مباشرة. بدلا من ذلك، يجب استخدام أسلوب get_database_client CosmosClient.
ContainerProxy	واجهة للتفاعل مع حاوية Cosmos DB معينة. لا يجب إنشاء مثيل لهذه الفئة مباشرة. بدلا من ذلك، استخدم أسلوب get_container_client DatabaseProxy للحصول على حاوية موجودة، أو أسلوب create_container لإنشاء حاوية جديدة.

توضح لك الأدلة التالية كيفية استخدام كل فئة من هذه الفئات لإنشاء التطبيق الخاص بك.

الدليل:	‏‏الوصف
إنشاء قاعدة بيانات	إنشاء قواعد بيانات
إنشاء حاوية	إنشاء حاويات
أمثلة العنصر	نقطة قراءة عنصر معين

(راجع أيضًا )

• PyPi
• العينات
• مرجع واجهة برمجة التطبيقات
• التعليمات البرمجية لمصدر للمكتبة
• تقديم ملاحظات

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

الآن بعد أن قمت بالاتصال بواجهة برمجة تطبيقات لحساب NoSQL، استخدم الدليل التالي لإنشاء قواعد البيانات وإدارتها.

إنشاء قاعدة بيانات في Azure Cosmos DB ل NoSQL باستخدام Python