مشاركة عبر

التشغيل السريع: Azure Cosmos DB ل MongoDB ل Python مع برنامج تشغيل MongoDB

  • مقالة

ينطبق على: MongoDB

ابدأ باستخدام MongoDB لإنشاء قواعد البيانات والمجموعات والمستندات داخل مورد Azure Cosmos DB. اتبع هذه الخطوات لنشر الحد الأدنى من الحل إلى البيئة الخاصة بك باستخدام Azure Developer CLI.

API للوثائق المرجعية ل MongoDB حزمة | pymongo Azure Developer CLI |

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

الإعداد

نشر حاوية تطوير هذا المشروع إلى البيئة الخاصة بك. ثم استخدم Azure Developer CLI (azd) لإنشاء Azure Cosmos DB لحساب MongoDB ونشر نموذج تطبيق حاوية. يستخدم نموذج التطبيق مكتبة العميل لإدارة البيانات النموذجية وإنشاءها وقراءتها والاستعلام عن البيانات.

فتح في GitHub Codespaces

فتح في حاوية Dev

هام

تتضمن حسابات GitHub استحقاق التخزين والساعات الأساسية دون أي تكلفة. لمزيد من المعلومات، راجع التخزين المضمن والساعات الأساسية لحسابات GitHub.

  1. افتح محطة طرفية في الدليل الجذر للمشروع.

  2. المصادقة على Azure Developer CLI باستخدام azd auth login. اتبع الخطوات المحددة بواسطة الأداة للمصادقة على CLI باستخدام بيانات اعتماد Azure المفضلة لديك.

    azd auth login

  3. استخدم azd init لتهيئة المشروع.

    azd init --template cosmos-db-mongodb-python-quickstart

    إشعار

    يستخدم هذا التشغيل السريع مستودع GitHub لقالب azure-samples/cosmos-db-mongodb-python-quickstart . يقوم Azure Developer CLI تلقائيا باستنساخ هذا المشروع إلى جهازك إذا لم يكن موجودا بالفعل.

  4. أثناء التهيئة، قم بتكوين اسم بيئة فريد.

    تلميح

    سيتم أيضا استخدام اسم البيئة كاسم مجموعة الموارد الهدف. لهذا التشغيل السريع، ضع في اعتبارك استخدام msdocs-cosmos-db.

  5. انشر حساب Azure Cosmos DB باستخدام azd up. تنشر قوالب Bicep أيضا نموذج تطبيق ويب.

    azd up

  6. أثناء عملية التوفير، حدد اشتراكك والموقع المطلوب. انتظر حتى اكتمال عملية التوفير. قد تستغرق العملية حوالي خمس دقائق.

  7. بمجرد توفير موارد Azure الخاصة بك، يتم تضمين عنوان URL لتطبيق الويب قيد التشغيل في الإخراج.

    Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

  8. استخدم عنوان URL في وحدة التحكم للانتقال إلى تطبيق الويب الخاص بك في المستعرض. لاحظ إخراج التطبيق قيد التشغيل.

    لقطة شاشة لتطبيق الويب قيد التشغيل.

تثبيت مكتبة العميل

  1. requirements.txt إنشاء ملف في دليل التطبيق الخاص بك يسرد حزم PyMongo وpython-dotenv.

    # requirements.txt
pymongo
python-dotenv

  2. إنشاء بيئة ظاهرية وتثبيت الحزم.

    # py -3 uses the global python interpreter. You can also use python3 -m venv .venv.
py -3 -m venv .venv
source .venv/Scripts/activate   
pip install -r requirements.txt

نموذج الكائن

لنلق نظرة على التسلسل الهرمي للموارد في واجهة برمجة التطبيقات ل MongoDB ونموذج العنصر المستخدم لإنشاء هذه الموارد والوصول إليها. ينشئ Azure Cosmos DB موارد في تسلسل هرمي يتكون من حسابات وقواعد بيانات ومجموعات ومستندات.

رسم تخطيطي لتدرج Azure Cosmos DB الهرمي بما في ذلك الحسابات وقواعد البيانات والمجموعات والمستندات.

