مشاركة عبر

إخلاء المسئولية

  • مقالة

انتهى دعم حزم Azure SDK Python ل Python 2.7 في 01 يناير 2022. لمزيد من المعلومات والأسئلة، يرجى الرجوع إلى https://github.com/Azure/azure-sdk-for-python/issues/20691

مكتبة عميل Azure Cosmos DB SQL API ل Python - الإصدار 4.5.1

Azure Cosmos DB هي قاعدة بيانات متعددة النماذج موزعة عالميًا تدعم الوثائق والقيم المفتاحية والعمود العريض وقواعد البيانات الرسومية.

استخدم Azure Cosmos DB SQL API SDK ل Python لإدارة قواعد البيانات ومستندات JSON التي تحتوي عليها في خدمة قاعدة بيانات NoSQL هذه. القدرات عالية المستوى هي:

  • إنشاء قواعد بيانات Cosmos DB وتعديل إعداداتها
  • إنشاء حاويات وتعديلها لتخزين مجموعات من مستندات JSON
  • إنشاء العناصر (مستندات JSON) وقراءتها وتحديثها وحذفها في حاوياتك
  • الاستعلام عن المستندات في قاعدة البيانات باستخدام بناء جملة يشبه SQL

التعليمات البرمجية | المصدر ل SDKالحزمة (PyPI) | حزمة (Conda) | الوثائق | المرجعية لواجهة برمجة التطبيقاتوثائق | المنتجعينات

يتم استخدام SDK هذا لواجهة برمجة تطبيقات SQL. بالنسبة لجميع واجهات برمجة التطبيقات الأخرى، يرجى التحقق من وثائق Azure Cosmos DB لتقييم أفضل SDK لمشروعك.

الشروع في العمل

تحديث هام لدعم Python 2.x

لن تدعم الإصدارات الجديدة من SDK Python 2.x بدءًا من 1 يناير 2022. الرجاء التحقق من CHANGELOG للحصول على مزيد من المعلومات.

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

إذا كنت بحاجة إلى حساب Cosmos DB SQL API، يمكنك إنشاء حساب باستخدام أمر Azure CLI هذا:

az cosmosdb create --resource-group <resource-group-name> --name <cosmos-account-name>

تثبيت الحِزَمة

pip install azure-cosmos

تكوين بيئة ظاهرية (اختياري)

على الرغم من أنه ليس مطلوبا، يمكنك الاحتفاظ بالنظام الأساسي وبيئات Azure SDK معزولة عن بعضها البعض إذا كنت تستخدم بيئة ظاهرية. نفذ الأوامر التالية لتكوين ثم أدخل بيئة ظاهرية باستخدام venv:

python3 -m venv azure-cosmosdb-sdk-environment
source azure-cosmosdb-sdk-environment/bin/activate

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

يبدأ التفاعل مع Cosmos DB بمثيل فئة CosmosClient . تحتاج إلى حسابوURI الخاص به وأحد مفاتيح الحساب الخاصة به لإنشاء مثيل لكائن العميل.

استخدم مقتطف Azure CLI أدناه لملء متغيرين للبيئة باستخدام URI لحساب قاعدة البيانات والمفتاح الرئيسي الأساسي الخاص به (يمكنك أيضا العثور على هذه القيم في مدخل Microsoft Azure). يُنسق المقتطف لـBash shell.

RES_GROUP=<resource-group-name>
ACCT_NAME=<cosmos-db-account-name>

export ACCOUNT_URI=$(az cosmosdb show --resource-group $RES_GROUP --name $ACCT_NAME --query documentEndpoint --output tsv)
export ACCOUNT_KEY=$(az cosmosdb list-keys --resource-group $RES_GROUP --name $ACCT_NAME --query primaryMasterKey --output tsv)

إنشاء العميل

بمجرد ملء ACCOUNT_URI متغيري البيئة و ACCOUNT_KEY ، يمكنك إنشاء CosmosClient.

from azure.cosmos import CosmosClient

import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)

مصادقة AAD

