CosmosClient الفصل

تمثيل منطقي من جانب العميل لحساب Azure Cosmos DB.

استخدم هذا العميل لتكوين الطلبات وتنفيذها إلى خدمة Azure Cosmos DB.

يوصى به للحفاظ على مثيل واحد من CosmosClient لكل عمر للتطبيق الذي يتيح إدارة الاتصال والأداء الفعالين.

تهيئة CosmosClient هي عملية ثقيلة - لا تستخدم مثيلات تهيئة CosmosClient كبيانات اعتماد أو عمليات التحقق من صحة اتصال الشبكة.

إنشاء مثيل CosmosClient جديد.

توريث

builtins.object

CosmosClient

الدالمنشئ

CosmosClient(url: str, credential: str | Dict[str, str] | TokenCredential, *, consistency_level: str | None = None, **kwargs: Any)

المعلمات

url

str

مطلوب

عنوان URL لحساب Cosmos DB.

credential

Union[str, Dict[str, str], AsyncTokenCredential]

مطلوب

يمكن أن يكون مفتاح الحساب أو قاموسا من الرموز المميزة للمورد.

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_on_status_codes

list[int]

قائمة رموز حالة معينة لإعادة المحاولة عليها.

retry_backoff_factor

float

عامل لحساب وقت الانتظار بين محاولات إعادة المحاولة.

enable_endpoint_discovery

bool

تمكين اكتشاف نقطة النهاية لحسابات قاعدة البيانات المنسوخة جغرافيا. (الافتراضي: صحيح)

preferred_locations

list[str]

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

enable_diagnostics_logging

bool

تمكين نهج CosmosHttpLogging. يجب استخدامه مع المسجل للعمل.

logger

Logger

المسجل الذي سيتم استخدامه لجمع تشخيصات الطلب. يمكن تمريره على مستوى العميل (لتسجيل جميع الطلبات) أو على مستوى طلب واحد. سيتم تسجيل الطلبات على مستوى INFO.

أمثلة

إنشاء مثيل جديد لعميل Cosmos DB:

       async with CosmosClient(url, key) as client:

الأساليب

close	أغلق هذا المثيل من CosmosClient.
create_database	إنشاء قاعدة بيانات جديدة بالمعرف المحدد (الاسم).
create_database_if_not_exists	إنشاء قاعدة البيانات إذا لم تكن موجودة بالفعل. إذا كانت قاعدة البيانات موجودة بالفعل، يتم إرجاع الإعدادات الموجودة. .. ملاحظة: لا تتحقق هذه الدالة من إعدادات قاعدة البيانات الموجودة أو تحدثها أو تقدم معدل نقل إذا كانت تختلف عما تم تمريره.
delete_database	احذف قاعدة البيانات بالمعرف المحدد (الاسم).
from_connection_string	إنشاء مثيل CosmosClient من سلسلة اتصال. يمكن استرداد هذا من مدخل Microsoft Azure. للحصول على قائمة كاملة كوسيطات الكلمة الأساسية الاختيارية، راجع الدالة الإنشائية CosmosClient.
get_database_client	استرداد قاعدة بيانات موجودة بمعرف المعرف (الاسم).
list_databases	سرد قواعد البيانات في حساب قاعدة بيانات Cosmos DB SQL.
query_databases	الاستعلام عن قواعد البيانات في حساب قاعدة بيانات Cosmos DB SQL.

close

أغلق هذا المثيل من CosmosClient.

async close() -> None

create_database

إنشاء قاعدة بيانات جديدة بالمعرف المحدد (الاسم).

async create_database(id: str, **kwargs: Any) -> DatabaseProxy

المعلمات

id

str

مطلوب

معرف (اسم) قاعدة البيانات المراد إنشاؤها.

offer_throughput

Union[int, ThroughputProperties]

معدل النقل المقدم لهذا العرض.

session_token

str

رمز مميز للاستخدام مع تناسق الجلسة.

initial_headers

dict[str, str]

العناوين الأولية التي سيتم إرسالها كجزء من الطلب.

etag

str

قيمة ETag أو حرف البدل (*). يستخدم للتحقق مما إذا كان المورد قد تغير، ويعمل وفقا للشرط المحدد بواسطة المعلمة match_condition .

match_condition

MatchConditions

شرط المطابقة لاستخدامه على etag.

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

استدعاء مع بيانات تعريف الاستجابة.

المرتجعات

مثيل DatabaseProxy يمثل قاعدة البيانات الجديدة.

نوع الإرجاع

DatabaseProxy

استثناءات

CosmosResourceExistsError

قاعدة البيانات ذات المعرف المحدد موجودة بالفعل.

أمثلة

إنشاء قاعدة بيانات في حساب Cosmos DB:

           database_name = "testDatabase"
           try:
               database = await client.create_database(id=database_name)
           except exceptions.CosmosResourceExistsError:
               database = client.get_database_client(database=database_name)

create_database_if_not_exists

إنشاء قاعدة البيانات إذا لم تكن موجودة بالفعل.

إذا كانت قاعدة البيانات موجودة بالفعل، يتم إرجاع الإعدادات الموجودة.

.. ملاحظة: لا تتحقق هذه الدالة من إعدادات قاعدة البيانات الموجودة أو تحدثها أو تقدم معدل نقل إذا كانت تختلف عما تم تمريره.