يتم تمثيل كل نوع من أنواع الموارد بواسطة فئة Python. فيما يلي الفئات الأكثر شيوعا:

  • MongoClient - الخطوة الأولى عند العمل مع PyMongo هي إنشاء MongoClient للاتصال بواجهة برمجة تطبيقات Azure Cosmos DB ل MongoDB. يتم استخدام كائن العميل لتكوين الطلبات وتنفيذها على الخدمة.

  • قاعدة البيانات - يمكن أن تدعم واجهة برمجة تطبيقات Azure Cosmos DB ل MongoDB قاعدة بيانات مستقلة واحدة أو أكثر.

  • المجموعة - يمكن أن تحتوي قاعدة البيانات على مجموعة واحدة أو أكثر. المجموعة هي مجموعة من المستندات المخزنة في MongoDB، ويمكن اعتبارها مكافئة تقريبا لجدول في قاعدة بيانات ارتباطية.

  • المستند - المستند عبارة عن مجموعة من أزواج قيم المفاتيح. تحتوي المستندات على مخطط ديناميكي. يعني المخطط الديناميكي أن المستندات في نفس المجموعة لا تحتاج إلى نفس مجموعة الحقول أو البنية. وقد تحتوي الحقول الشائعة في مستندات المجموعة على أنواع مختلفة من البيانات.

لمعرفة المزيد عن التسلسل الهرمي للكيانات، راجع مقالة نموذج مورد Azure Cosmos DB.

أمثلة على التعليمات البرمجية

ينشئ نموذج التعليمات البرمجية الموضح في هذه المقالة قاعدة بيانات مسماة adventureworks بحاوية مُسماة products. تم تصميم المجموعة products لتحتوي على تفاصيل المنتج مثل الاسم والفئة والكمية ومؤشر البيع. يحتوي كل منتج أيضًا على معرّف فريد. نموذج التعليمات البرمجية الكامل في https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/.

بالنسبة للخطوات أدناه، لن تستخدم قاعدة البيانات التقسيم وتعرض تطبيقا متزامنا باستخدام برنامج تشغيل PyMongo . بالنسبة للتطبيقات غير المتزامنة، استخدم برنامج تشغيل المحرك .

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

  1. في دليل المشروع، قم بإنشاء ملف run.py . في المحرر، أضف عبارات تتطلب للإشارة إلى الحزم التي ستستخدمها، بما في ذلك حزم PyMongo وpython-dotenv.

    import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv

  2. احصل على معلومات الاتصال من متغير البيئة المحدد في ملف .env .

    load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")

  3. حدد الثوابت التي ستستخدمها في التعليمات البرمجية.

    DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

الاتصال بواجهة برمجة تطبيقات Azure Cosmos DB ل MongoDB

استخدم كائن MongoClient للاتصال بمورد Azure Cosmos DB ل MongoDB. يقوم أسلوب الاتصال بإرجاع مرجع إلى قاعدة البيانات.

client = pymongo.MongoClient(CONNECTION_STRING)

الحصول على قاعدة بيانات

تحقق مما إذا كانت قاعدة البيانات موجودة باستخدام أسلوب list_database_names . إذا لم تكن قاعدة البيانات موجودة، فاستخدم الأمر إنشاء ملحق قاعدة بيانات لإنشائها بمعدل نقل محدد تم توفيره.

# Create database if it doesn't exist
db = client[DB_NAME]
if DB_NAME not in client.list_database_names():
    # Create a database with 400 RU throughput that can be shared across
    # the DB's collections
    db.command({"customAction": "CreateDatabase", "offerThroughput": 400})
    print("Created db '{}' with shared throughput.\n".format(DB_NAME))
else:
    print("Using database: '{}'.\n".format(DB_NAME))

الحصول على المجموعة

تحقق مما إذا كانت المجموعة موجودة باستخدام أسلوب list_collection_names . إذا لم تكن المجموعة موجودة، فاستخدم الأمر إنشاء ملحق المجموعة لإنشائها.

# Create collection if it doesn't exist
collection = db[COLLECTION_NAME]
if COLLECTION_NAME not in db.list_collection_names():
    # Creates a unsharded collection that uses the DBs shared throughput
    db.command(
        {"customAction": "CreateCollection", "collection": COLLECTION_NAME}
    )
    print("Created collection '{}'.\n".format(COLLECTION_NAME))