يمكنك أيضا مصادقة عميل باستخدام بيانات اعتماد AAD لمدير الخدمة وحزمة هوية azure. يمكنك تمرير معلومات بيانات الاعتماد مباشرة إلى ClientSecretCredential، أو استخدام DefaultAzureCredential:

from azure.cosmos import CosmosClient
from azure.identity import ClientSecretCredential, DefaultAzureCredential

import os
url = os.environ['ACCOUNT_URI']
tenant_id = os.environ['TENANT_ID']
client_id = os.environ['CLIENT_ID']
client_secret = os.environ['CLIENT_SECRET']

# Using ClientSecretCredential
aad_credentials = ClientSecretCredential(
    tenant_id=tenant_id,
    client_id=client_id,
    client_secret=client_secret)

# Using DefaultAzureCredential (recommended)
aad_credentials = DefaultAzureCredential()

client = CosmosClient(url, aad_credentials)

تأكد دائما من أن الهوية المدارة التي تستخدمها لمصادقة AAD لها readMetadata أذونات.
مزيد من المعلومات حول كيفية إعداد مصادقة AAD: إعداد RBAC لمصادقة AAD
مزيد من المعلومات حول العمليات المسموح بها للعملاء المصادق عليهم من AAD: نموذج إذن التحكم في الوصول استنادا إلى الدور

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

بمجرد تهيئة CosmosClient، يمكنك التفاعل مع أنواع الموارد الأساسية في قاعدة بيانات Cosmos:

  • قاعدة البيانات: حساب Cosmos DB يمكن أن يحتوي على قواعد بيانات متعددة. عندما تنشئ قاعدة بيانات فأنت تحدد واجهة برمجة التطبيقات التي تريد استخدامها عندما تتعامل مع هذه الوثائق: SQL, MongoDB, Gremlin, Cassandra, أو Azure Table. استخدم كائن DatabaseProxy لإدارة حاوياته.

  • حاوية: الحاوية هي مجموعة من وثائق JSON. يمكنك إنشاء (إدراج) وقراءة وتحديث وحذف العناصر في حاوية باستخدام أساليب على كائن ContainerProxy .

  • العنصر: العنصر هو تمثيل يشبه القاموس لمستند JSON المخزن في حاوية. يجب أن يتضمن كل عنصر تضيفه إلى حاوية مفتاحا id بقيمة تعرف العنصر داخل الحاوية بشكل فريد.

لمزيد من المعلومات حول هذه الموارد، راجع استخدام قواعد بيانات Azure Cosmos والحاويات والعناصر.

كيفية استخدام enable_cross_partition_query

تقبل وسيطة enable_cross_partition_query الكلمة الأساسية خيارين: None (افتراضي) أو True.

ملاحظة حول استخدام الاستعلامات حسب المعرف

عند استخدام الاستعلامات التي تحاول العثور على عناصر استنادا إلى قيمة معرف ، تأكد دائما من تمرير متغير نوع سلسلة. يسمح Azure Cosmos DB فقط بقيم معرف السلسلة وإذا كنت تستخدم أي نوع بيانات آخر، فلن ترجع SDK هذه أي نتائج ولا رسائل خطأ.

ملاحظة حول مستويات تناسق العميل

اعتبارا من الإصدار 4.3.0b3، إذا لم يمرر المستخدم مستوى تناسق صريحا إلى تهيئة العميل، فسيستخدم عميله المستوى الافتراضي لحساب قاعدة البيانات الخاص به. في السابق، كان يتم تعيين الافتراضي إلى Session التناسق. إذا كنت ترغب لسبب ما في الاستمرار في القيام بذلك، يمكنك تغيير تهيئة العميل لتضمين المعلمة الصريحة لهذا كما هو موضح:

from azure.cosmos import CosmosClient

import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY, consistency_level='Session')

التقييدات

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

