CosmosClient الفصل
تمثيل منطقي من جانب العميل لحساب Azure Cosmos DB.
استخدم هذا العميل لتكوين الطلبات وتنفيذها إلى خدمة Azure Cosmos DB.
يوصى به للحفاظ على مثيل واحد من CosmosClient لكل عمر للتطبيق الذي يتيح إدارة الاتصال والأداء الفعالين.
تهيئة CosmosClient هي عملية ثقيلة - لا تستخدم مثيلات تهيئة CosmosClient كبيانات اعتماد أو عمليات التحقق من صحة اتصال الشبكة.
إنشاء مثيل CosmosClient جديد.
- توريث
-
builtins.objectCosmosClient
الدالمنشئ
CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)
المعلمات
يمكن أن يكون مفتاح الحساب أو قاموسا من الرموز المميزة للمورد.
- consistency_level
- str
مستوى التناسق لاستخدامه في جلسة العمل. القيمة الافتراضية هي None (مستوى الحساب). المزيد حول مستويات التناسق والقيم المحتملة: https://aka.ms/cosmos-consistency-levels
- timeout
- int
مهلة مطلقة بالثوان، لطلب HTTP المدمج ومعالجة الاستجابة.
- connection_timeout
- int
مهلة طلب HTTP بالثوان.
- connection_mode
- str
وضع الاتصال للعميل - يدعم حاليا "البوابة" فقط.
- proxy_config
- ProxyConfiguration
تكوين وكيل الاتصال.
- ssl_config
- SSLConfiguration
تكوين اتصال SSL.
- connection_verify
- bool
سواء كنت تريد التحقق من الاتصال، فإن القيمة الافتراضية هي True.
- connection_cert
- str
شهادة بديلة للتحقق من الاتصال.
- retry_total
- int
الحد الأقصى لمحاولات إعادة المحاولة.
- retry_backoff_max
- int
الحد الأقصى لوقت انتظار إعادة المحاولة بالثوان.
- retry_fixed_interval
- int
تم إصلاح الفاصل الزمني لإعادة المحاولة بالمللي ثانية.
- retry_read
- int
الحد الأقصى لعدد محاولات إعادة محاولة قراءة مأخذ التوصيل.
- retry_connect
- int
الحد الأقصى لعدد محاولات إعادة محاولة خطأ الاتصال.
- retry_status
- int
الحد الأقصى لعدد محاولات إعادة المحاولة على رموز حالة الخطأ.
- retry_backoff_factor
- float
عامل لحساب وقت الانتظار بين محاولات إعادة المحاولة.
- enable_endpoint_discovery
- bool
تمكين اكتشاف نقطة النهاية لحسابات قاعدة البيانات المنسوخة جغرافيا. (الافتراضي: صحيح)
- enable_diagnostics_logging
- bool
تمكين نهج CosmosHttpLogging. يجب استخدامه مع المسجل للعمل.
- logger
- Logger
المسجل الذي سيتم استخدامه لجمع تشخيصات الطلب. يمكن تمريره على مستوى العميل (لتسجيل جميع الطلبات) أو على مستوى طلب واحد. سيتم تسجيل الطلبات على مستوى INFO.
أمثلة
إنشاء مثيل جديد لعميل Cosmos DB:
from azure.cosmos import exceptions, CosmosClient, PartitionKey
import os
url = os.environ["ACCOUNT_URI"]
key = os.environ["ACCOUNT_KEY"]
client = CosmosClient(url, key)
الأساليب
create_database |
إنشاء قاعدة بيانات جديدة بالمعرف المحدد (الاسم). |
create_database_if_not_exists |
إنشاء قاعدة البيانات إذا لم تكن موجودة بالفعل. إذا كانت قاعدة البيانات موجودة بالفعل، يتم إرجاع الإعدادات الموجودة. .. ملاحظة: لا تتحقق هذه الدالة من إعدادات قاعدة البيانات الموجودة أو تحدثها أو تقدم معدل نقل إذا كانت تختلف عما تم تمريره. |
delete_database |
احذف قاعدة البيانات بالمعرف المحدد (الاسم). |
from_connection_string |
إنشاء مثيل CosmosClient من سلسلة اتصال. يمكن استرداد هذا من مدخل Microsoft Azure. للحصول على قائمة كاملة كوسيطات الكلمة الأساسية الاختيارية، راجع الدالة الإنشائية CosmosClient. |
get_database_account |
استرداد معلومات حساب قاعدة البيانات. |
get_database_client |
استرداد قاعدة بيانات موجودة بمعرف المعرف (الاسم). |
list_databases |
سرد قواعد البيانات في حساب قاعدة بيانات Cosmos DB SQL. |
query_databases |
الاستعلام عن قواعد البيانات في حساب قاعدة بيانات Cosmos DB SQL. |
create_database
إنشاء قاعدة بيانات جديدة بالمعرف المحدد (الاسم).
create_database(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy
المعلمات
- id
معرف (اسم) قاعدة البيانات المراد إنشاؤها.
- offer_throughput
معدل النقل المقدم لهذا العرض.
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
- etag
- str
قيمة ETag أو حرف البدل (*). يستخدم للتحقق مما إذا كان المورد قد تغير، ويعمل وفقا للشرط المحدد بواسطة المعلمة match_condition .
- match_condition
- MatchConditions
شرط المطابقة لاستخدامه على etag.
- response_hook
- Callable
استدعاء مع بيانات تعريف الاستجابة.
المرتجعات
مثيل DatabaseProxy يمثل قاعدة البيانات الجديدة.
نوع الإرجاع
استثناءات
قاعدة البيانات ذات المعرف المحدد موجودة بالفعل.
أمثلة
إنشاء قاعدة بيانات في حساب Cosmos DB:
database_name = "testDatabase"
try:
database = client.create_database(id=database_name)
except exceptions.CosmosResourceExistsError:
database = client.get_database_client(database=database_name)
create_database_if_not_exists
إنشاء قاعدة البيانات إذا لم تكن موجودة بالفعل.
إذا كانت قاعدة البيانات موجودة بالفعل، يتم إرجاع الإعدادات الموجودة.
.. ملاحظة: لا تتحقق هذه الدالة من إعدادات قاعدة البيانات الموجودة أو تحدثها أو تقدم معدل نقل إذا كانت تختلف عما تم تمريره.
create_database_if_not_exists(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy
المعلمات
- id
معرف (اسم) قاعدة البيانات المراد قراءتها أو إنشائها.
- offer_throughput
- int أو <xref:azure.cosmos.ThroughputProperties.>
معدل النقل المقدم لهذا العرض.
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
- etag
- str
قيمة ETag أو حرف البدل (*). يستخدم للتحقق مما إذا كان المورد قد تغير، ويعمل وفقا للشرط المحدد بواسطة المعلمة match_condition .
- match_condition
- MatchConditions
شرط المطابقة لاستخدامه على etag.
- response_hook
- Callable
استدعاء مع بيانات تعريف الاستجابة.
المرتجعات
مثيل DatabaseProxy يمثل قاعدة البيانات.
نوع الإرجاع
استثناءات
فشلت قراءة قاعدة البيانات أو إنشائها.
delete_database
احذف قاعدة البيانات بالمعرف المحدد (الاسم).
delete_database(database: str | DatabaseProxy | Dict[str, Any], populate_query_metrics: bool | None = None, **kwargs: Any) -> None
المعلمات
- database
- str أو dict(str, str) أو DatabaseProxy
المعرف (الاسم)، الإملاء الذي يمثل خصائص قاعدة البيانات أو DatabaseProxy مثيلها المراد حذفه.
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
- etag
- str
قيمة ETag أو حرف البدل (*). يستخدم للتحقق مما إذا كان المورد قد تغير، ويعمل وفقا للشرط المحدد بواسطة المعلمة match_condition .
- match_condition
- MatchConditions
شرط المطابقة لاستخدامه على etag.
- response_hook
- Callable
استدعاء مع بيانات تعريف الاستجابة.
نوع الإرجاع
استثناءات
إذا تعذر حذف قاعدة البيانات.
from_connection_string
إنشاء مثيل CosmosClient من سلسلة اتصال.
يمكن استرداد هذا من مدخل Microsoft Azure. للحصول على قائمة كاملة كوسيطات الكلمة الأساسية الاختيارية، راجع الدالة الإنشائية CosmosClient.
from_connection_string(conn_str: str, credential: Any | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient
المعلمات
بيانات الاعتماد البديلة لاستخدامها بدلا من المفتاح المتوفر في سلسلة الاتصال.
مستوى التناسق لاستخدامه في جلسة العمل. القيمة الافتراضية هي None (مستوى الحساب).
استثناءات
قاعدة البيانات ذات المعرف المحدد موجودة بالفعل.
get_database_account
استرداد معلومات حساب قاعدة البيانات.
get_database_account(**kwargs: Any) -> DatabaseAccount
المعلمات
- response_hook
- Callable
استدعاء مع بيانات تعريف الاستجابة.
المرتجعات
مثيل DatabaseAccount يمثل حساب قاعدة بيانات Cosmos DB.
نوع الإرجاع
استثناءات
قاعدة البيانات ذات المعرف المحدد موجودة بالفعل.
get_database_client
استرداد قاعدة بيانات موجودة بمعرف المعرف (الاسم).
get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy
المعلمات
- database
- str أو dict(str, str) أو DatabaseProxy
المعرف (الاسم)، الإملاء الذي يمثل الخصائص أو مثيل DatabaseProxy لقاعدة البيانات المراد قراءتها.
المرتجعات
مثيل DatabaseProxy يمثل قاعدة البيانات المستردة.
نوع الإرجاع
استثناءات
قاعدة البيانات ذات المعرف المحدد موجودة بالفعل.
list_databases
سرد قواعد البيانات في حساب قاعدة بيانات Cosmos DB SQL.
list_databases(max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]
المعلمات
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
- response_hook
- Callable
استدعاء مع بيانات تعريف الاستجابة.
المرتجعات
قابل لل تكرار لخصائص قاعدة البيانات (الإملاءات).
نوع الإرجاع
استثناءات
قاعدة البيانات ذات المعرف المحدد موجودة بالفعل.
query_databases
الاستعلام عن قواعد البيانات في حساب قاعدة بيانات Cosmos DB SQL.
query_databases(query: str | None = None, parameters: List[Dict[str, Any]] | None = None, enable_cross_partition_query: bool | None = None, max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]
المعلمات
صفيف اختياري من المعلمات للاستعلام. يتم تجاهله إذا لم يتم توفير استعلام.
- enable_cross_partition_query
- bool
السماح بالمسح الضوئي على الاستعلامات التي لا يمكن تقديمها كفهرسة تم إلغاء الاشتراك في المسارات المطلوبة.
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
- response_hook
- Callable
استدعاء مع بيانات تعريف الاستجابة.
المرتجعات
قابل لل تكرار لخصائص قاعدة البيانات (الإملاءات).
نوع الإرجاع
استثناءات
قاعدة البيانات ذات المعرف المحدد موجودة بالفعل.
Azure SDK for Python