else:
    print("Using collection: '{}'.\n".format(COLLECTION_NAME))

إنشاء فهرس

إنشاء فهرس باستخدام الأمر ملحق مجموعة التحديث. يمكنك أيضا تعيين الفهرس في الأمر إنشاء ملحق المجموعة. قم بتعيين الفهرس إلى name الخاصية في هذا المثال بحيث يمكنك الفرز لاحقا باستخدام أسلوب فرز فئة المؤشر على اسم المنتج.

indexes = [
    {"key": {"_id": 1}, "name": "_id_1"},
    {"key": {"name": 2}, "name": "_id_2"},
]
db.command(
    {
        "customAction": "UpdateCollection",
        "collection": COLLECTION_NAME,
        "indexes": indexes,
    }
)
print("Indexes are: {}\n".format(sorted(collection.index_information())))

إنشاء مستند

إنشاء مستند بخصائص المنتج لقاعدة adventureworks البيانات:

  • * خاصية الفئة. يمكن استخدام هذه الخاصية كمفتاح القسم المنطقي.
  • * خاصية الاسم.
  • * خاصية كمية المخزون.
  • * خاصية البيع، مما يشير إلى ما إذا كان المنتج قيد البيع.
"""Create new document and upsert (create or replace) to collection"""
product = {
    "category": "gear-surf-surfboards",
    "name": "Yamba Surfboard-{}".format(randint(50, 5000)),
    "quantity": 1,
    "sale": False,
}
result = collection.update_one(
    {"name": product["name"]}, {"$set": product}, upsert=True
)
print("Upserted document with _id {}\n".format(result.upserted_id))

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

تحتوي نتيجة update_one العملية على _id قيمة الحقل التي يمكنك استخدامها في العمليات اللاحقة. تم إنشاء الخاصية _id تلقائيا.

الحصول على مستند

استخدم أسلوب find_one للحصول على مستند.

doc = collection.find_one({"_id": result.upserted_id})
print("Found a document with _id {}: {}\n".format(result.upserted_id, doc))

في Azure Cosmos DB، يمكنك تنفيذ عملية قراءة نقطة أقل تكلفة باستخدام كل من المعرف الفريد (_id) ومفتاح القسم.

الاستعلام عن المستندات

بعد إدراج مستند، يمكنك تشغيل استعلام للحصول على كافة المستندات التي تطابق عامل تصفية معينًا. يبحث هذا المثال عن كافة المستندات التي تطابق فئة محددة: gear-surf-surfboards. بمجرد تعريف الاستعلام، اتصل Collection.find للحصول على نتيجة Cursor ، ثم استخدم الفرز.

"""Query for documents in the collection"""
print("Products with category 'gear-surf-surfboards':\n")
allProductsQuery = {"category": "gear-surf-surfboards"}
for doc in collection.find(allProductsQuery).sort(
    "name", pymongo.ASCENDING
):
    print("Found a product with _id {}: {}\n".format(doc["_id"], doc))

استكشاف الأخطاء وإصلاحها:

  • إذا تلقيت خطأ مثل The index path corresponding to the specified order-by item is excluded.، فتأكد من إنشاء الفهرس.

تشغيل التعليمات البرمجية

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

لتشغيل التطبيق، استخدم terminal للانتقال إلى دليل التطبيق وتشغيل التطبيق.

python run.py

يجب أن يكون إخراج التطبيق مشابهًا لهذا المثال:


Created db 'adventureworks' with shared throughput.

Created collection 'products'.

Indexes are: ['_id_', 'name_1']

Upserted document with _id <ID>

Found a document with _id <ID>:
{'_id': <ID>,
'category': 'gear-surf-surfboards',
'name': 'Yamba Surfboard-50',
'quantity': 1,
'sale': False}

Products with category 'gear-surf-surfboards':

Found a product with _id <ID>:
{'_id': ObjectId('<ID>'),
'name': 'Yamba Surfboard-386',
'category': 'gear-surf-surfboards',
'quantity': 1,
'sale': False}

تنظيف الموارد

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

استخدم الأمر az group delete لحذف مجموعة الموارد.

az group delete --name $resourceGroupName