قيود مستوى البيانات:

  • استعلامات التجميع حسب
  • الاستعلامات باستخدام COUNT من استعلام فرعي DISTINCT: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
  • معالجة دفعة مجمعة/معاملات
  • الوصول المباشر إلى وضع TCP
  • دعم الرمز المميز للاستمرار للاستعلامات المجمعة عبر الأقسام مثل الفرز والعد والتميز. تدعم الاستعلامات القابلة للبث مثل SELECT * FROM WHERE الرموز المميزة للمتابعة.
  • موجز التغيير: المعالج
  • موجز التغيير: قراءة قيم مفاتيح أقسام متعددة
  • موجز التغيير: قراءة وقت محدد
  • موجز التغيير: قراءة من البداية
  • موجز التغيير: نموذج السحب
  • ORDER BY عبر الأقسام للأنووع المختلطة
  • تمكين التشخيصات لأساليب نوع الاستعلام غير المتزامن

قيود وحدة التحكم:

  • الحصول على مقاييس CollectionSizeUsage و DatabaseUsage و DocumentUsage
  • إنشاء فهرس جغرافي مكاني
  • الحصول على سلسلة الاتصال
  • الحصول على الحد الأدنى من وحدات الطلب/الثانية للحاوية

الحلول البديلة

حل قيود المعالجة المجمعة

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

الحل البديل لقيود مستوى التحكم

عادة، يمكنك استخدام مدخل Microsoft Azure أوواجهة برمجة تطبيقات REST لموفر موارد Azure Cosmos DB أو Azure CLI أو PowerShell لقيود مستوى التحكم غير المدعومة.

نوع البيانات المنطقية

بينما تستخدم لغة Python "True" و"False" للأنووع المنطقية، يقبل Cosmos DB "true" و"false" فقط. بمعنى آخر، تستخدم لغة Python القيم المنطقية مع الحرف الكبير الأول وجميع الأحرف الصغيرة الأخرى، بينما يستخدم Cosmos DB ولغة SQL الخاصة به الأحرف الصغيرة فقط لتلك القيم المنطقية نفسها. كيفية التعامل مع هذا التحدي؟

  • يجب أن تستخدم مستندات JSON التي تم إنشاؤها باستخدام Python "True" و"False"، لتمرير التحقق من صحة اللغة. سيقوم SDK بتحويله إلى "true" و"false" نيابة عنك. بمعنى أن "true" و"false" هو ما سيتم تخزينه في Cosmos DB.
  • إذا قمت باسترداد هذه المستندات باستخدام مستكشف بيانات مدخل Cosmos DB، فسترى "صواب" و"خطأ".
  • إذا قمت باسترداد هذه المستندات باستخدام Python SDK هذا، فسيتم تحويل قيم "true" و"false" تلقائيا إلى "True" و"False".

SQL Queries x FROM Clause Subitems

يستخدم SDK هذا الأسلوب query_items لإرسال استعلامات SQL إلى Azure Cosmos DB.

تسمح لك لغة Cosmos DB SQL بالحصول على مواقع فرعية باستخدام عبارة FROM، لتقليل المصدر إلى مجموعة فرعية أصغر. على سبيل المثال، يمكنك استخدام select * from Families.children بدلا من select * from Families. ولكن يرجى ملاحظة ما يلي:

  • بالنسبة إلى استعلامات SQL باستخدام query_items الأسلوب ، تتطلب SDK هذه تحديد العلامة partition_keyenable_cross_partition_query أو استخدامها.
  • إذا كنت تحصل على مواقع فرعية وتحدد partition_key، فالرجاء التأكد من تضمين مفتاح القسم الخاص بك في المواقع الفرعية، وهو أمر غير صحيح لمعظم الحالات.

الحد الأقصى لعدد العناصر

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

أمثلة

توفر الأقسام التالية العديد من مقتطفات التعليمات البرمجية التي تغطي بعض مهام قاعدة بيانات Cosmos الأكثر شيوعًا، بما في ذلك:

إنشاء قاعدة بيانات

بعد مصادقة CosmosClient، يمكنك العمل مع أي مورد في الحساب. تنشئ القصاصة البرمجية أدناه قاعدة بيانات SQL API، وهي الافتراضية عندما لا يتم تحديد واجهة برمجة التطبيقات عند استدعاء create_database .

