DatabaseProxy الفصل
واجهة للتفاعل مع قاعدة بيانات معينة.
يجب عدم إنشاء مثيل لهذه الفئة مباشرة. بدلا من ذلك، استخدم <xref:azure.cosmos.aio.cosmos_client.CosmosClient.get_database_client> الأسلوب للحصول على قاعدة بيانات موجودة، أو <xref:azure.cosmos.aio.cosmos_client.CosmosClient.create_database> الأسلوب لإنشاء قاعدة بيانات جديدة.
تحتوي قاعدة البيانات على حاوية واحدة أو أكثر، يمكن أن تحتوي كل منها على عناصر وإجراءات مخزنة ومشغلات ووظائف معرفة من قبل المستخدم.
يمكن أن تحتوي قاعدة البيانات أيضا على مستخدمين مقترنين، يتم تكوين كل منهم بمجموعة من الأذونات للوصول إلى حاويات معينة أو إجراءات مخزنة أو مشغلات أو وظائف معرفة من قبل المستخدم أو عناصر.
تحتوي قاعدة بيانات Azure Cosmos DB SQL API على الخصائص التالية التي أنشأها النظام. هذه الخصائص للقراءة فقط:
_rid: معرف المورد.
_ts: عند آخر تحديث للمورد. القيمة هي طابع زمني.
_self: عنوان URI الفريد القابل للعنوان للمورد.
_etag: اسم المورد المطلوب للتحكم في التزامن المتفائل.
_colls: المسار القابل للعنوان لمورد المجموعات.
_users: المسار القابل للعنوان لمورد المستخدمين.
- توريث
-
builtins.objectDatabaseProxy
الدالمنشئ
DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] = None)المعلمات
- client_connection
- <xref:azure.cosmos.aio.CosmosClientConnection>
العميل الذي تم استرداد قاعدة البيانات هذه منه.
- properties
المتغيرات
- id
معرف (اسم) قاعدة البيانات.
الأساليب
| create_container |
إنشاء حاوية جديدة بالمعرف المحدد (الاسم). إذا كانت حاوية ذات المعرف المحدد موجودة بالفعل، يتم رفع CosmosResourceExistsError. |
| create_container_if_not_exists |
إنشاء حاوية إذا لم تكن موجودة بالفعل. إذا كانت الحاوية موجودة بالفعل، يتم إرجاع الإعدادات الموجودة. ملاحظة: لا يتحقق من إعدادات الحاوية الموجودة أو يحدثها أو يقدم معدل نقل إذا كانت تختلف عما تم تمريره إلى الأسلوب. |
| create_user |
إنشاء مستخدم جديد في الحاوية. لتحديث مستخدم موجود أو استبداله <xref:ContainerProxy.upsert_user> ، استخدم الأسلوب . |
| delete_container |
حذف حاوية. |
| delete_user |
احذف المستخدم المحدد من الحاوية. |
| get_container_client |
احصل على ContainerProxy لحاوية ذات معرف محدد (اسم). |
| get_throughput |
احصل على كائن ThroughputProperties لقاعدة البيانات هذه. إذا لم يكن هناك ThroughputProperties موجود بالفعل لقاعدة البيانات، يتم رفع استثناء. |
| get_user_client |
احصل على UserProxy لمستخدم بمعرف محدد. |
| list_containers |
سرد الحاويات في قاعدة البيانات. |
| list_users |
سرد جميع المستخدمين في الحاوية. |
| query_containers |
سرد خصائص الحاويات في قاعدة البيانات الحالية. |
| query_users |
إرجاع جميع المستخدمين المطابقة للاستعلام المحدد. |
| read |
اقرأ خصائص قاعدة البيانات. |
| replace_container |
إعادة تعيين خصائص الحاوية. تستمر تغييرات الخصائص على الفور. ستتم إعادة تعيين أي خصائص غير محددة إلى قيمها الافتراضية. |
| replace_throughput |
استبدل معدل النقل على مستوى قاعدة البيانات. إذا لم تكن هناك أي ThroughputProperties موجودة بالفعل لقاعدة البيانات، يتم رفع استثناء. |
| replace_user |
يستبدل المستخدم المحدد إذا كان موجودا في الحاوية. |
| upsert_user |
إدراج المستخدم المحدد أو تحديثه. إذا كان المستخدم موجودا بالفعل في الحاوية، يتم استبداله. إذا لم يكن المستخدم موجودا بالفعل، يتم إدراجه. |
create_container
إنشاء حاوية جديدة بالمعرف المحدد (الاسم).
إذا كانت حاوية ذات المعرف المحدد موجودة بالفعل، يتم رفع CosmosResourceExistsError.
async create_container(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyالمعلمات
- default_ttl
- int
الوقت الافتراضي للعيش (TTL) للعناصر الموجودة في الحاوية. إذا لم يتم تحديدها، فلن تنتهي صلاحية العناصر.
- offer_throughput
- Union[int, ThroughputProperties]
معدل النقل المقدم لهذا العرض.
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
- etag
- str
قيمة ETag أو حرف البدل (*). يستخدم للتحقق مما إذا كان المورد قد تغير، والعمل وفقا للشرط المحدد بواسطة المعلمة match_condition .
- match_condition
- MatchConditions
شرط المطابقة لاستخدامه على etag.
- analytical_storage_ttl
- int
وقت تخزين تحليلي للعيش (TTL) للعناصر الموجودة في الحاوية. قيمة None تترك التخزين التحليلي متوقفا عن التشغيل وقيمة -1 تعمل على تشغيل التخزين التحليلي بدون TTL. يرجى ملاحظة أنه لا يمكن تمكين التخزين التحليلي إلا على الحسابات الممكنة ل Synapse Link.
المرتجعات
مثيل ContainerProxy يمثل الحاوية الجديدة.
نوع الإرجاع
استثناءات
فشل إنشاء الحاوية.
أمثلة
إنشاء حاوية بالإعدادات الافتراضية:
container_name = "products"
try:
container = await database.create_container(
id=container_name, partition_key=PartitionKey(path="/productName")
)
except exceptions.CosmosResourceExistsError:
container = database.get_container_client(container_name)
إنشاء حاوية بإعدادات محددة؛ في هذه الحالة، مفتاح قسم مخصص:
customer_container_name = "customers"
try:
customer_container = await database.create_container(
id=customer_container_name,
partition_key=PartitionKey(path="/city"),
default_ttl=200,
)
except exceptions.CosmosResourceExistsError:
customer_container = database.get_container_client(customer_container_name)
create_container_if_not_exists
إنشاء حاوية إذا لم تكن موجودة بالفعل.
إذا كانت الحاوية موجودة بالفعل، يتم إرجاع الإعدادات الموجودة. ملاحظة: لا يتحقق من إعدادات الحاوية الموجودة أو يحدثها أو يقدم معدل نقل إذا كانت تختلف عما تم تمريره إلى الأسلوب.
async create_container_if_not_exists(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyالمعلمات
- default_ttl
- int
الوقت الافتراضي للعيش (TTL) للعناصر الموجودة في الحاوية. إذا لم يتم تحديدها، فلن تنتهي صلاحية العناصر.
- offer_throughput
- Union[int, ThroughputProperties]
معدل النقل المقدم لهذا العرض.
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
- etag
- str
قيمة ETag أو حرف البدل (*). يستخدم للتحقق مما إذا كان المورد قد تغير، والعمل وفقا للشرط المحدد بواسطة المعلمة match_condition .
- match_condition
- MatchConditions
شرط المطابقة لاستخدامه على etag.
- analytical_storage_ttl
- int
وقت تخزين تحليلي للعيش (TTL) للعناصر الموجودة في الحاوية. قيمة None تترك التخزين التحليلي متوقفا عن التشغيل وقيمة -1 تعمل على تشغيل التخزين التحليلي بدون TTL. يرجى ملاحظة أنه لا يمكن تمكين التخزين التحليلي إلا على الحسابات الممكنة ل Synapse Link.
المرتجعات
مثيل ContainerProxy يمثل الحاوية الجديدة.
نوع الإرجاع
استثناءات
فشل إنشاء الحاوية.
create_user
إنشاء مستخدم جديد في الحاوية.
لتحديث مستخدم موجود أو استبداله <xref:ContainerProxy.upsert_user> ، استخدم الأسلوب .
async create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxyالمعلمات
كائن يشبه الإملاء مع مفتاح معرف وقيمة تمثل المستخدم الذي سيتم إنشاؤه. يجب أن يكون معرف المستخدم فريدا داخل قاعدة البيانات، وأن يتكون من ما لا يزيد عن 255 حرفا.
المرتجعات
مثيل UserProxy يمثل المستخدم الجديد.
نوع الإرجاع
استثناءات
إذا تعذر إنشاء المستخدم المحدد.
أمثلة
إنشاء مستخدم قاعدة بيانات:
try:
await database.create_user(dict(id="Walter Harp"))
print("Created user Walter Harp.")
except exceptions.CosmosResourceExistsError:
print("A user with that ID already exists.")
except exceptions.CosmosHttpResponseError as failure:
print("Failed to create user. Status code:{}".format(failure.status_code))
delete_container
حذف حاوية.
async delete_container(container: str | ContainerProxy | Dict[str, Any], **kwargs: Any) -> Noneالمعلمات
- container
- str أو Dict[str, Any] أو ContainerProxy
معرف (اسم) الحاوية المراد حذفها. يمكنك إما تمرير معرف الحاوية للحذف أو مثيل ContainerProxy أو إملاء يمثل خصائص الحاوية.
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
- etag
- str
قيمة ETag أو حرف البدل (*). يستخدم للتحقق مما إذا كان المورد قد تغير، والعمل وفقا للشرط المحدد بواسطة المعلمة match_condition .
- match_condition
- MatchConditions
شرط المطابقة لاستخدامه على etag.
نوع الإرجاع
استثناءات
إذا تعذر حذف الحاوية.
delete_user
احذف المستخدم المحدد من الحاوية.
async delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> Noneالمعلمات
المعرف (الاسم)، الإملاء الذي يمثل خصائص أو UserProxy مثيل المستخدم المراد حذفه.
نوع الإرجاع
استثناءات
لم يتم حذف المستخدم بنجاح.
المستخدم غير موجود في الحاوية.
get_container_client
احصل على ContainerProxy لحاوية ذات معرف محدد (اسم).
get_container_client(container: str | ContainerProxy | Dict[str, Any]) -> ContainerProxyالمعلمات
المعرف (الاسم) أو الإملاء الذي يمثل خصائص الحاوية أو ContainerProxy مثيلها للحصول عليها.
المرتجعات
مثيل ContainerProxy يمثل الحاوية.
نوع الإرجاع
استثناءات
فشل إنشاء الحاوية.
أمثلة
احصل على حاوية موجودة، ومعالجة فشل إذا تمت مواجهتها:
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
get_throughput
احصل على كائن ThroughputProperties لقاعدة البيانات هذه.
إذا لم يكن هناك ThroughputProperties موجود بالفعل لقاعدة البيانات، يتم رفع استثناء.
async get_throughput(**kwargs: Any) -> ThroughputPropertiesالمعلمات
استدعاء مع بيانات تعريف الاستجابة.
المرتجعات
معدل النقل لقاعدة البيانات.
نوع الإرجاع
استثناءات
لا توجد خصائص معدل النقل لقاعدة البيانات أو تعذر استرداد خصائص معدل النقل.
get_user_client
احصل على UserProxy لمستخدم بمعرف محدد.
get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxyالمعلمات
المعرف (الاسم) أو الإملاء الذي يمثل الخصائص أو UserProxy مثيل المستخدم الذي يجب الحصول عليه.
المرتجعات
مثيل UserProxy يمثل المستخدم الذي تم استرداده.
نوع الإرجاع
استثناءات
فشل إنشاء الحاوية.
list_containers
سرد الحاويات في قاعدة البيانات.
list_containers(**kwargs) -> AsyncItemPaged[Dict[str, Any]]المعلمات
- max_item_count
- int
الحد الأقصى لعدد العناصر التي سيتم إرجاعها في عملية التعداد.
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
استدعاء مع بيانات تعريف الاستجابة.
المرتجعات
AsyncItemPaged من خصائص الحاوية (dicts).
نوع الإرجاع
استثناءات
فشل إنشاء الحاوية.
أمثلة
سرد جميع الحاويات في قاعدة البيانات:
database = client.get_database_client(database_name)
async for container in database.list_containers():
print("Container ID: {}".format(container['id']))
list_users
سرد جميع المستخدمين في الحاوية.
list_users(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]المعلمات
- max_item_count
- int
الحد الأقصى لعدد المستخدمين الذين سيتم إرجاعهم في عملية التعداد.
استدعاء مع بيانات تعريف الاستجابة.
المرتجعات
AsyncItemPaged لخصائص المستخدم (dicts).
نوع الإرجاع
استثناءات
فشل إنشاء الحاوية.
query_containers
سرد خصائص الحاويات في قاعدة البيانات الحالية.
query_containers(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]المعلمات
صفيف اختياري من المعلمات للاستعلام. كل معلمة هي dict() مع مفاتيح "الاسم" و"القيمة".
- max_item_count
- int
الحد الأقصى لعدد العناصر التي سيتم إرجاعها في عملية التعداد.
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
استدعاء مع بيانات تعريف الاستجابة.
المرتجعات
AsyncItemPaged من خصائص الحاوية (dicts).
نوع الإرجاع
استثناءات
فشل إنشاء الحاوية.
query_users
إرجاع جميع المستخدمين المطابقة للاستعلام المحدد.
query_users(query: str | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]المعلمات
صفيف اختياري من المعلمات للاستعلام. كل معلمة هي dict() مع مفاتيح "الاسم" و"القيمة". يتم تجاهله إذا لم يتم توفير استعلام.
- max_item_count
- int
الحد الأقصى لعدد المستخدمين الذين سيتم إرجاعهم في عملية التعداد.
استدعاء مع بيانات تعريف الاستجابة.
المرتجعات
AsyncItemPaged لخصائص المستخدم (dicts).
نوع الإرجاع
استثناءات
فشل إنشاء الحاوية.
read
اقرأ خصائص قاعدة البيانات.
async read(**kwargs: Any) -> Dict[str, Any]المعلمات
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
المرتجعات
إملاء يمثل خصائص قاعدة البيانات
نوع الإرجاع
استثناءات
إذا تعذر استرداد قاعدة البيانات المحددة.
replace_container
إعادة تعيين خصائص الحاوية.
تستمر تغييرات الخصائص على الفور. ستتم إعادة تعيين أي خصائص غير محددة إلى قيمها الافتراضية.
async replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyالمعلمات
المعرف (الاسم)، الإملاء الذي يمثل خصائص الحاوية المراد استبدالها أو ContainerProxy مثيلها.
- default_ttl
- int
الوقت الافتراضي للعيش (TTL) للعناصر الموجودة في الحاوية. إذا لم يتم تحديدها، فلن تنتهي صلاحية العناصر.
- session_token
- str
رمز مميز للاستخدام مع تناسق الجلسة.
- etag
- str
قيمة ETag أو حرف البدل (*). يستخدم للتحقق مما إذا كان المورد قد تغير، والعمل وفقا للشرط المحدد بواسطة المعلمة match_condition .
- match_condition
- MatchConditions
شرط المطابقة لاستخدامه على etag.
- analytical_storage_ttl
- int
وقت تخزين تحليلي للعيش (TTL) للعناصر الموجودة في الحاوية. قيمة None تترك التخزين التحليلي متوقفا عن التشغيل وقيمة -1 تعمل على تشغيل التخزين التحليلي بدون TTL. يرجى ملاحظة أنه لا يمكن تمكين التخزين التحليلي إلا على الحسابات الممكنة ل Synapse Link.
المرتجعات
مثيل ContainerProxy يمثل الحاوية بعد اكتمال استبدالها.
نوع الإرجاع
استثناءات
يرفع إذا تعذر استبدال الحاوية. يتضمن ذلك ما إذا كانت الحاوية ذات المعرف المحدد غير موجودة.
أمثلة
أعد تعيين خاصية TTL على حاوية، واعرض الخصائص المحدثة:
# Set the TTL on the container to 3600 seconds (one hour)
await database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)
# Display the new TTL setting for the container
container_props = await database.get_container_client(container_name).read()
print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))
replace_throughput
استبدل معدل النقل على مستوى قاعدة البيانات.
إذا لم تكن هناك أي ThroughputProperties موجودة بالفعل لقاعدة البيانات، يتم رفع استثناء.
async replace_throughput(throughput: int | ThroughputProperties, **kwargs: Any) -> ThroughputPropertiesالمعلمات
المرتجعات
معدل النقل لقاعدة البيانات، تم تحديثه بمعدل نقل جديد.
نوع الإرجاع
استثناءات
لا توجد خصائص معدل النقل لقاعدة البيانات أو تعذر تحديث خصائص معدل النقل.
replace_user
يستبدل المستخدم المحدد إذا كان موجودا في الحاوية.
async replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxyالمعلمات
المعرف (الاسم)، الإملاء الذي يمثل خصائص أو UserProxy مثيل المستخدم المراد استبداله.
المرتجعات
مر مثيل UserProxy الذي يمثل المستخدم بعد استبداله.
نوع الإرجاع
استثناءات
إذا فشل استبدال أو لم يكن المستخدم بمعرف معين موجودا.
upsert_user
إدراج المستخدم المحدد أو تحديثه.
إذا كان المستخدم موجودا بالفعل في الحاوية، يتم استبداله. إذا لم يكن المستخدم موجودا بالفعل، يتم إدراجه.
async upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxyالمعلمات
المرتجعات
مثيل UserProxy يمثل المستخدم الذي تمت إعادة إدراجه.
نوع الإرجاع
استثناءات
إذا تعذر رفع شهادة المستخدم المحدد.
Azure SDK for Python