CosmosClient الفصل

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

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

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

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

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

توريث

builtins.object

CosmosClient

الدالمنشئ

CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)

المعلمات

url

str

مطلوب

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

credential

Union[str, Dict[str, str], TokenCredential]

مطلوب

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

consistency_level

str

القيمة الافتراضية: None

مستوى التناسق لاستخدامه في جلسة العمل. القيمة الافتراضية هي 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:

   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

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

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

Callable

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

المرتجعات

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

نوع الإرجاع

DatabaseProxy

استثناءات

CosmosResourceExistsError

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

أمثلة

إنشاء قاعدة بيانات في حساب 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

مطلوب

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

populate_query_metrics

bool

مطلوب

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

offer_throughput

int أو <xref:azure.cosmos.ThroughputProperties.>

مطلوب

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

session_token

str

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

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

Callable

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

المرتجعات

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

نوع الإرجاع

DatabaseProxy

استثناءات

CosmosHttpResponseError

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

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

مطلوب

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

session_token

str

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

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

Callable

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

نوع الإرجاع

None

استثناءات

CosmosHttpResponseError

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

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

المعلمات

conn_str

str

مطلوب

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

credential

str أو dict(str, str)

القيمة الافتراضية: None

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

consistency_level

Optional[str]

القيمة الافتراضية: None

مستوى التناسق لاستخدامه في جلسة العمل. القيمة الافتراضية هي None (مستوى الحساب).

استثناءات

CosmosResourceExistsError

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

get_database_account

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

get_database_account(**kwargs: Any) -> DatabaseAccount

المعلمات

response_hook

Callable

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

المرتجعات

مثيل DatabaseAccount يمثل حساب قاعدة بيانات Cosmos DB.

نوع الإرجاع

DatabaseAccount

استثناءات

CosmosResourceExistsError

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

get_database_client

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

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

المعلمات

database

str أو dict(str, str) أو DatabaseProxy

مطلوب

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

المرتجعات

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

نوع الإرجاع

DatabaseProxy

استثناءات

CosmosResourceExistsError

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

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]]

المعلمات

max_item_count

int

مطلوب

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

session_token

str

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

initial_headers

dict[str,str]

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

response_hook

Callable

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

المرتجعات

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

نوع الإرجاع

Iterable[dict[str, str]]

استثناءات

CosmosResourceExistsError

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

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]]

المعلمات

query

str

مطلوب

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

parameters

List[Dict[str, Any]]

مطلوب

صفيف اختياري من المعلمات للاستعلام. يتم تجاهله إذا لم يتم توفير استعلام.

enable_cross_partition_query

bool

مطلوب

السماح بالمسح الضوئي على الاستعلامات التي لا يمكن تقديمها كفهرسة تم إلغاء الاشتراك في المسارات المطلوبة.

max_item_count

int

مطلوب

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

session_token

str

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

initial_headers

dict[str,str]

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

response_hook

Callable

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

المرتجعات

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

نوع الإرجاع

Iterable[dict[str, str]]

استثناءات

CosmosResourceExistsError

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