async create_database_if_not_exists(id: str, **kwargs: Any) -> DatabaseProxy

المعلمات

id

str

مطلوب

معرف (اسم) قاعدة البيانات المراد قراءتها أو إنشائها.

offer_throughput

Union[int, ThroughputProperties]

معدل النقل المقدم لهذا العرض.

session_token

str

رمز مميز للاستخدام مع تناسق الجلسة.

initial_headers

dict[str, str]

العناوين الأولية التي سيتم إرسالها كجزء من الطلب.

etag

str

قيمة ETag أو حرف البدل (*). يستخدم للتحقق مما إذا كان المورد قد تغير، ويعمل وفقا للشرط المحدد بواسطة المعلمة match_condition .

match_condition

MatchConditions

شرط المطابقة لاستخدامه على etag.

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

استدعاء مع بيانات تعريف الاستجابة.

المرتجعات

مثيل DatabaseProxy يمثل قاعدة البيانات.

نوع الإرجاع

DatabaseProxy

استثناءات

CosmosHttpResponseError

فشلت قراءة قاعدة البيانات أو إنشائها.

delete_database

احذف قاعدة البيانات بالمعرف المحدد (الاسم).

async delete_database(database: str | DatabaseProxy | Dict[str, Any], **kwargs: Any) -> None

المعلمات

database

Union[str, DatabaseProxy, Dict[str, Any]]

مطلوب

المعرف (الاسم)، أو الإملاء الذي يمثل الخصائص، أو DatabaseProxy مثيل قاعدة البيانات المراد حذفه.

session_token

str

رمز مميز للاستخدام مع تناسق الجلسة.

initial_headers

dict[str, str]

العناوين الأولية التي سيتم إرسالها كجزء من الطلب.

etag

str

قيمة ETag أو حرف البدل (*). يستخدم للتحقق مما إذا كان المورد قد تغير، ويعمل وفقا للشرط المحدد بواسطة المعلمة match_condition .

match_condition

MatchConditions

شرط المطابقة لاستخدامه على etag.

response_hook

Callable[[Dict[str, str]], None]

استدعاء مع بيانات تعريف الاستجابة.

نوع الإرجاع

None

استثناءات

CosmosHttpResponseError

إذا تعذر حذف قاعدة البيانات.

from_connection_string

إنشاء مثيل CosmosClient من سلسلة اتصال.

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

from_connection_string(conn_str: str, *, credential: str | Dict[str, str] | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

المعلمات

conn_str

str

مطلوب

سلسلة الاتصال.

credential

Union[str, Dict[str, str]]

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

consistency_level

str

مستوى التناسق لاستخدامه في جلسة العمل. القيمة الافتراضية هي None (على مستوى الحساب). المزيد حول مستويات التناسق والقيم المحتملة: https://aka.ms/cosmos-consistency-levels

المرتجعات

مثيل CosmosClient

نوع الإرجاع

CosmosClient

get_database_client

استرداد قاعدة بيانات موجودة بمعرف المعرف (الاسم).

get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy

المعلمات

database

Union[str, DatabaseProxy, Dict[str, Any]]

مطلوب

المعرف (الاسم)، أو الإملاء الذي يمثل الخصائص، أو DatabaseProxy مثيل قاعدة البيانات للحصول عليها.

المرتجعات

مثيل DatabaseProxy يمثل قاعدة البيانات المستردة.

نوع الإرجاع

DatabaseProxy

list_databases

سرد قواعد البيانات في حساب قاعدة بيانات Cosmos DB SQL.

list_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

المعلمات

max_item_count

int

الحد الأقصى لعدد العناصر التي سيتم إرجاعها في عملية التعداد.

session_token

str

رمز مميز للاستخدام مع تناسق الجلسة.

initial_headers

dict[str, str]

العناوين الأولية التي سيتم إرسالها كجزء من الطلب.

response_hook

Callable[[Dict[str, str]], None]

استدعاء مع بيانات تعريف الاستجابة.

المرتجعات

AsyncItemPaged من خصائص قاعدة البيانات (dicts).

نوع الإرجاع

<xref:AsyncItemPaged>[Dict[str, str]]

query_databases

الاستعلام عن قواعد البيانات في حساب قاعدة بيانات Cosmos DB SQL.

query_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

المعلمات

query

Union[str, Dict[str, Any]]

استعلام Azure Cosmos DB SQL المراد تنفيذه.

parameters

List[Dict[str, Any]]

صفيف اختياري من المعلمات للاستعلام. كل معلمة هي dict() مع مفاتيح "الاسم" و"القيمة".

max_item_count

int

الحد الأقصى لعدد العناصر التي سيتم إرجاعها في عملية التعداد.

session_token

str

رمز مميز للاستخدام مع تناسق الجلسة.

initial_headers

dict[str, str]

العناوين الأولية التي سيتم إرسالها كجزء من الطلب.

response_hook

Callable[[Dict[str, str]], None]

استدعاء مع بيانات تعريف الاستجابة.

المرتجعات

AsyncItemPaged من خصائص قاعدة البيانات (الإملاءات).

نوع الإرجاع

<xref:AsyncItemPaged>[Dict[str, str]]