from azure.cosmos import CosmosClient, exceptions
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
try:
    database = client.create_database(DATABASE_NAME)
except exceptions.CosmosResourceExistsError:
    database = client.get_database_client(DATABASE_NAME)

إنشاء حاوية

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

from azure.cosmos import CosmosClient, PartitionKey, exceptions
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'

try:
    container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
    raise

إنشاء حاوية مخزن تحليلي مُمكَّنة

ينشئ هذا المثال حاوية مع تمكين المخزن التحليلي ، لإعداد التقارير، وBI، الذكاء الاصطناعي، والتحليلات المتقدمة باستخدام ارتباط Azure Synapse.

خيارات analytical_storage_ttl هي:

  • 0 أو Null أو غير مطلع: غير ممكن.
  • -1: سيتم تخزين البيانات بشكل لا نهائي.
  • أي رقم آخر: ttl الفعلي، بالثوان.
CONTAINER_NAME = 'products'
try:
    container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"),analytical_storage_ttl=-1)
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
    raise

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

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

استرداد حاوية موجودة من قاعدة البيانات:

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

إدراج بيانات

لإدراج عناصر في حاوية، مرر قاموسا يحتوي على بياناتك إلى ContainerProxy.upsert_item. يجب أن يتضمن كل عنصر تضيفه إلى حاوية مفتاحا id بقيمة تعرف العنصر داخل الحاوية بشكل فريد.

يدرج هذا المثال عدة عناصر في الحاوية، ولكل منها id:

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

for i in range(1, 10):
    container.upsert_item({
            'id': 'item{0}'.format(i),
            'productName': 'Widget',
            'productModel': 'Model {0}'.format(i)
        }
    )

حذف البيانات

لحذف العناصر من حاوية، استخدم ContainerProxy.delete_item. لا تدعم واجهة برمجة تطبيقات SQL في Cosmos DB عبارة SQL DELETE .

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

for item in container.query_items(
        query='SELECT * FROM products p WHERE p.productModel = "Model 2"',
        enable_cross_partition_query=True):
    container.delete_item(item, partition_key='Widget')

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

الاستعلام عن قاعدة البيانات

تدعم قاعدة بيانات Cosmos DB SQL API الاستعلام عن العناصر في حاوية مع ContainerProxy.query_items باستخدام بناء جملة يشبه SQL.

يستعلم هذا المثال عن حاوية للعناصر ذات id:

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

# Enumerate the returned items
import json
for item in container.query_items(
        query='SELECT * FROM mycontainer r WHERE r.id="item3"',
        enable_cross_partition_query=True):
    print(json.dumps(item, indent=True))

ملاحظة: على الرغم من أنه يمكنك تحديد أي قيمة لاسم الحاوية في العبارة FROM ، نوصي باستخدام اسم الحاوية للتناسق.

قم بإجراء استعلامات ذات معلمات عن طريق تمرير قاموس يحتوي على المعلمات وقيمها إلى ContainerProxy.query_items:

discontinued_items = container.query_items(
    query='SELECT * FROM products p WHERE p.productModel = @model',
    parameters=[
        dict(name='@model', value='Model 7')
    ],
    enable_cross_partition_query=True
)
for item in discontinued_items:
    print(json.dumps(item, indent=True))

لمزيد من المعلومات حول الاستعلام عن قواعد بيانات قاعدة بيانات Cosmos باستخدام واجهة برمجة تطبيقات SQL، راجع الاستعلام عن بيانات قاعدة بيانات Azure Cosmos باستخدام استعلامات SQL.

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

الحصول على خصائص قاعدة البيانات وعرضها:

from azure.cosmos import CosmosClient
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
properties = database.read()
print(json.dumps(properties))

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

احصل على قيم معدل النقل لقاعدة بيانات وحاوية ذات معدل نقل مخصص وعرضها:

from azure.cosmos import CosmosClient
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)

# Database
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
db_offer = database.read_offer()
print('Found Offer \'{0}\' for Database \'{1}\' and its throughput is \'{2}\''.format(db_offer.properties['id'], database.id, db_offer.properties['content']['offerThroughput']))

