مشاركة عبر

استكشاف المشكلات وإصلاحها عند استخدام Azure Cosmos DB Python SDK مع واجهة برمجة التطبيقات لحسابات NoSQL

  • مقالة

ينطبق على: NoSQL

هام

تتناول هذه المقالة استكشاف الأخطاء وإصلاحها ل Azure Cosmos DB Python SDK فقط. يرجى الاطلاع على ملاحظات إصدار Azure Cosmos DB Python SDK Readme والحزمة (PyPI) والحزمة (Conda) ونصائح الأداء لمزيد من المعلومات.

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

ابدأ بهذه القائمة:

  • ألق نظرة على قسم المشكلات الشائعة والحلول في هذه المقالة.
  • انظر إلى Python SDK في مستودع Azure Cosmos DB المركزي، والذي يتوفر مصدر مفتوح على GitHub. يحتوي على قسم مشكلات تتم مراقبته بشكل نشط. تحقق لمعرفة ما إذا تم بالفعل تقديم أي مشكلة مماثلة مع حل بديل. أحد النصائح المفيدة هو تصفية المشكلات حسب العلامة *Cosmos* .
  • راجع نصائح الأداء ل Azure Cosmos DB Python SDK، واتبع الممارسات المقترحة.
  • اقرأ بقية هذه المقالة، إذا لم تجد حلاً. ثم قم بتسجيل مشكلة GitHub. إذا كان هناك خيار لإضافة علامات إلى مشكلة GitHub، أضف *Cosmos* علامة.

تسجيل التشخيصات والتقاطها

هام

نوصي باستخدام أحدث إصدار من python SDK. يمكنك التحقق من محفوظات الإصدار هنا

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

يمكن تمكين تسجيل مستوى DEBUG التفصيلي، بما في ذلك هيئات الطلب/الاستجابة والعناوين غير المصححة، على عميل باستخدام الوسيطة 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 Cosmos DB SDKs للحصول على إرشادات حول كيفية تصميم التطبيقات المرنة ومعرفة دلالات إعادة المحاولة ل SDK.

المشكلات الشائعة والحلول

اقتراحات عامة

لأفضل أداء:

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

تحقق من مقاييس المدخل

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

تقييد الاتصال

يمكن أن يحدث تقييد الاتصال إما بسبب [حد الاتصال على جهاز مضيف] أو [استنفاد منفذ Azure SNAT (PAT).

حد الاتصال في جهاز مضيف

تحتوي بعض أنظمة Linux، مثل Red Hat، على حد أعلى للعدد الإجمالي للملفات المفتوحة. يتم تنفيذ المقابس في Linux كملفات، لذا فإن هذا الرقم يحد من إجمالي عدد الاتصالات أيضاً. قم بتشغيل الأمر التالي.

ulimit -a

يجب أن يكون عدد الملفات المفتوحة القصوى المسموح بها، والتي تم تحديدها على أنها "nofile"، ضعف حجم تجمع الاتصال على الأقل. لمزيد من المعلومات، راجع نصائح أداء Azure Cosmos DB Python SDK.

استنفاد منفذ Azure SNAT (PAT)

إذا تم نشر تطبيقك على أجهزة Azure الظاهرية دون عنوان IP عام، فإن منافذ Azure SNAT تنشئ افتراضياً اتصالات بأي نقطة نهاية خارج الجهاز الظاهري. عدد الاتصالات المسموح بها من الجهاز الظاهري لنقطة نهاية Azure Cosmos DB محدود بواسطة تكوين Azure SNAT.

تُستخدم منافذ Azure SNAT فقط عندما يكون للجهاز الظاهري عنوان IP خاص وتحاول عملية من الجهاز الظاهري الاتصال بعنوان IP عام. هناك نوعان من الحلول لتجنب قيود Azure SNAT:

  • أضف نقطة نهاية خدمة Azure Cosmos DB إلى الشبكة الفرعية لشبكة Azure Virtual Machines الخاصة بك. لمزيد من المعلومات، راجع نقاط نهاية خدمة الشبكة الظاهرية Azure.

    عند تمكين نقطة نهاية الخدمة، لن يتم إرسال الطلبات من عنوان IP عام إلى Azure Cosmos DB. بدلاً من ذلك، يتم إرسال هوية الشبكة الافتراضية والشبكة الفرعية. قد يؤدي هذا التغيير إلى سقوط جدار الحماية إذا تم السماح بعناوين IP العامة فقط. إذا كنت تستخدم جدار حماية، فعند تمكين نقطة نهاية الخدمة، أضف شبكة فرعية إلى جدار الحماية باستخدام Virtual Network ACLs.

  • قم بتعيين IP عام لجهاز Azure VM الخاص بك.

لا يمكن الوصول إلى الخدمة - جدار الحماية

azure.core.exceptions.ServiceRequestError: يشير إلى أن SDK لا يمكنه الوصول إلى الخدمة. اتبع حد الاتصال على جهاز مضيف.

فشل الاتصال بمحاكي Azure Cosmos DB

شهادة HTTPS لمحاكي Azure Cosmos DB هي شهادة موقعة ذاتياً. لكي تعمل Python SDK مع المحاكي، قم باستيراد شهادة المحاكي. لمزيد من المعلومات، راجع تصدير شهادات Azure Cosmos DB Emulator.

وكيل HTTP

إذا كنت تستخدم وكيل HTTP، فتأكد من أنه يمكنه دعم عدد الاتصالات التي تم تكوينها في SDK ConnectionPolicy. خلاف ذلك، ستواجه مشكلات في الاتصال.

مشاكل الاستعلام الشائعة

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

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

  • تعرف على إرشادات الأداء ل Python SDK
  • تعرف على أفضل الممارسات ل Python SDK