# Container with dedicated throughput only. Will return error "offer not found" for containers without dedicated throughput
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)
container_offer = container.read_offer()
print('Found Offer \'{0}\' for Container \'{1}\' and its throughput is \'{2}\''.format(container_offer.properties['id'], container.id, container_offer.properties['content']['offerThroughput']))

تعديل خصائص الحاوية

يمكن تعديل خصائص معينة لحاوية موجودة. يعين هذا المثال الوقت الافتراضي للعيش (TTL) للعناصر الموجودة في الحاوية إلى 10 ثوان:

from azure.cosmos import CosmosClient, PartitionKey
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

database.replace_container(
    container,
    partition_key=PartitionKey(path="/productName"),
    default_ttl=10,
)
# Display the new TTL setting for the container
container_props = container.read()
print(json.dumps(container_props['defaultTtl']))

لمزيد من المعلومات حول TTL، راجع وقت البقاء لبيانات Azure Cosmos DB.

استخدام العميل غير المتزامن

عميل Cosmos غير المتزامن هو عميل منفصل يبحث ويعمل بطريقة مشابهة للعميل المتزامن الحالي. ومع ذلك، يجب استيراد العميل غير المتزامن بشكل منفصل ويجب استخدام أساليبه مع الكلمات الأساسية غير المتزامنة/الانتظار. يجب تهيئة عميل Async وإغلاقه بعد الاستخدام، والذي يمكن القيام به يدويا أو باستخدام مدير السياق. يوضح المثال أدناه كيفية القيام بذلك يدويا.

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'    

async def create_products():
    client = CosmosClient(URL, credential=KEY)
    database = client.get_database_client(DATABASE_NAME)
    container = database.get_container_client(CONTAINER_NAME)
    for i in range(10):
        await container.upsert_item({
                'id': 'item{0}'.format(i),
                'productName': 'Widget',
                'productModel': 'Model {0}'.format(i)
            }
        )
    await client.close() # the async client must be closed manually if it's not initialized in a with statement

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

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'

async def create_products():
    async with CosmosClient(URL, credential=KEY) as client: # the with statement will automatically initialize and close the async client
        database = client.get_database_client(DATABASE_NAME)
        container = database.get_container_client(CONTAINER_NAME)
        for i in range(10):
            await container.upsert_item({
                    'id': 'item{0}'.format(i),
                    'productName': 'Widget',
                    'productModel': 'Model {0}'.format(i)
                }
            )

الاستعلامات مع العميل غير المتزامن

على عكس العميل المتزامن، لا يحتوي العميل غير المتزامن على enable_cross_partition علامة في الطلب. ستحاول الاستعلامات التي لا تحتوي على قيمة مفتاح قسم محددة إجراء استعلام عبر الأقسام بشكل افتراضي.

يمكن تكرار نتائج الاستعلام، ولكن الإخراج الأولي للاستعلام يرجع مكرر غير متزامن. وهذا يعني أن كل كائن من المكرر هو كائن ينتظره، ولا يحتوي بعد على نتيجة الاستعلام الحقيقية. للحصول على نتائج الاستعلام، يمكنك استخدام مزامنة غير متزامنة للتكرار الحلقي، والتي تنتظر كل نتيجة أثناء التكرار على الكائن، أو الانتظار يدويا لكل نتيجة استعلام أثناء التكرار عبر التكرار غير المتزامن.

نظرا لأن نتائج الاستعلام هي مكرر غير متزامن، فلا يمكن تحويلها إلى قوائم مباشرة؛ بدلا من ذلك، إذا كنت بحاجة إلى إنشاء قوائم من نتائجك، فاستخدم غير متزامن لحلقة أو فهم قائمة Python لملء قائمة:

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

async def create_lists():
    results = container.query_items(
            query='SELECT * FROM products p WHERE p.productModel = "Model 2"')

    # iterates on "results" iterator to asynchronously create a complete list of the actual query results

    item_list = []
    async for item in results:
        item_list.append(item)

    # Asynchronously creates a complete list of the actual query results. This code performs the same action as the for-loop example above.
    item_list = [item async for item in results]
    await client.close()

استخدام ذاكرة التخزين المؤقت المتكاملة

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

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

كيفية تكوين ذاكرة التخزين المؤقت المتكاملة Azure Cosmos DB (معاينة)

import azure.cosmos.cosmos_client as cosmos_client
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = cosmos_client.CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)

def integrated_cache_snippet():
    item_id = body['id'] 
    query = 'SELECT * FROM c'

    #item cache
    container.read_item(item=item_id, partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)

    #query cache   
    container.query_items(query=query,
         partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)

لمزيد من المعلومات حول ذاكرة التخزين المؤقت المتكاملة، راجع ذاكرة التخزين المؤقت المتكاملة ل Azure Cosmos DB - نظرة عامة.

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

عام

عند التفاعل مع Cosmos DB باستخدام Python SDK، تتوافق الاستثناءات التي تم إرجاعها بواسطة الخدمة مع نفس رموز حالة HTTP التي تم إرجاعها لطلبات واجهة برمجة تطبيقات REST:

رموز حالة HTTP لـ Azure Cosmos DB

على سبيل المثال، إذا حاولت إنشاء حاوية باستخدام معرف (اسم) قيد الاستخدام بالفعل في قاعدة بيانات Cosmos DB، 409 يتم إرجاع خطأ يشير إلى التعارض. في المثال التالي، تتم معالجة الخطأ على نحو آمن من خلال معرفة الاستثناء وعرض معلومات إضافية حول الخطأ.

try:
    database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
    print("""Error creating container
HTTP status code 409: The ID (name) provided for the container is already in use.
The container name must be unique within the database.""")

تسجيل الدخول

تستخدم هذه المكتبة مكتبة التسجيل القياسية للتسجيل. يتم تسجيل المعلومات الأساسية حول جلسات HTTP (عناوين URL والعناوين وما إلى ذلك) على مستوى INFO.

يمكن تمكين تسجيل مستوى تتبع الأخطاء المفصل، بما في ذلك هيئات الطلب/الاستجابة والعناوين غير النشطة، على عميل باستخدام الوسيطة logging_enable :

import sys
import logging
from azure.cosmos import CosmosClient

# 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)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)

وبالمثل، logging_enable يمكن تمكين تسجيل مفصل لعملية واحدة، حتى عندما لا يتم تمكين للعميل:

database = client.create_database(DATABASE_NAME, logging_enable=True)

بدلا من ذلك، يمكنك تسجيل الدخول باستخدام CosmosHttpLoggingPolicy، والذي يمتد من Azure core HttpLoggingPolicy، عن طريق تمرير المسجل إلى الوسيطة logger . بشكل افتراضي، سيستخدم السلوك من HttpLoggingPolicy. سيؤدي تمرير الوسيطة enable_diagnostics_logging إلى تمكين CosmosHttpLoggingPolicy، وسيكون لديك معلومات إضافية في الاستجابة ذات الصلة بتصحيح أخطاء مشكلات Cosmos.

import logging
from azure.cosmos import CosmosClient

#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)

# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)

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

# This example enables the CosmosHttpLoggingPolicy and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

بيانات تتبع الاستخدام

يوفر Azure Core القدرة على استخدام Python SDKs معهم. الحزم الوحيدة التي تحتاج إلى تثبيت لاستخدام هذه الوظيفة هي التالية:

pip install azure-core-tracing-opentelemetry
pip install opentelemetry-sdk

لمزيد من المعلومات حول ذلك، نوصي بإلقاء نظرة على هذا المستند من Azure Core يصف كيفية إعداده. لقد أضفنا أيضا ملفا نموذجيا لإظهار كيفية استخدامه مع SDK. يعمل هذا بنفس الطريقة بغض النظر عن عميل Cosmos الذي تستخدمه.

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

للحصول على وثائق أكثر شمولًا حول خدمة قاعدة بيانات Cosmos، راجع وثائق قاعدة بيانات Azure Cosmos على docs.microsoft.com.

المساهمة

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

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

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