Package google.firestore.v1

الفهرس

• Firestore (واجهة)
• AggregationResult (رسالة)
• ArrayValue (رسالة)
• BatchGetDocumentsRequest (رسالة)
• BatchGetDocumentsResponse (رسالة)
• BatchWriteRequest (رسالة)
• BatchWriteResponse (رسالة)
• BeginTransactionRequest (رسالة)
• BeginTransactionResponse (رسالة)
• BitSequence (رسالة)
• BloomFilter (رسالة)
• CommitRequest (رسالة)
• CommitResponse (رسالة)
• CreateDocumentRequest (رسالة)
• Cursor (رسالة)
• DeleteDocumentRequest (رسالة)
• Document (رسالة)
• DocumentChange (رسالة)
• DocumentDelete (رسالة)
• DocumentMask (رسالة)
• DocumentRemove (رسالة)
• DocumentTransform (رسالة)
• DocumentTransform.FieldTransform (رسالة)
• DocumentTransform.FieldTransform.ServerValue (تعداد)
• ExecutionStats (رسالة)
• ExistenceFilter (رسالة)
• ExplainMetrics (رسالة)
• ExplainOptions (رسالة)
• GetDocumentRequest (رسالة)
• ListCollectionIdsRequest (رسالة)
• ListCollectionIdsResponse (رسالة)
• ListDocumentsRequest (رسالة)
• ListDocumentsResponse (رسالة)
• ListenRequest (رسالة)
• ListenResponse (رسالة)
• MapValue (رسالة)
• PartitionQueryRequest (رسالة)
• PartitionQueryResponse (رسالة)
• PlanSummary (رسالة)
• Precondition (رسالة)
• RollbackRequest (رسالة)
• RunAggregationQueryRequest (رسالة)
• RunAggregationQueryResponse (رسالة)
• RunQueryRequest (رسالة)
• RunQueryResponse (رسالة)
• StructuredAggregationQuery (رسالة)
• StructuredAggregationQuery.Aggregation (رسالة)
• StructuredAggregationQuery.Aggregation.Avg (رسالة)
• StructuredAggregationQuery.Aggregation.Count (رسالة)
• StructuredAggregationQuery.Aggregation.Sum (رسالة)
• StructuredQuery (رسالة)
• StructuredQuery.CollectionSelector (رسالة)
• StructuredQuery.CompositeFilter (رسالة)
• StructuredQuery.CompositeFilter.Operator (تعداد)
• StructuredQuery.Direction (تعداد)
• StructuredQuery.FieldFilter (رسالة)
• StructuredQuery.FieldFilter.Operator (تعداد)
• StructuredQuery.FieldReference (رسالة)
• StructuredQuery.Filter (رسالة)
• StructuredQuery.FindNearest (رسالة)
• StructuredQuery.FindNearest.DistanceMeasure (تعداد)
• StructuredQuery.Order (رسالة)
• StructuredQuery.Projection (رسالة)
• StructuredQuery.UnaryFilter (رسالة)
• StructuredQuery.UnaryFilter.Operator (تعداد)
• Target (رسالة)
• Target.DocumentsTarget (رسالة)
• Target.QueryTarget (رسالة)
• TargetChange (رسالة)
• TargetChange.TargetChangeType (تعداد)
• TransactionOptions (رسالة)
• TransactionOptions.ReadOnly (رسالة)
• TransactionOptions.ReadWrite (رسالة)
• UpdateDocumentRequest (رسالة)
• Value (رسالة)
• Write (رسالة)
• WriteRequest (رسالة)
• WriteResponse (رسالة)
• WriteResult (رسالة)

Firestore

خدمة Cloud Firestore

Cloud Firestore هي قاعدة بيانات لمستندات NoSQL وسريعة ومُدارة بالكامل بدون خادم ومستنِدة إلى السحابة الإلكترونية، وتعمل على تبسيط عملية تخزين البيانات ومزامنتها والاستعلام عن البيانات لتطبيقات الأجهزة الجوّالة والويب وتطبيقات إنترنت الأشياء على نطاق عالمي. وتوفر مكتبات العملاء التابعة لها مزامنة مباشرة ودعمًا بلا اتصال بالإنترنت، بينما تعمل ميزات الأمان وعمليات الدمج مع Firebase وGoogle Cloud Platform على تسريع إنشاء تطبيقات بدون خوادم فعليًا.

الدفعة الحصول على المستندات

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse) الحصول على مستندات متعددة لا نضمن لك إرجاع المستندات التي تم إرجاعها باستخدام هذه الطريقة بالترتيب نفسه الذي تم طلبها به. نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

كتابة مجمّعة

rpc BatchWrite(BatchWriteRequest) returns (BatchWriteResponse) يُطبق مجموعة من عمليات الكتابة. لا تطبق طريقة BatchWrite عمليات الكتابة على نحو ذري ويمكن أن تطبقها بدون ترتيب. لا تسمح الطريقة بأكثر من عملية كتابة واحدة لكل مستند. تنجح كل عملية كتابة أو تفشل بشكل مستقل. راجِع BatchWriteResponse لمعرفة حالة نجاح كل عملية كتابة. إذا كنت تتطلّب مجموعة من عمليات الكتابة المطبَّقة بشكلٍ كامل، استخدِم Commit بدلاً من ذلك. نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

بدء المعاملة
rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse) بدء معاملة جديدة نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

إتمام
rpc Commit(CommitRequest) returns (CommitResponse) إتمام معاملة، مع تعديل المستندات اختياريًا نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

إنشاء مستند
rpc CreateDocument(CreateDocumentRequest) returns (Document) ينشئ مستندًا جديدًا. نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

حذف المستند
rpc DeleteDocument(DeleteDocumentRequest) returns (Empty) حذف مستند نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

الحصول علىمستند
rpc GetDocument(GetDocumentRequest) returns (Document) للحصول على مستند واحد نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

أرقام تعريف ListCollectionId
rpc ListCollectionIds(ListCollectionIdsRequest) returns (ListCollectionIdsResponse) يسرد جميع معرّفات المجموعة أسفل مستند. نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

ListDocuments (مستندات القائمة)
rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse) يسرد المستندات. نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

الاستماع
rpc Listen(ListenRequest) returns (ListenResponse) الاستماع إلى التغييرات لا تتوفر هذه الطريقة إلا من خلال gRPC أو WebChannel (وليس REST). نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

طلب القسم

rpc PartitionQuery(PartitionQueryRequest) returns (PartitionQueryResponse) لتقسيم استعلام عن طريق عرض مؤشرات الأقسام التي يمكن استخدامها لتشغيل الاستعلام بشكل متوازٍ. مؤشرات التقسيم المعروضة هي نقاط تقسيم يمكن استخدامها بواسطة RunQuery كنقاط بداية/نهاية لنتائج الاستعلام. نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

العودة إلى الحالة السابقة
rpc Rollback(RollbackRequest) returns (Empty) إرجاع معاملة نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

طلب RunAggregationQuery

rpc RunAggregationQuery(RunAggregationQueryRequest) returns (RunAggregationQueryResponse) لتنفيذ طلب بحث عن تجميع. بدلاً من عرض نتائج Document مثل Firestore.RunQuery، تسمح واجهة برمجة التطبيقات هذه بتشغيل عملية تجميع لإنتاج سلسلة من ملفات AggregationResult من جهة الخادم. مثال على المستوى العالي: -- Return the number of documents in table given a filter. SELECT COUNT(*) FROM ( SELECT * FROM k where a = true ); نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

تنفيذ طلب البحث
rpc RunQuery(RunQueryRequest) returns (RunQueryResponse) لتنفيذ استعلام. نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

مستند تحديث
rpc UpdateDocument(UpdateDocumentRequest) returns (Document) لتعديل مستند أو إدراجه نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

كتابة
rpc Write(WriteRequest) returns (WriteResponse) يبث مجموعات تحديثات المستندات وعمليات حذفها بالترتيب. لا تتوفر هذه الطريقة إلا من خلال gRPC أو WebChannel (وليس REST). نطاقات الأذونات يتطلب هذا الإعداد أحد نطاقات OAuth التالية: https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

نتيجة التجميع

نتيجة حزمة واحدة من طلب تجميع Firestore.

مفاتيح aggregate_fields هي نفسها لجميع النتائج في طلب البحث عن التجميع، على عكس طلبات البحث في المستندات التي يمكن أن تحتوي على حقول مختلفة لكل نتيجة.

الحقول
aggregate_fields	map<string, Value> نتيجة دوال التجميع، مثل: COUNT(*) AS total_docs. المفتاح هو alias المعيّن لدالة التجميع عند الإدخال، ويساوي حجم هذه الخريطة عدد دوال التجميع في الاستعلام.

ArrayValue

قيمة مصفوفة.

الحقول
values[]	Value القيم في الصفيف

طلب مجمّع

طلب الحصول على Firestore.BatchGetDocuments

الحقول
database	string مطلوب. اسم قاعدة البيانات. بالتنسيق: projects/{project_id}/databases/{database_id}.
documents[]	string أسماء المستندات المطلوب استردادها بالتنسيق: projects/{project_id}/databases/{database_id}/documents/{document_path}. سيتعذر الطلب إذا لم يكن أي من المستند موردًا فرعيًا لـ database المحدَّد. سيتم إلغاء الأسماء المكررة.
mask	DocumentMask الحقول المطلوب عرضها. وفي حال تم تركها بدون ضبط، سيتم عرض جميع الحقول. إذا كان المستند يحتوي على حقل غير موجود في هذا القناع، لن يتم عرض هذا الحقل في الرد.
حقل الاتحاد consistency_selector. وضع الاتساق لهذه المعاملة وفي حال تم ترك السياسة بدون ضبط، سيتم تطبيق القيمة التلقائية على مستوى الاتساق القوي. يمكن أن يكون consistency_selector واحدًا فقط مما يلي:
transaction	bytes يقرأ المستندات في المعاملة.
new_transaction	TransactionOptions يبدأ معاملة جديدة ويقرأ المستندات. يتم استخدام القيمة التلقائية لمعاملة القراءة فقط. سيتم عرض معرِّف المعاملة الجديد كأول ردّ في مصدر البيانات.
read_time	Timestamp يقرأ المستندات كما كانت في الوقت المحدّد. ويجب أن يكون هذا الطابع الزمني للدقة بالميكرو ثانية خلال الساعة الماضية، أو إذا كانت ميزة "الاسترداد في نقطة زمنية" مفعَّلة، يمكن أن يكون أيضًا طابعًا زمنيًا لدقيقة كاملة خلال آخر 7 أيام.

استجابة BatchGetDocumentsResponse

الردّ الذي تم بثه لـ "Firestore.BatchGetDocuments"

الحقول
transaction	bytes المعاملة التي بدأت كجزء من هذا الطلب. سيتم ضبطه في الاستجابة الأولى فقط وفي حال ضبط السمة BatchGetDocumentsRequest.new_transaction في الطلب فقط.
read_time	Timestamp تمثّل هذه السمة وقت قراءة المستند. قد يكون هذا في ازدياد أحادي، وفي هذه الحالة، نضمن عدم تغيير المستندات السابقة في تدفق النتائج بين read_time وهذا الوقت.
حقل الاتحاد result. نتيجة واحدة. ويمكن أن يكون هذا الحقل فارغًا إذا كان الخادم يعرض معاملةً فقط. يمكن أن يكون result واحدًا فقط مما يلي:
found	Document المستند الذي تم طلبه
missing	string اسم المستند الذي تم طلبه ولكنه غير موجود. بالتنسيق: projects/{project_id}/databases/{database_id}/documents/{document_path}.

طلب مجمّع

طلب الحصول على Firestore.BatchWrite

الحقول
database	string مطلوب. اسم قاعدة البيانات. بالتنسيق: projects/{project_id}/databases/{database_id}.
writes[]	Write العبارات التي سيتم تطبيقها. لا تنطبق الطريقة على الكتابة بشكل كامل ولا تضمن الطلب. تنجح كل عملية كتابة أو تفشل بشكل مستقل. لا يمكنك الكتابة إلى المستند نفسه أكثر من مرة لكل طلب.
labels	map<string, string> التصنيفات المرتبطة بالكتابة المجمّعة

BatchWriteResponse

الرد من Firestore.BatchWrite

الحقول
write_results[]	WriteResult هي نتيجة تطبيق عمليات الكتابة. تتوافق نتيجة i-th write هذه مع الكتابة i-th في الطلب.
status[]	Status حالة تطبيق عمليات الكتابة. تتوافق حالة i-th write هذه مع i-th write في الطلب.

طلب بدء العملية

طلب الحصول على Firestore.BeginTransaction

الحقول
database	string مطلوب. اسم قاعدة البيانات. بالتنسيق: projects/{project_id}/databases/{database_id}.
options	TransactionOptions خيارات المعاملة يتم ضبط الإعدادات التلقائية على معاملة قراءة وكتابة.

بدء المعاملة

تمثّل هذه السمة الردّ على Firestore.BeginTransaction.

الحقول
transaction	bytes المعاملة التي بدأت.

تسلسل البت

يشير ذلك المصطلح إلى تسلسل من وحدات البت، ويتم ترميزه في مصفوفة بايت.

تخزّن كل بايت في مصفوفة البايت bitmap 8 بت من التسلسل. الاستثناء الوحيد هو البايت الأخير، الذي قد يخزن 8 بت أو أقل. تحدِّد padding عدد وحدات بت البايت الأخير الذي سيتم تجاهله على أنّه "مساحة متروكة". قيم "المساحة المتروكة" وحدات البت غير محددة ويجب تجاهلها.

لاسترداد البت الأول، البت 0، احسب: (bitmap[0] & 0x01) != 0. لاسترداد البت الثاني، البت 1، احسب: (bitmap[0] & 0x02) != 0. لاسترداد البت الثالث، بت 2، احسب: (bitmap[0] & 0x04) != 0. لاسترداد البت الرابع، البت 3، احسب: (bitmap[0] & 0x08) != 0. لاسترداد البت ن، احسب: (bitmap[n / 8] & (0x01 << (n % 8))) != 0.

"الحجم" يتم حساب BitSequence (عدد وحدات البت التي تحتوي عليها) باستخدام هذه الصيغة: (bitmap.length * 8) - padding.

الحقول
bitmap	bytes وحدات البايت التي تشفِّر تسلسل البت. وقد يكون طولها صفرًا.
padding	int32 عدد وحدات بت للبايت الأخير في bitmap المطلوب تجاهلها كـ "مساحة متروكة". إذا كان طول الدالة bitmap صفرًا، يجب أن تكون هذه القيمة 0. وبخلاف ذلك، يجب أن تكون هذه القيمة بين 0 و7، بشكل شامل.

فلتر BloomFilter

فلتر بلوم (https://en.wikipedia.org/wiki/Bloom_filter)

يعمل فلتر Bloom على تجزئة الإدخالات باستخدام MD5 ويتعامل مع تجزئة 128 بت الناتجة كقيمتَين مختلفتَين لتجزئة 64 بت، ويتم تفسيرهما كأعداد صحيحة غير موقَّعة باستخدام ترميز 2 تكامل.

ويتم بعد ذلك استخدام قيمتَي التجزئة، المُسمّى h1 وh2، لاحتساب قيم تجزئة hash_count باستخدام الصيغة، بدءًا من i=0:

h(i) = h1 + (i * h2)

بعد ذلك، تؤخذ هذه القيم الناتجة في قالب حسب عدد وحدات البت في فلتر الإزهار للحصول على وحدات بت هذا الفلتر ليتم اختبارها على الإدخال المحدد.

الحقول
bits	BitSequence بيانات فلتر الزهور
hash_count	int32 عدد علامات التجزئة التي تستخدمها الخوارزمية.

تنفيذ الطلب

طلب الحصول على Firestore.Commit

الحقول
database	string مطلوب. اسم قاعدة البيانات. بالتنسيق: projects/{project_id}/databases/{database_id}.
writes[]	Write العبارات التي سيتم تطبيقها. يتم تنفيذها دائمًا بشكل كامل وبالترتيب.
transaction	bytes في حال ضبط هذه السياسة، يتم تطبيق جميع عمليات الشراء في هذه المعاملة والالتزام بها.

الالتزام بالاستجابة

تمثّل هذه السمة الردّ على Firestore.Commit.

الحقول
write_results[]	WriteResult هي نتيجة تطبيق عمليات الكتابة. تتوافق نتيجة i-th write هذه مع الكتابة i-th في الطلب.
commit_time	Timestamp وقت حدوث الالتزام. يمكن ضمان ظهور تأثيرات عملية الإتمام عند قراءة قيمة مساوية لقيمة read_time أو أكبر.

إنشاء طلب مستند

طلب الحصول على Firestore.CreateDocument

الحقول
parent	string مطلوب. المرجع الرئيسي. على سبيل المثال: projects/{project_id}/databases/{database_id}/documents أو projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}
collection_id	string مطلوب. رقم تعريف المجموعة المرتبط بـ parent في القائمة. مثلاً: chatrooms
document_id	string رقم تعريف المستند الذي خصّصه العميل لاستخدامه لهذا المستند. هذه السمة اختيارية. إذا لم يتم تحديد هذا الحقل، سيتم تخصيص معرّف من قِبل الخدمة.
document	Document مطلوب. المستند المراد إنشاؤه. يجب عدم ضبط name.
mask	DocumentMask الحقول المطلوب عرضها. وفي حال تم تركها بدون ضبط، سيتم عرض جميع الحقول. إذا كان المستند يحتوي على حقل غير موجود في هذا القناع، لن يتم عرض هذا الحقل في الرد.

المؤشر

تمثّل هذه السمة موضعًا في مجموعة نتائج طلب بحث.

الحقول
values[]	Value القيم التي تمثل موضعًا، بالترتيب الذي تظهر به بالترتيب حسب عبارة الاستعلام. يمكن أن يحتوي على قيم أقل مما هو محدّد في الترتيب حسب العبارة.
before	bool إذا كان الموضع قبل القيم المحددة مباشرةً أو بعدها مباشرةً، نسبةً إلى ترتيب الترتيب المحدّد في طلب البحث.

طلب حذف مستند

طلب الحصول على Firestore.DeleteDocument

الحقول
name	string مطلوب. اسم المورد للمستند المطلوب حذفه. بالتنسيق: projects/{project_id}/databases/{database_id}/documents/{document_path}.
current_document	Precondition شرط مُسبَق اختياري في المستند. سيتعذّر الطلب إذا تم ضبط ذلك ولم يتم استيفاؤه من خلال المستند المستهدف.

مستند

مستند Firestore

يجب ألا تتجاوز 1 مبيبايت إلى 4 بايت.

الحقول
name	string اسم المورد للمستند، على سبيل المثال projects/{project_id}/databases/{database_id}/documents/{document_path}.
fields	map<string, Value>
create_time	Timestamp النتائج فقط. وقت إنشاء المستند. تزداد هذه القيمة بشكل رتيب عند حذف مستند ثم إعادة إنشائه. ويمكن أيضًا مقارنتها بالقيم من مستندات أخرى وread_time من طلب بحث.
update_time	Timestamp النتائج فقط. آخر وقت تم فيه تغيير المستند. يتم ضبط هذه القيمة في البداية على create_time ثم تزداد بشكل رتيب مع كل تغيير يتم إجراؤه على المستند. ويمكن أيضًا مقارنتها بالقيم من مستندات أخرى وread_time من طلب بحث.

تغيير المستند

تم تغيير Document.

قد يكون ذلك نتيجة عمليات writes متعددة، بما في ذلك عمليات الحذف، والتي نتج عنها في النهاية قيمة جديدة لـ Document.

قد يتم عرض رسائل DocumentChange متعددة للتغيير المنطقي نفسه، في حال تأثّر أهداف متعددة.

الحقول
document	Document الحالة الجديدة لـ Document. في حال ضبط السياسة mask، لن يحتوي إلا على الحقول التي تم تعديلها أو إضافتها.
target_ids[]	int32 مجموعة من أرقام تعريف الاستهدافات المستهدفة التي تتطابق مع هذا المستند.
removed_target_ids[]	int32 مجموعة من أرقام التعريف المستهدفة للأهداف التي لم تعُد تتطابق مع هذا المستند.

حذف المستند

تم حذف Document.

قد يكون ذلك نتيجة عمليات writes متعددة، بما في ذلك التعديلات، آخرها حذف Document.

يمكن عرض رسائل DocumentDelete متعددة للحذف المنطقي نفسه، في حال تأثرت أهداف متعددة.

الحقول
document	string اسم المورد Document الذي تم حذفه.
removed_target_ids[]	int32 مجموعة من أرقام التعريف المستهدفة للأهداف التي تطابقت سابقًا مع هذا الكيان.
read_time	Timestamp الطابع الزمني للقراءة الذي تم فيه رصد عملية الحذف. أكبر من أو يساوي commit_time للحذف.

قناع مستند

مجموعة من مسارات الحقول في مستند يتم استخدامه لتقييد عملية الحصول أو التحديث على مستند إلى مجموعة فرعية من حقوله. ويختلف ذلك عن أقنعة الحقل العادية، لأنّه يتم تحديد نطاقها دائمًا على Document، ويستند إلى الطبيعة الديناميكية لـ Value.

الحقول
field_paths[]	string قائمة مسارات الحقول في القناع اطّلِع على Document.fields للحصول على مرجع بنية مسار الحقل.

إزالة المستند

تمت إزالة Document من عرض الأهداف.

يتم إرساله إذا لم يعُد المستند مناسبًا لأحد الأهداف ولم يعُد معروضًا. يمكن إرسالها بدلاً من DocumentDelete أو DocumentChange إذا لم يتمكن الخادم من إرسال القيمة الجديدة للمستند.

يمكن عرض رسائل DocumentRemove متعددة للكتابة أو الحذف المنطقي نفسه، إذا تأثّرت أهداف متعددة.

الحقول
document	string اسم مورد Document الذي تعذَّر عرضه.
removed_target_ids[]	int32 مجموعة من أرقام التعريف المستهدفة للأهداف التي تطابقت سابقًا مع هذا المستند.
read_time	Timestamp الطابع الزمني للقراءة الذي تم فيه رصد عملية الإزالة أكبر أو يساوي commit_time للتغيير/الحذف/الإزالة.

تحويل المستند

تحويل المستند.

الحقول
document	string اسم المستند المطلوب تحويله.
field_transforms[]	FieldTransform قائمة عمليات التحويل المطلوب تطبيقها على حقول المستند بالترتيب. يجب ألا يكون هذا الحقل فارغًا.

تحويل الحقل

تحويل حقل المستند.

الحقول
field_path	string مسار الحقل. راجِع Document.fields للاطّلاع على مرجع بنية مسار الحقل.
حقل الاتحاد transform_type. التحويل المراد تطبيقه على أرض الواقع. يمكن أن يكون transform_type واحدًا فقط مما يلي:
set_to_server_value	ServerValue لضبط الحقل على قيمة الخادم المحدّدة.
increment	Value لإضافة القيمة المحددة إلى القيمة الحالية للحقل يجب أن تكون هذه القيمة عددًا صحيحًا أو قيمة مزدوجة. إذا لم يكن الحقل عددًا صحيحًا أو مزدوجًا، أو إذا لم يكن الحقل متوفّرًا بعد، ستضبط عملية التحويل الحقل على القيمة المحدّدة. إذا كانت أي من القيمة المحددة أو قيمة الحقل الحالي مزدوجة، فسيتم تفسير كلتا القيمتين على أنهما زوجيتان. العمليات الحسابية المزدوجة وتمثيل القيم المزدوجة تتبع دلالات IEEE 754. إذا كان هناك فائض عدد صحيح موجب/سالب، يتم التعامل مع الحقل إلى أكبر عدد صحيح موجب/سالب.
maximum	Value لضبط الحقل على الحد الأقصى لقيمته الحالية والقيمة المحدّدة. يجب أن تكون هذه القيمة عددًا صحيحًا أو قيمة مزدوجة. إذا لم يكن الحقل عددًا صحيحًا أو مزدوجًا، أو إذا لم يكن الحقل متوفّرًا بعد، ستضبط عملية التحويل الحقل على القيمة المحدّدة. إذا تم تطبيق عملية الحد الأقصى حيث يكون الحقل وقيمة الإدخال من أنواع مختلطة (أي - واحد يمثل عددًا صحيحًا والآخر مزدوج) سيتخذ الحقل نوع المعامل الأكبر. إذا كانت المعاملات متكافئة (مثل 3 و3.0)، لن يتغيّر الحقل. 0 و0.0 و-0.0 جميعها صفرية. الحد الأقصى لقيمة مخزنة يكون فيها صفر وقيمة إدخال صفرية هو دائمًا القيمة المخزّنة. الحد الأقصى لأي قيمة رقمية x وNaN هو NaN.
minimum	Value لضبط الحقل على الحد الأدنى لقيمته الحالية والقيمة المحدّدة. يجب أن تكون هذه القيمة عددًا صحيحًا أو قيمة مزدوجة. إذا لم يكن الحقل عددًا صحيحًا أو مزدوجًا، أو إذا لم يكن الحقل متاحًا بعد، ستضبط عملية التحويل الحقل على قيمة الإدخال. إذا تم تطبيق عملية أدنى حيث يكون الحقل وقيمة الإدخال من أنواع مختلطة (أي - واحد يمثل عددًا صحيحًا والآخر زوجيًا) يأخذ الحقل نوع المعامل الأصغر. إذا كانت المعاملات متكافئة (مثل 3 و3.0)، لن يتغيّر الحقل. 0 و0.0 و-0.0 جميعها صفرية. الحد الأدنى لقيمة مخزنة صفرية وقيمة إدخال صفرية هو دائمًا القيمة المخزنة. الحد الأدنى لأي قيمة رقمية x وNaN هو NaN.
append_missing_elements	ArrayValue إلحاق العناصر المحددة بالترتيب إذا لم تكن موجودة من قبل في قيمة الحقل الحالي. إذا لم يكن الحقل صفيفًا، أو لم يكن الحقل متوفّرًا بعد، يتم تعيينه أولاً على الصفيف الفارغ. تعتبر الأرقام المكافئة للأنواع المختلفة (مثل 3L و3.0) متساوية عند التحقق مما إذا كانت القيمة مفقودة. NaN تساوي NaN، وNull تساوي Null. إذا كان الإدخال يحتوي على قيم مكافئة متعددة، سيتم مراعاة القيمة الأولى فقط. وستكون قيمة transform_result المقابلة هي القيمة الفارغة.
remove_all_from_array	ArrayValue إزالة كافة العناصر المحددة من الصفيف في الحقل. إذا لم يكن الحقل مصفوفة، أو لم يكن الحقل متاحًا بعد، سيتم ضبطه على مصفوفة فارغة. وتُعد الأرقام المكافئة للأنواع المختلفة (مثل 3L و3.0) متساوية عند تحديد ما إذا كان يجب إزالة عنصر أم لا. NaN تساوي NaN، وNull تساوي Null. سيؤدي هذا إلى إزالة جميع القيم المكافئة في حالة وجود تكرارات. وستكون قيمة transform_result المقابلة هي القيمة الفارغة.

قيمة الخادم

يشير ذلك المصطلح إلى قيمة يحتسبها الخادم.

تعدادات
SERVER_VALUE_UNSPECIFIED	غير محدَّد يجب عدم استخدام هذه القيمة.
REQUEST_TIME	الوقت الذي عالج فيه الخادم الطلب، بدقة ملي ثانية. في حال استخدام هذه الحقول في حقول متعدّدة (المستندات نفسها أو مستندات مختلفة) في معاملة، ستحصل على الطابع الزمني نفسه للخادم.

إحصائيات التنفيذ

إحصاءات التنفيذ الخاصة بطلب البحث

الحقول
results_returned	int64 إجمالي عدد النتائج التي تم عرضها، بما في ذلك المستندات والتوقعات ونتائج التجميع والمفاتيح.
execution_duration	Duration يشير ذلك المصطلح إلى الوقت الإجمالي اللازم لتنفيذ طلب البحث في الخلفية.
read_operations	int64 إجمالي عمليات القراءة القابلة للفوترة.
debug_stats	Struct تصحيح أخطاء الإحصاءات من تنفيذ طلب البحث. ويُرجى العِلم بأنّ إحصاءات تصحيح الأخطاء عرضة للتغيير مع تطوّر Firestore. يمكن أن يتضمن: { "indexes_entries_scan": "1000", "documents_scan": "20", "billing_details" : { "documents_billable": "20", "index_entries_billable": "1000", "min_query_cost": "0" } }

فلتر التواجد

هو ملخّص لجميع المستندات التي تتطابق مع هدف معيّن.

الحقول
target_id	int32 رقم تعريف الاستهداف الذي ينطبق عليه هذا الفلتر.
count	int32 إجمالي عدد المستندات التي تطابق target_id. إذا كان مختلفًا عن عدد المستندات المطابقة في البرنامج، على العميل أن يحدد يدويًا المستندات التي لم تعد تتطابق مع الهدف. يمكن للعميل استخدام فلتر بلوم unchanged_names للمساعدة في هذا التحديد من خلال اختبار جميع أسماء المستندات وفقًا للفلتر. إذا لم يكُن اسم المستند مدرَجًا في الفلتر، هذا يعني أنّ المستند لم يعُد مطابقًا للهدف.
unchanged_names	BloomFilter فلتر Bloom يحتوي، على الرغم من اسمه، على ترميزات UTF-8 بايت لأسماء الموارد لجميع المستندات التي تطابق target_id، بالتنسيق projects/{project_id}/databases/{database_id}/documents/{document_path}. قد يتم حذف فلتر الإزهار هذا وفقًا لتقدير الخادم، مثلاً إذا تم اعتبار أن العميل لن يستخدم هذا الفلتر أو إذا كان حسابه أو نقله مكلفًا من الناحية الحسابية. يجب أن يتعامل العملاء بسلاسة مع غياب هذا الحقل من خلال الرجوع إلى المنطق المستخدم قبل وجود هذا الحقل. أي إعادة إضافة الهدف بدون رمز سيرة ذاتية مميز لمعرفة المستندات في ذاكرة التخزين المؤقت للعميل غير المتزامنة.

شرح المقاييس

شرح مقاييس الاستعلام.

الحقول
plan_summary	PlanSummary معلومات مرحلة التخطيط للاستعلام.
execution_stats	ExecutionStats إحصاءات مجمعة من تنفيذ طلب البحث. لا تتوفّر هذه الميزة إلا عند ضبط ExplainOptions.analyze على "صحيح".

أسباب الشرح

شرح خيارات الاستعلام.

الحقول
analyze	bool هذه السمة اختيارية. ما إذا كان سيتم تنفيذ هذا الاستعلام أم لا. أمّا في حال اختيار القيمة false (الإعداد التلقائي)، فسيتم التخطيط لطلب البحث، وسيتمّ عرض المقاييس من مراحل التخطيط فقط. عندما تكون القيمة true، سيتم تخطيط طلب البحث وتنفيذه، وسيتم عرض نتائج طلب البحث الكاملة بالإضافة إلى مقاييس مرحلة التخطيط والتنفيذ.

طلب GetDocumentRequest

طلب الحصول على Firestore.GetDocument

الحقول
name	string مطلوب. اسم المورد للمستند الذي تريد الحصول عليه بالتنسيق: projects/{project_id}/databases/{database_id}/documents/{document_path}.
mask	DocumentMask الحقول المطلوب عرضها. وفي حال تم تركها بدون ضبط، سيتم عرض جميع الحقول. إذا كان المستند يحتوي على حقل غير موجود في هذا القناع، لن يتم عرض هذا الحقل في الرد.
حقل الاتحاد consistency_selector. وضع الاتساق لهذه المعاملة وفي حال تم ترك السياسة بدون ضبط، سيتم تطبيق القيمة التلقائية على مستوى الاتساق القوي. يمكن أن يكون consistency_selector واحدًا فقط مما يلي:
transaction	bytes يقرأ المستند في إحدى المعاملات.
read_time	Timestamp يقرأ نسخة المستند في الوقت المحدد. ويجب أن يكون هذا الطابع الزمني للدقة بالميكرو ثانية خلال الساعة الماضية، أو إذا كانت ميزة "الاسترداد في نقطة زمنية" مفعَّلة، يمكن أن يكون أيضًا طابعًا زمنيًا لدقيقة كاملة خلال آخر 7 أيام.

طلب ListCollectionIds

طلب الحصول على Firestore.ListCollectionIds

الحقول
parent	string مطلوب. المستند الرئيسي بالتنسيق: projects/{project_id}/databases/{database_id}/documents/{document_path}. مثلاً: projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
page_size	int32 الحد الأقصى لعدد النتائج المطلوب عرضها.
page_token	string رمز مميّز للصفحة. يجب أن تكون القيمة من ListCollectionIdsResponse.
حقل الاتحاد consistency_selector. وضع الاتساق لهذا الطلب. وفي حال تم ترك السياسة بدون ضبط، سيتم تطبيق القيمة التلقائية على مستوى الاتساق القوي. يمكن أن يكون consistency_selector واحدًا فقط مما يلي:
read_time	Timestamp يقرأ المستندات كما كانت في الوقت المحدّد. ويجب أن يكون هذا الطابع الزمني للدقة بالميكرو ثانية خلال الساعة الماضية، أو إذا كانت ميزة "الاسترداد في نقطة زمنية" مفعَّلة، يمكن أن يكون أيضًا طابعًا زمنيًا لدقيقة كاملة خلال آخر 7 أيام.

الاستجابة لـ ListCollectionIds

الرد من Firestore.ListCollectionIds

الحقول
collection_ids[]	string معرّفات المجموعات
next_page_token	string هو رمز مميّز للصفحة يمكن استخدامه لمتابعة القائمة.

طلب ListDocumentsRequest

طلب الحصول على Firestore.ListDocuments

الحقول
parent	string مطلوب. اسم المورد الرئيسي. بالتنسيق: projects/{project_id}/databases/{database_id}/documents أو projects/{project_id}/databases/{database_id}/documents/{document_path}. على سبيل المثال: projects/my-project/databases/my-database/documents أو projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
collection_id	string هذه السمة اختيارية. رقم تعريف المجموعة المرتبط بـ parent في القائمة. على سبيل المثال: chatrooms أو messages هذا الإجراء اختياري، وفي حال عدم توفيره، سيُدرج Firestore المستندات من كل المجموعات ضمن parent المقدَّم.
page_size	int32 هذه السمة اختيارية. الحد الأقصى لعدد المستندات المطلوب عرضها في رد واحد. قد تعرض Firestore عددًا أقل من هذه القيمة.
page_token	string هذه السمة اختيارية. رمز مميّز للصفحة، تم تلقّيه من رد ListDocuments سابق. يمكنك توفير هذا الحقل لاسترداد الصفحة التالية. عند التقسيم على صفحات، يجب أن تتطابق جميع المَعلمات الأخرى (باستثناء page_size) مع القيم المحدَّدة في الطلب الذي أنشأ الرمز المميّز للصفحة.
order_by	string هذه السمة اختيارية. الترتيب الاختياري للمستندات المطلوب عرضها مثلاً: priority desc, __name__ desc يعكس هذا ORDER BY المستخدم في طلبات بحث Firestore ولكن في تمثيل سلسلة. عند عدم توفّر هذه المستندات، يتم ترتيب المستندات استنادًا إلى __name__ ASC.
mask	DocumentMask هذه السمة اختيارية. الحقول المطلوب عرضها. وفي حال تم تركها بدون ضبط، سيتم عرض جميع الحقول. إذا كان المستند يحتوي على حقل غير موجود في هذا القناع، لن يتم عرض هذا الحقل في الرد.
show_missing	bool ما إذا كان يجب أن تُظهر القائمة المستندات المفقودة. أحد المستندات مفقود إذا لم يكن موجودًا، ولكن توجد مستندات فرعية متداخلة أسفله. عندما تكون القيمة true، سيتم عرض هذه المستندات المفقودة باستخدام مفتاح ولكن لن تحتوي على مجموعة من الحقول، أو create_time أو update_time. لا يجوز أن تحدّد الطلبات مع show_missing السمة where أو order_by.
حقل الاتحاد consistency_selector. وضع الاتساق لهذه المعاملة وفي حال تم ترك السياسة بدون ضبط، سيتم تطبيق القيمة التلقائية على مستوى الاتساق القوي. يمكن أن يكون consistency_selector واحدًا فقط مما يلي:
transaction	bytes يُرجى إجراء القراءة كجزء من معاملة نشطة حاليًا.
read_time	Timestamp نفِّذ القراءة في الوقت المحدَّد. ويجب أن يكون هذا الطابع الزمني للدقة بالميكرو ثانية خلال الساعة الماضية، أو إذا كانت ميزة "الاسترداد في نقطة زمنية" مفعَّلة، يمكن أن يكون أيضًا طابعًا زمنيًا لدقيقة كاملة خلال آخر 7 أيام.

رد ListDocumentsResponse

تمثّل هذه السمة الردّ على Firestore.ListDocuments.

الحقول
documents[]	Document تم العثور على "المستندات"
next_page_token	string رمز مميز لاسترداد الصفحة التالية من المستندات. في حال إسقاط هذا الحقل، لن تظهر أي صفحات لاحقة.

طلب الاستماع

طلب للحصول على Firestore.Listen

الحقول
database	string مطلوب. اسم قاعدة البيانات. بالتنسيق: projects/{project_id}/databases/{database_id}.
labels	map<string, string> التصنيفات المرتبطة بهذا التغيير المستهدف.
حقل الاتحاد target_change. يتغيّر الاستهداف المتوافق. يمكن أن يكون target_change واحدًا فقط مما يلي:
add_target	Target هدف مطلوب إضافته إلى مصدر البيانات هذا.
remove_target	int32 رقم تعريف الهدف المطلوب إزالته من مصدر البيانات هذا.

استجابة الاستماع

تمثّل هذه السمة الردّ على Firestore.Listen.

الحقول
حقل الاتحاد response_type. الاستجابات المتوافقة. يمكن أن يكون response_type واحدًا فقط مما يلي:
target_change	TargetChange تم تغيير الأهداف.
document_change	DocumentChange تم تغيير Document.
document_delete	DocumentDelete تم حذف Document.
document_remove	DocumentRemove تمت إزالة Document من استهداف (لأنه لم يعد ذا صلة بذلك الهدف).
filter	ExistenceFilter عامل تصفية لتطبيقه على مجموعة المستندات التي تم عرضها سابقًا للهدف المحدّد. يتم عرضه عندما ربما تمت إزالة المستندات من الهدف المحدد، لكن المستندات الدقيقة غير معروفة.

قيمة خريطة

قيمة الخريطة.

الحقول
fields	map<string, Value> حقول الخريطة. تمثل مفاتيح الخريطة أسماء الحقول. تم حجز أسماء الحقول التي تتطابق مع التعبير العادي __.*__. ويُحظر استخدام أسماء الحقول المحجوزة إلا في سياقات موثقة معينة. يجب ألا تتجاوز مفاتيح الخريطة، المُمثلة بترميز UTF-8، 1500 بايت ولا يمكن أن تكون فارغة.

طلب التقسيم

طلب الحصول على Firestore.PartitionQuery

الحقول
parent	string مطلوب. اسم المورد الرئيسي. بالتنسيق: projects/{project_id}/databases/{database_id}/documents. أسماء موارد المستندات غير متوافقة؛ يمكن تحديد أسماء موارد قاعدة البيانات فقط.
partition_count	int64 تمثّل هذه السمة الحد الأقصى المطلوب لعدد نقاط التقسيم. وقد يتم عرض الأقسام على مستوى صفحات نتائج متعددة. يجب أن يكون الرقم موجبًا. قد يكون العدد الفعلي للأقسام التي تم عرضها أقل. على سبيل المثال، قد يتم ضبط ذلك على عدد أقل بمقدار واحد من عدد طلبات البحث المتوازية المراد تشغيلها، أو عند تشغيل مهمة مسار بيانات، أقل من عدد العاملين أو مثيلات الحوسبة المتاحة.
page_token	string القيمة next_page_token التي تم عرضها من استدعاء سابق إلى PartitionQuery والتي يمكن استخدامها للحصول على مجموعة إضافية من النتائج. وليس هناك ضمانات ترتيب بين مجموعات النتائج. وبالتالي، سيتطلب استخدام مجموعات متعددة من النتائج دمج مجموعات النتائج المختلفة. على سبيل المثال، قد يتم عرض طلبَين تاليَين يستخدمان page_token: المؤشر B، المؤشر M، المؤشر Q المؤشر A، المؤشر U، المؤشر W للحصول على مجموعة نتائج كاملة مرتبة حسب نتائج طلب البحث المقدمة إلى PartitionQuery، يجب دمج مجموعات النتائج: المؤشر A والمؤشر B والمؤشر M والمؤشر Q والمؤشر U والمؤشر W
page_size	int32 الحد الأقصى لعدد الأقسام المطلوب عرضها في هذه المكالمة، ويخضع لـ partition_count. على سبيل المثال، إذا كانت partition_count = 10 وpage_size = 8، سيعرض الاستدعاء الأول لـ PartitionQuery ما يصل إلى 8 أقسام وnext_page_token في حالة توفر المزيد من النتائج. سيؤدي الاستدعاء الثاني لـ PartitionQuery إلى قسمين مما يصل إلى قسمين لإكمال إجمالي 10 أقسام محددة في partition_count.
حقل الاتحاد query_type. الاستعلام المطلوب تقسيمه. يمكن أن يكون query_type واحدًا فقط مما يلي:
structured_query	StructuredQuery طلب بحث منظم. يجب أن يحدد طلب البحث مجموعة تضم كل العناصر التابعة وأن يتم ترتيبها حسب الاسم تصاعديًا. لا تتوفّر الفلاتر الأخرى، والترتيب حسب، والحدود، والإزاحة، ومؤشرات البدء/النهاية.
حقل الاتحاد consistency_selector. وضع الاتساق لهذا الطلب. وفي حال تم ترك السياسة بدون ضبط، سيتم تطبيق القيمة التلقائية على مستوى الاتساق القوي. يمكن أن يكون consistency_selector واحدًا فقط مما يلي:
read_time	Timestamp يقرأ المستندات كما كانت في الوقت المحدّد. ويجب أن يكون هذا الطابع الزمني للدقة بالميكرو ثانية خلال الساعة الماضية، أو إذا كانت ميزة "الاسترداد في نقطة زمنية" مفعَّلة، يمكن أن يكون أيضًا طابعًا زمنيًا لدقيقة كاملة خلال آخر 7 أيام.

ردّ على طلب التقسيم

تمثّل هذه السمة الردّ على Firestore.PartitionQuery.

الحقول
partitions[]	Cursor نتائج التقسيم كل قسم هو نقطة تقسيم يمكن استخدامها بواسطة RunQuery كنقطة بداية أو نهاية لنتائج الاستعلام. يجب إجراء طلبات RunQuery باستخدام طلب البحث نفسه المتوفّر في طلب PartitionQuery هذا. سيتم ترتيب مؤشرات أقسام التقسيم وفقًا للترتيب نفسه الخاص بنتائج طلب البحث المقدَّمة في PartitionQuery. على سبيل المثال، إذا عرض طلب PartitionQuery مؤشري القسمين A وB، فإن تشغيل الاستعلامات الثلاثة التالية سيُرجع مجموعة نتائج الاستعلام الأصلي بالكامل: استعلام، end_at A استعلام، start_at A، end_at B استعلام، start_at B قد تشير النتيجة الفارغة إلى أنّ عدد النتائج قليل جدًا ولا يمكن تقسيمها في طلب البحث، أو أنّ عملية التقسيم غير متاحة بعد.
next_page_token	string يشير هذا المصطلح إلى رمز مميّز للصفحة يمكن استخدامه لطلب مجموعة إضافية من النتائج، بما يصل إلى العدد المحدَّد من خلال partition_count في طلب التقسيم. إذا كان هذا الحقل فارغًا، هذا يعني أنّه ما مِن نتائج أخرى.

ملخص الخطة

معلومات مرحلة التخطيط للاستعلام.

الحقول
indexes_used[]	Struct الفهارس المحددة لطلب البحث. على سبيل المثال: [ {"query_scope": "Collection", " properties": "(foo ASC, name ASC)"}, {"query_scope": "Collection", "properties": "(bar ASC, name ASC)"} ]

شرط مُسبَق

شرط مسبق على مستند، يستخدم للعمليات الشرطية.

الحقول
حقل الاتحاد condition_type. تمثّل هذه السمة نوع الشرط المُسبَق. يمكن أن يكون condition_type واحدًا فقط مما يلي:
exists	bool عند ضبط هذه السياسة على true، يجب أن يكون المستند الهدف متوفرًا. عند ضبط هذه السياسة على false، يجب ألا يتوفّر المستند الهدف.
update_time	Timestamp عند ضبط هذه السياسة، يجب أن يكون المستند المستهدَف متاحًا وأن يكون آخر تعديل له في ذلك الوقت. يجب محاذاة الطابع الزمني بالميكرو ثانية.

طلب العودة إلى الحالة السابقة

طلب الحصول على Firestore.Rollback

الحقول
database	string مطلوب. اسم قاعدة البيانات. بالتنسيق: projects/{project_id}/databases/{database_id}.
transaction	bytes مطلوب. المعاملة المطلوب العودة إليها

طلب RunAggregationQuery

طلب الحصول على Firestore.RunAggregationQuery

الحقول
parent	string مطلوب. اسم المورد الرئيسي. بالتنسيق: projects/{project_id}/databases/{database_id}/documents أو projects/{project_id}/databases/{database_id}/documents/{document_path}. على سبيل المثال: projects/my-project/databases/my-database/documents أو projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
explain_options	ExplainOptions هذه السمة اختيارية. شرح خيارات الاستعلام. وفي حال ضبطها، سيتم عرض إحصاءات إضافية لطلبات البحث. وإذا لم يكن الأمر كذلك، فسيتم عرض نتائج الاستعلام فقط.
حقل الاتحاد query_type. الاستعلام المطلوب تنفيذه. يمكن أن يكون query_type واحدًا فقط مما يلي:
structured_aggregation_query	StructuredAggregationQuery طلب تجميع.
حقل الاتحاد consistency_selector. يتم ضبط وضع الاتساق لطلب البحث تلقائيًا على الاتساق القوي. يمكن أن يكون consistency_selector واحدًا فقط مما يلي:
transaction	bytes تنفيذ التجميع ضمن معاملة نشطة بالفعل. القيمة هنا هي معرّف المعاملة مبهم لتنفيذ الاستعلام فيه.
new_transaction	TransactionOptions بدء معاملة جديدة كجزء من طلب البحث، مع ضبط الإعداد التلقائي على القراءة فقط. سيتم عرض معرِّف المعاملة الجديد كأول ردّ في مصدر البيانات.
read_time	Timestamp لتنفيذ طلب البحث عند الطابع الزمني المحدّد. ويجب أن يكون هذا الطابع الزمني للدقة بالميكرو ثانية خلال الساعة الماضية، أو إذا كانت ميزة "الاسترداد في نقطة زمنية" مفعَّلة، يمكن أن يكون أيضًا طابعًا زمنيًا لدقيقة كاملة خلال آخر 7 أيام.

RunAggregationQueryResponse

تمثّل هذه السمة الردّ على Firestore.RunAggregationQuery.

الحقول
result	AggregationResult نتيجة تجميع واحدة. لا تتوفّر هذه الميزة عند الإبلاغ عن التقدّم الجزئي.
transaction	bytes المعاملة التي بدأت كجزء من هذا الطلب. لا تظهر إلا في الاستجابة الأولى عندما يطلب الطلب بدء معاملة جديدة.
read_time	Timestamp وقت حساب النتيجة المجمّعة. وهذا يتزايد دائمًا بصورة رتيبة؛ في هذه الحالة، نضمن عدم تغيير نتيجة التجميع السابقة في ساحة مشاركات النتائج بين read_time وهذه النتيجة. إذا لم يعرض طلب البحث أي نتائج، سيتم إرسال ردّ بـ read_time بدون result، ويمثّل ذلك وقت تنفيذ طلب البحث.
explain_metrics	ExplainMetrics مقاييس شرح طلب البحث ولا تتوفّر هذه السمة إلا عند توفير RunAggregationQueryRequest.explain_options، ويتم إرسالها مرة واحدة فقط مع آخر ردّ في ساحة المشاركات.

RunQueryRequest

طلب الحصول على Firestore.RunQuery

الحقول
parent	string مطلوب. اسم المورد الرئيسي. بالتنسيق: projects/{project_id}/databases/{database_id}/documents أو projects/{project_id}/databases/{database_id}/documents/{document_path}. على سبيل المثال: projects/my-project/databases/my-database/documents أو projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
explain_options	ExplainOptions هذه السمة اختيارية. شرح خيارات الاستعلام. وفي حال ضبطها، سيتم عرض إحصاءات إضافية لطلبات البحث. وإذا لم يكن الأمر كذلك، فسيتم عرض نتائج الاستعلام فقط.
حقل الاتحاد query_type. الاستعلام المطلوب تنفيذه. يمكن أن يكون query_type واحدًا فقط مما يلي:
structured_query	StructuredQuery طلب بحث منظم.
حقل الاتحاد consistency_selector. وضع الاتساق لهذه المعاملة وفي حال تم ترك السياسة بدون ضبط، سيتم تطبيق القيمة التلقائية على مستوى الاتساق القوي. يمكن أن يكون consistency_selector واحدًا فقط مما يلي:
transaction	bytes نفِّذ الاستعلام ضمن معاملة نشطة بالفعل. القيمة هنا هي معرّف المعاملة مبهم لتنفيذ الاستعلام فيه.
new_transaction	TransactionOptions يبدأ معاملة جديدة ويقرأ المستندات. يتم استخدام القيمة التلقائية لمعاملة القراءة فقط. سيتم عرض معرِّف المعاملة الجديد كأول ردّ في مصدر البيانات.
read_time	Timestamp يقرأ المستندات كما كانت في الوقت المحدّد. ويجب أن يكون هذا الطابع الزمني للدقة بالميكرو ثانية خلال الساعة الماضية، أو إذا كانت ميزة "الاسترداد في نقطة زمنية" مفعَّلة، يمكن أن يكون أيضًا طابعًا زمنيًا لدقيقة كاملة خلال آخر 7 أيام.

تنفيذ طلب الاستجابة

تمثّل هذه السمة الردّ على Firestore.RunQuery.

الحقول
transaction	bytes المعاملة التي بدأت كجزء من هذا الطلب. لا يمكن ضبط هذا الإعداد إلا في الرد الأول، وفي حال ضبط السمة RunQueryRequest.new_transaction في الطلب فقط. في حال ضبط هذه السياسة، لن يتم ضبط أي حقول أخرى في هذه الاستجابة.
document	Document نتيجة طلب بحث، لم يتم ضبطها عند الإبلاغ عن التقدّم الجزئي.
read_time	Timestamp تمثّل هذه السمة وقت قراءة المستند. وقد يكون هذا يزداد بصورة رتيبة؛ في هذه الحالة، نضمن عدم تغيير المستندات السابقة في تدفق النتائج بين read_time وهذا المستند. إذا لم يعرض طلب البحث أي نتائج، سيتم إرسال ردّ بـ read_time بدون document، ويمثّل ذلك وقت تنفيذ طلب البحث.
skipped_results	int32 عدد النتائج التي تم تخطّيها بسبب الفارق بين الردّ الأخير والاستجابة الحالية.
explain_metrics	ExplainMetrics مقاييس شرح طلب البحث ولا تتوفّر هذه السمة إلا عند توفير RunQueryRequest.explain_options، ويتم إرسالها مرة واحدة فقط مع آخر ردّ في ساحة المشاركات.
حقل الاتحاد continuation_selector. وضع المتابعة للاستعلام. في حال توفُّرها، يعني ذلك أنّ سلسلة الردود الحالية على طلب البحث قد انتهت. يمكن ضبط هذه السياسة مع توفُّر document أو بدونه، ولكن عند ضبطها، لن يتم عرض المزيد من النتائج. يمكن أن يكون continuation_selector واحدًا فقط مما يلي:
done	bool في حال توفّره، يعني ذلك أنّ Firestore قد أنهى الطلب بالكامل ولن يتم إرجاع المزيد من المستندات.

طلب البحث عن التجميع المنظَّم

طلب بحث Firestore لتشغيل تجميع على StructuredQuery

الحقول
aggregations[]	Aggregation هذه السمة اختيارية. سلسلة من التجميعات المطلوب تطبيقها على نتائج structured_query. يتطلب: ما لا يقل عن خمس تجميعات أو خمس مجموعات كحد أقصى لكل طلب بحث.
حقل الاتحاد query_type. الاستعلام الأساسي المطلوب تجميعه. يمكن أن يكون query_type واحدًا فقط مما يلي:
structured_query	StructuredQuery استعلام منظم متداخل.

التجميع

تحدد هذه السمة تجميعًا ينتج عنه نتيجة واحدة.

الحقول
alias	string هذه السمة اختيارية. اسم اختياري للحقل لتخزين نتيجة التجميع فيه. إذا لم يتم توفير الاسم، ستختار Firestore اسمًا تلقائيًا بالتنسيق field_<incremental_id++>. على سبيل المثال: AGGREGATE COUNT_UP_TO(1) AS count_up_to_1, COUNT_UP_TO(2), COUNT_UP_TO(3) AS count_up_to_3, COUNT(*) OVER ( ... ); يصبح: AGGREGATE COUNT_UP_TO(1) AS count_up_to_1, COUNT_UP_TO(2) AS field_1, COUNT_UP_TO(3) AS count_up_to_3, COUNT(*) AS field_2 OVER ( ... ); يتطلب: يجب أن يكون فريدًا على مستوى جميع الأسماء المستعارة للتجميع. يجب الامتثال لقيود document field name.
حقل الاتحاد operator. تمثّل هذه السمة نوع التجميع المطلوب تنفيذه. يمكن أن يكون operator واحدًا فقط مما يلي:
count	Count عدد مجمّع السلع.
sum	Sum مجمّع السلع.
avg	Avg متوسط مجمّع السلع.

Avg

متوسط قيم الحقل المطلوب.

• سيتم تجميع القيم الرقمية فقط. يتم تخطّي جميع القيم غير الرقمية بما في ذلك NULL.

• وإذا كانت القيم المجمّعة تحتوي على NaN، يتم عرض NaN. تتبع الرياضيات اللانهائية معايير IEEE-754.

• إذا كانت مجموعة القيم المجمّعة فارغة، يتم عرض NULL.

• يتم دائمًا عرض النتيجة على شكل مزدوج.

الحقول
field	FieldReference الحقل المطلوب تجميعه.

الإحصاء

عدد المستندات التي تطابق طلب البحث.

تعمل دالة التجميع COUNT(*) على المستند بأكمله، لذا لا تتطلب مرجعًا للحقل.

الحقول
up_to	Int64Value هذه السمة اختيارية. قيد اختياري على الحد الأقصى لعدد المستندات المطلوب احتسابها. يوفر ذلك طريقة لتعيين حد أقصى لعدد المستندات المطلوب مسحها ضوئيًا، والحد من وقت الاستجابة والتكلفة. ويتم تفسير القيمة "غير محدّد" على أنّها غير مشروطة. مثال على المستوى العالي: AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k ); يتطلب: يجب أن تكون القيمة أكبر من صفر عند وجودها.

المجموع

مجموع قيم الحقل المطلوب.

• سيتم تجميع القيم الرقمية فقط. يتم تخطّي جميع القيم غير الرقمية بما في ذلك NULL.

• وإذا كانت القيم المجمّعة تحتوي على NaN، يتم عرض NaN. تتبع الرياضيات اللانهائية معايير IEEE-754.

• إذا كانت مجموعة القيم المجمّعة فارغة، يتم عرض 0.

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

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

الحقول
field	FieldReference الحقل المطلوب تجميعه.

طلب البحث المنظَّم

استعلام Firestore.

يتم تنفيذ مراحل الاستعلام بالترتيب التالي: 1. من 2. حيث 3. حدد 4. order_by + start_at + end_at 5. الإزاحة 6. الحد

الحقول
select	Projection مجموعة فرعية اختيارية من الحقول المطلوب عرضها. يعمل هذا الإجراء كـ DocumentMask على المستندات التي يتم عرضها من طلب البحث. في حال ترك هذه السياسة بدون ضبط، يتم افتراض أنّ المتصل يريد عرض جميع الحقول.
from[]	CollectionSelector المجموعات المطلوب الاستعلام عنها.
where	Filter الفلتر المطلوب تطبيقه.
order_by[]	Order الترتيب الذي سيتم تطبيقه على نتائج الاستعلام. يتيح Firestore للمتصلين تقديم طلب كامل أو طلب جزئي أو عدم تقديم أي طلب على الإطلاق. في جميع الحالات، تضمن Firestore ترتيبًا ثابتًا من خلال القواعد التالية: يجب توفير order_by للإشارة إلى جميع الحقول المستخدَمة مع فلتر عدم المساواة. يتم إلحاق جميع الحقول المطلوبة في order_by ولكن لم يتم توفيرها بعد بترتيب قاموس لاسم الحقل. إذا لم يتم تحديد طلب في __name__، سيتم إلحاقه تلقائيًا. يتم إلحاق الحقول باتجاه الترتيب نفسه كآخر ترتيب محدّد، أو باستخدام "ASCENDING". إذا لم يتم تحديد أي طلب. على سبيل المثال: تغيّر اسم "ORDER BY a" ليصبح "ORDER BY a ASC, __name__ ASC" تغيّر اسم "ORDER BY a DESC" ليصبح "ORDER BY a DESC, __name__ DESC" تغيّر اسم "WHERE a > 1" ليصبح "WHERE a > 1 ORDER BY a ASC, __name__ ASC" تغيّر اسم "WHERE __name__ > ... AND a > 1" ليصبح "WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC"
start_at	Cursor بادئة محتملة لموضع في مجموعة النتائج لبدء طلب البحث عند. ويعتمد ترتيب مجموعة النتائج على عبارة ORDER BY من طلب البحث الأصلي. SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC; يتم ترتيب نتائج هذا الطلب حسب (b ASC, __name__ ASC). يمكن أن تشير المؤشرات إلى الترتيب الكامل أو بادئة الموقع الجغرافي، على الرغم من أنّه لا يمكن أن تشير إلى حقول أكثر من تلك المتوفّرة في سمة ORDER BY المقدَّمة. متابعة للمثال أعلاه، سيكون لإرفاق مؤشرات البدء التالية تأثير متفاوت: START BEFORE (2, /k/123): بدء الاستعلام قبل a = 1 AND b > 2 AND __name__ > /k/123 مباشرة. START AFTER (10): بدء طلب البحث بعد a = 1 AND b > 10 مباشرةً على عكس OFFSET الذي يتطلب فحص نتائج N الأولى لتخطيها، يسمح مؤشر البدء ببدء طلب البحث في موضع منطقي. هذا الموضع غير مطلوب ليطابق نتيجة فعلية، وسيتم فحصه بدءًا من هذا الموضع للعثور على المستند التالي. يتطلب: لا يمكن أن يكون عدد القيم أكبر من عدد الحقول المحدّدة في عبارة ORDER BY.
end_at	Cursor بادئة محتملة لموضع في مجموعة النتيجة لإنهاء طلب البحث عند. يشبه هذا الإجراء START_AT ولكن يتحكّم في موضع النهاية بدلاً من موضع البداية. يتطلب: لا يمكن أن يكون عدد القيم أكبر من عدد الحقول المحدّدة في عبارة ORDER BY.
offset	int32 عدد المستندات المطلوب تخطيها قبل عرض النتيجة الأولى. ينطبق ذلك بعد القيود المحدّدة في WHERE وSTART AT و END AT لكن قبل عبارة LIMIT. يتطلب: يجب أن تكون القيمة أكبر من صفر أو تساويه في حال تحديده.
limit	Int32Value الحد الأقصى لعدد النتائج المطلوب عرضها. يُطبق بعد كل القيود الأخرى. يتطلب: يجب أن تكون القيمة أكبر من صفر أو تساويه في حال تحديده.
find_nearest	FindNearest هذه السمة اختيارية. عملية بحث محتملة من الجيران الأقرب. ينطبق ذلك بعد كل الفلاتر الأخرى والترتيب. لإيجاد أقرب تضمينات المتجهة لمتجه الاستعلام المحدد.

أداة اختيار المجموعة

مجموعة مختارات، مثل messages as m1.

الحقول
collection_id	string معرّف المجموعة. وعند ضبط هذه السياسة، يتم فقط اختيار المجموعات التي تحمل هذا المعرّف.
all_descendants	bool وعند ضبط هذه السياسة على "خطأ"، يتم فقط اختيار المجموعات الثانوية المباشرة للسمة parent المحدّدة في العنصر RunQueryRequest الذي يتضمّن هذا العنصر. عند ضبط القيمة على "صحيح"، يتم اختيار كل المجموعات التابعة.

الفلتر المركّب

فلتر يدمج فلاتر أخرى متعددة باستخدام عامل التشغيل المحدد.

الحقول
op	Operator عامل دمج عوامل تصفية متعددة.
filters[]	Filter قائمة الفلاتر المطلوب دمجها يتطلب: هناك فلتر واحد على الأقل.

المؤثِّر

عامل تصفية مركب

تعدادات
OPERATOR_UNSPECIFIED	غير محدَّد يجب عدم استخدام هذه القيمة.
AND	يجب إدخال المستندات لاستيفاء جميع الفلاتر المدمجة.
OR	يجب أن تستوفي المستندات فلترًا واحدًا على الأقل من الفلاتر المدمجة.

توجيه المشاهدين لاتخاذ إجراء

اتجاه الفرز.

تعدادات
DIRECTION_UNSPECIFIED	غير محدَّد
ASCENDING	تصاعدي.
DESCENDING	تنازلي.

فلتر الحقل

فلتر على حقل معيّن

الحقول
field	FieldReference الحقل الذي تريد الفلترة حسبه.
op	Operator العامل المطلوب الفلترة حسبه.
value	Value القيمة المطلوب المقارنة بها.

المؤثِّر

عامل تصفية الحقل

تعدادات
OPERATOR_UNSPECIFIED	غير محدَّد يجب عدم استخدام هذه القيمة.
LESS_THAN	قيمة field المحدّدة أقل من قيمة value المحدّدة. يتطلب: تأتي "field" في المرتبة order_by.
LESS_THAN_OR_EQUAL	قيمة field المحدّدة أقل من أو تساوي value المحدَّد. يتطلب: تأتي "field" في المرتبة order_by.
GREATER_THAN	قيمة field المحدّدة أكبر من قيمة value المحدّدة. يتطلب: تأتي "field" في المرتبة order_by.
GREATER_THAN_OR_EQUAL	قيمة field المحدّدة أكبر من أو تساوي value المحدَّد. يتطلب: تأتي "field" في المرتبة order_by.
EQUAL	تساوي قيمة field المحدّدة قيمة value المحدّدة.
NOT_EQUAL	لا تساوي قيمة field المحدّدة قيمة value المحدّدة. يتطلب: ما مِن NOT_EQUAL أو NOT_IN أو IS_NOT_NULL أو IS_NOT_NAN أخرى. تأتي field في المركز الأول في order_by.
ARRAY_CONTAINS	field المحدّد هو مصفوفة تحتوي على السمة value المحددة.
IN	تساوي قيمة field المحدّدة قيمة واحدة على الأقل في المصفوفة المحدّدة. يتطلب: قيمة value هي ArrayValue غير فارغ، ويخضع لحدود الفصل. ما مِن فلاتر "NOT_IN" في طلب البحث نفسه.
ARRAY_CONTAINS_ANY	field المحدّد هو مصفوفة تتضمّن أيًّا من القيم في المصفوفة المحدّدة. يتطلب: قيمة value هي ArrayValue غير فارغ، ويخضع لحدود الفصل. ما مِن فلاتر ARRAY_CONTAINS_ANY أخرى ضمن عملية الفصل نفسها. ما مِن فلاتر "NOT_IN" في طلب البحث نفسه.
NOT_IN	ليست قيمة field في المصفوفة المحددة. يتطلب: هذه القيمة value هي قيمة ArrayValue غير فارغة تشتمل على 10 قيم كحدّ أقصى. ما مِن OR أو IN أو ARRAY_CONTAINS_ANY أو NOT_IN أو NOT_EQUAL أو IS_NOT_NULL أو IS_NOT_NAN الأخرى. تأتي field في المركز الأول في order_by.

FieldReference

مرجع إلى حقل في مستند، مثل: stats.operations.

الحقول
field_path	string مرجع إلى حقل في مستند. يتطلب: يجب أن يكون سلسلة من المقاطع مفصولة بالنقاط (.)، حيث يتوافق كل مقطع مع قيود document field name.

فلتر

فلتر

الحقول
حقل الاتحاد filter_type. نوع الفلتر يمكن أن يكون filter_type واحدًا فقط مما يلي:
composite_filter	CompositeFilter عامل تصفية مُركّب
field_filter	FieldFilter فلتر على حقل مستند.
unary_filter	UnaryFilter فلتر يأخذ وسيطة واحدة بالضبط.

البحث الأقرب

إعداد بحث الجيران الأقرب.

الحقول
vector_field	FieldReference مطلوب. حقل متّجه مفهرس للبحث عنه يمكن فقط عرض المستندات التي تحتوي على متجهات تتطابق أبعادها مع query_vector.
query_vector	Value مطلوب. متجه الاستعلام الذي نبحث عنه. يجب ألا يزيد طول الخط المتجه عن 2048.
distance_measure	DistanceMeasure مطلوب. قياس المسافة المطلوب استخدامه، مطلوب.
limit	Int32Value مطلوب. عدد الجيران الأقرب المُراد إرجاعه. يجب أن يكون عددًا صحيحًا موجبًا لا يزيد عن 1000.

قياس المسافة

قياس المسافة المستخدم عند المقارنة بين المتجهات.

تعدادات
DISTANCE_MEASURE_UNSPECIFIED	يجب عدم ضبطها.
EUCLIDEAN	تقيس مسافة EUCLIDEAN بين المتجهات. راجِع الإقليدية لمزيد من المعلومات
COSINE	تقارن المتجهات بناءً على الزاوية بينها، مما يسمح لك بقياس التشابه الذي لا يعتمد على حجم المتجهات. نوصي باستخدام DOT_PRODUCT مع وحدة متجهات تمت تسويتها بدلاً من مسافة COSINE، والتي تكون مكافئة رياضيًا بأداء أفضل. اطّلِع على مقالة تشابه جيب التمام لمعرفة مزيد من المعلومات.
DOT_PRODUCT	يشبه جيب التمام ولكنه يتأثر بحجم المتجهات. راجِع Dot Product لمزيد من المعلومات.

طلب

طلب في حقل

الحقول
field	FieldReference الحقل المطلوب الترتيب حسبه.
direction	Direction الاتجاه الذي يجب الطلب وفقًا له. وتكون القيمة التلقائية هي ASCENDING.

توقّعات الميزانية

إسقاط حقول المستند المطلوب عرضها.

الحقول
fields[]	FieldReference الحقول المطلوب عرضها. إذا كانت فارغة، سيتم عرض جميع الحقول. لعرض اسم المستند فقط، استخدِم ['__name__'].

فلتر UnaryFilter

فلتر بمعامل واحد.

الحقول
op	Operator عامل التشغيل الأحادي المطلوب تطبيقه.
حقل الاتحاد operand_type. وسيطة الفلتر. يمكن أن يكون operand_type واحدًا فقط مما يلي:
field	FieldReference الحقل الذي تريد تطبيق عامل التشغيل عليه.

المؤثِّر

عامل تشغيل أحادي.

تعدادات
OPERATOR_UNSPECIFIED	غير محدَّد يجب عدم استخدام هذه القيمة.
IS_NAN	تساوي قيمة field المحدّدة NaN.
IS_NULL	تساوي قيمة field المحدّدة NULL.
IS_NOT_NAN	لا تساوي قيمة field المحدّدة NaN. يتطلب: ما مِن NOT_EQUAL أو NOT_IN أو IS_NOT_NULL أو IS_NOT_NAN أخرى. تأتي field في المركز الأول في order_by.
IS_NOT_NULL	لا تساوي قيمة field المحدّدة NULL. يتطلب: عنوان NOT_EQUAL واحد أو NOT_IN أو IS_NOT_NULL أو IS_NOT_NAN تأتي field في المركز الأول في order_by.

الهدف

يشير ذلك المصطلح إلى مواصفات مجموعة من المستندات التي يجب الاستماع إليها.

الحقول
target_id	int32 رقم تعريف الهدف الذي يحدّد الهدف في البث يجب أن تكون القيمة عددًا موجبًا وغير صفري. إذا كانت قيمة target_id هي 0 (أو غير محدّدة)، سيعيّن الخادم رقم تعريف لهذا الهدف ويعرضه في حدث TargetChange::ADD. بعد إضافة استهداف مع target_id=0، يجب أن تحتوي كل الاستهدافات اللاحقة على target_id=0 أيضًا. إذا تم إرسال طلب AddTarget مع target_id != 0 إلى الخادم بعد إضافة هدف مع target_id=0، سيرسل الخادم على الفور استجابة مع حدث TargetChange::Remove. يُرجى العلم أنّه إذا أرسل العميل طلبات "AddTarget" متعدّدة بدون معرّف، لن يكون ترتيب المعرّفات المعروضة في "TargetChage.target_ids" محدّدًا. لذلك، يجب على العملاء تقديم معرّف هدف بدلاً من الاعتماد على الخادم لتحديد معرّف. إذا لم تكن قيمة target_id صفرًا، يجب ألا يكون هناك هدف نشط حالي في مصدر البيانات هذا برقم التعريف نفسه.
once	bool ما إذا كان يجب إزالة الاستهداف بعد أن يصبح ساريًا ومتسقًا
expected_count	Int32Value عدد المستندات التي تطابقت مع الاستعلام آخر مرة في الرمز المميز للسيرة الذاتية أو وقت القراءة. تكون هذه القيمة ذات صلة فقط عند توفير resume_type. هذه القيمة متوفّرة وأكبر من صفر يشير إلى أنّ العميل يريد تضمين ExistenceFilter.unchanged_names في الردّ.
حقل الاتحاد target_type. نوع الهدف المطلوب الاستماع إليه. يمكن أن يكون target_type واحدًا فقط مما يلي:
query	QueryTarget هدف محدّد بواسطة طلب بحث.
documents	DocumentsTarget هدف يتم تحديده من خلال مجموعة من أسماء المستندات.
حقل الاتحاد resume_type. وقت بدء الاستماع في حال تحديد ما سبق، لن يتم عرض سوى المستندات المطابقة التي تم تعديلها بعد resume_token أو read_time. وإلا، يتم عرض جميع المستندات المطابقة قبل إجراء أي تغييرات لاحقة. يمكن أن يكون resume_type واحدًا فقط مما يلي:
resume_token	bytes رمز مميّز لاستئناف العمل من TargetChange سابق لهدف متطابق لا يمكن استخدام رمز مميّز خاص بالسيرة الذاتية مع هدف مختلف، وقد يتعذّر استخدامها.
read_time	Timestamp يمكنك بدء الاستماع بعد read_time محدّد. يجب أن يعرف العميل حالة المستندات المطابقة في الوقت الحالي.

هدف المستندات

هدف يتم تحديده من خلال مجموعة من أسماء المستندات.

الحقول
documents[]	string أسماء المستندات المطلوب استردادها بالتنسيق: projects/{project_id}/databases/{database_id}/documents/{document_path}. سيتعذر الطلب إذا لم يكن أي من المستند موردًا فرعيًا لـ database المحدَّد. سيتم إلغاء الأسماء المكررة.

استهداف طلبات البحث

هدف محدّد بواسطة طلب بحث.

الحقول
parent	string اسم المورد الرئيسي. بالتنسيق: projects/{project_id}/databases/{database_id}/documents أو projects/{project_id}/databases/{database_id}/documents/{document_path}. على سبيل المثال: projects/my-project/databases/my-database/documents أو projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
حقل الاتحاد query_type. الاستعلام المطلوب تنفيذه. يمكن أن يكون query_type واحدًا فقط مما يلي:
structured_query	StructuredQuery طلب بحث منظم.

تغيير الاستهداف

تغيّرت الأهداف التي تتم مشاهدتها.

الحقول
target_change_type	TargetChangeType نوع التغيير الذي حدث.
target_ids[]	int32 أرقام التعريف المستهدَفة للأهداف التي تغيّرت. وإذا كانت فارغة، فسينطبق التغيير على جميع الاستهدافات. لم يتم تحديد ترتيب أرقام تعريف الاستهداف.
cause	Status تمثّل هذه السمة الخطأ الذي أدّى إلى هذا التغيير، إذا كان ذلك منطبقًا.
resume_token	bytes هو رمز مميّز يمكن استخدامه لاستئناف البث في نطاق target_ids المحدَّد أو جميع الأهداف إذا كانت السمة target_ids فارغة. لا يتم ضبطه عند كل تغيير مستهدَف.
read_time	Timestamp تمثّل هذه السمة read_time المتسق للسمة target_ids المحدّدة (يتم حذفها عندما لا تكون قِيَم target_ids في نبذة متسقة). نضمن لك أن يتم إرسال حقل "read_time" مع حقل "target_ids" فارغًا عندما يصل البث بأكمله إلى نبذة جديدة متسقة. نضمن لك أن تؤدي الرسائل ADD وCURRENT وRESET (في النهاية) إلى الحصول على لقطة جديدة متسقة (في حين أن الرسائل NO_change وREMOVE) ليست كذلك). بالنسبة إلى مصدر بيانات معيّن، نضمن أن يزداد عنصر read_time بوتيرة رتيبة.

نوع التغيير المستهدف

نوع التغيير.

تعدادات
NO_CHANGE	لم يحدث أي تغيير. لا يُستخدم سوى لإرسال resume_token معدَّل.
ADD	تمت إضافة الاستهدافات.
REMOVE	تمت إزالة الاستهدافات.
CURRENT	تعكس الأهداف جميع التغييرات التي تم إجراؤها قبل إضافة الأهداف إلى ساحة المشاركات. سيتم إرسال هذه القيمة بعد أو مع read_time أكبر من أو يساوي الوقت الذي تمت إضافة الاستهدافات فيه. ويمكن للمستمعين انتظار هذا التغيير إذا كانت الدلالة الدلالية للقراءة بعد الكتابة مطلوبة.
RESET	تمّت إعادة ضبط الاستهدافات، وسيتم عرض حالة أولية جديدة للأهداف في التغييرات اللاحقة. بعد اكتمال الحالة الأولية، سيتم عرض CURRENT حتى إذا سبق الإشارة إلى أنّ الهدف CURRENT.

خيارات المعاملات

خيارات إنشاء معاملة جديدة.

الحقول
حقل الاتحاد mode. وضع المعاملة يمكن أن يكون mode واحدًا فقط مما يلي:
read_only	ReadOnly يمكن استخدام المعاملة لإجراء عمليات القراءة فقط.
read_write	ReadWrite ويمكن استخدام المعاملة في عمليتَي القراءة والكتابة على حدّ سواء.

قراءة فقط

خيارات معاملة يمكن استخدامها لقراءة المستندات فقط.

الحقول
حقل الاتحاد consistency_selector. وضع الاتساق لهذه المعاملة وفي حال تم ترك السياسة بدون ضبط، سيتم تطبيق القيمة التلقائية على مستوى الاتساق القوي. يمكن أن يكون consistency_selector واحدًا فقط مما يلي:
read_time	Timestamp يقرأ المستندات في الوقت المحدد. ويجب أن يكون هذا الطابع الزمني للدقة بالميكرو ثانية خلال الساعة الماضية، أو إذا كانت ميزة "الاسترداد في نقطة زمنية" مفعَّلة، يمكن أن يكون أيضًا طابعًا زمنيًا لدقيقة كاملة خلال آخر 7 أيام.

ReadWrite

خيارات المعاملة التي يمكن استخدامها لقراءة المستندات وكتابتها.

لا تسمح Firestore بطلبات المصادقة من جهات خارجية بإنشاء القراءة والكتابة. المعاملات.

الحقول
retry_transaction	bytes معاملة اختيارية لإعادة المحاولة.

طلب تحديث مستند

طلب الحصول على Firestore.UpdateDocument

الحقول
document	Document مطلوب. المستند الذي تم تعديله يتم إنشاء المستند إذا لم يكن موجودًا من قبل.
update_mask	DocumentMask الحقول المطلوب تعديلها. لا يجوز أن يحتوي أي من مسارات الحقول في القناع على اسم محجوز. إذا كان المستند موجودًا على الخادم ويحتوي على حقول لم تتم الإشارة إليها في القناع، يتم تركها بدون تغيير. يتم حذف الحقول المُشار إليها في القناع، ولكن غير المتوفّرة في مستند الإدخال، من المستند على الخادم.
mask	DocumentMask الحقول المطلوب عرضها. وفي حال تم تركها بدون ضبط، سيتم عرض جميع الحقول. إذا كان المستند يحتوي على حقل غير موجود في هذا القناع، لن يتم عرض هذا الحقل في الرد.
current_document	Precondition شرط مُسبَق اختياري في المستند. سيتعذّر الطلب إذا تم ضبط ذلك ولم يتم استيفاؤه من خلال المستند المستهدف.

القيمة

رسالة يمكن أن تحتوي على أي من أنواع القيم المسموح بها

الحقول
حقل الاتحاد value_type. يجب تحديد قيمة. يمكن أن يكون value_type واحدًا فقط مما يلي:
null_value	NullValue قيمة فارغة.
boolean_value	bool قيمة منطقية.
integer_value	int64 قيمة عدد صحيح.
double_value	double قيمة مزدوجة.
timestamp_value	Timestamp قيمة طابع زمني. الضبط بدقة تصل إلى ميكرو ثانية فقط. وعند تخزينها، يتم تقريب أي دقة إضافية إلى قيمة أقل.
string_value	string قيمة سلسلة. يجب ألا تتجاوز السلسلة، الممثلة بترميز UTF-8، بين 1 مبيبايت و89 بايت. تنظر طلبات البحث فقط في أول 1,500 بايت من تمثيل UTF-8.
bytes_value	bytes قيمة بايت. يجب ألا تتجاوز 1 مبيبايت إلى 89 بايت. تأخذ طلبات البحث أول 1,500 بايت فقط في الاعتبار.
reference_value	string مرجع لمستند مثلاً: projects/{project_id}/databases/{database_id}/documents/{document_path}
geo_point_value	LatLng يشير ذلك المصطلح إلى قيمة نقطة جغرافية تمثّل نقطة على سطح الأرض.
array_value	ArrayValue قيمة مصفوفة. لا يمكن أن يحتوي على قيمة صفيف أخرى مباشرةً، ولكن يمكن أن يحتوي على خريطة تحتوي على صفيف آخر.
map_value	MapValue قيمة الخريطة.

كتابة

كتابة على مستند ما.

الحقول
update_mask	DocumentMask الحقول المطلوب تعديلها في هذه الكتابة. لا يمكن ضبط هذا الحقل إلا عندما تكون العملية update. وإذا لم يتم ضبط القناع على update وكان المستند متوفّرًا، سيتم استبدال أي بيانات حالية. وإذا تم ضبط القناع وكان المستند على الخادم يحتوي على حقول لا يغطيها القناع، يتم تركها بدون تغيير. يتم حذف الحقول المُشار إليها في القناع، ولكن غير المتوفّرة في مستند الإدخال، من المستند على الخادم. يجب ألا تحتوي مسارات الحقول في هذا القناع على اسم حقل محجوز.
update_transforms[]	FieldTransform تمثّل هذه السمة عمليات التحويل التي سيتم إجراؤها بعد التحديث. لا يمكن ضبط هذا الحقل إلا عندما تكون العملية update. في حال توفُّرها، تعادل طريقة الكتابة هذه تنفيذ update وtransform على المستند ذاته من الناحية البساطة والترتيب.
current_document	Precondition شرط مُسبَق اختياري في المستند. ستفشل الكتابة إذا تم ضبط ذلك ولم يتم تحقيقه من خلال المستند الهدف.
حقل الاتحاد operation. العملية المطلوب تنفيذها. يمكن أن يكون operation واحدًا فقط مما يلي:
update	Document مستند للكتابة
delete	string اسم المستند المطلوب حذفه بالتنسيق: projects/{project_id}/databases/{database_id}/documents/{document_path}.
transform	DocumentTransform تطبيق عملية تحويل على مستند

كتابة طلب

طلب الحصول على Firestore.Write

ينشئ الطلب الأول مجموعة بث أو يستأنف بثًا حاليًا من رمز مميّز.

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

عند استئناف البث، يبث الخادم أولاً أي ردود بعد الرمز المميّز المحدّد، ثم يبث ردّ تحتوي على رمز مميّز حديث فقط لاستخدامها في الطلب التالي.

الحقول
database	string مطلوب. اسم قاعدة البيانات. بالتنسيق: projects/{project_id}/databases/{database_id}. هذا الإجراء مطلوب فقط في الرسالة الأولى.
stream_id	string رقم تعريف ساحة المشاركات للكتابة المطلوب استئنافها يمكن ضبط هذا الإعداد في الرسالة الأولى فقط. عند ترك هذا الحقل فارغًا، سيتم إنشاء ساحة مشاركات جديدة للكتابة.
writes[]	Write العبارات التي سيتم تطبيقها. يتم تنفيذها دائمًا بشكل كامل وبالترتيب. يجب أن يكون هذا الحقل فارغًا في الطلب الأول. وقد يكون هذا الحقل فارغًا في الطلب الأخير. ويجب ألا يكون هذا الحقل فارغًا في جميع الطلبات الأخرى.
stream_token	bytes رمز مميّز للبث أرسله الخادم في السابق. يجب أن يضبط العميل هذا الحقل على الرمز المميّز من آخر WriteResponse تلقّاه. ويعني ذلك أنّ العميل قد تلقّى ردودًا حول هذا الرمز المميّز. بعد إرسال هذا الرمز المميّز، قد لا يتم استخدام الرموز المميّزة السابقة بعد الآن. وقد يغلق الخادم ساحة المشاركات في حال وجود عدد كبير جدًا من الردود التي لم يتم قبولها. يُرجى إبقاء هذا الحقل بدون ضبط عند إنشاء بث جديد. لاستئناف بث عند وقت محدّد، يجب ضبط هذا الحقل والحقل stream_id. يُرجى إبقاء هذا الحقل بدون ضبط عند إنشاء بث جديد.
labels	map<string, string> التصنيفات المرتبطة بطلب الكتابة هذا

كتابة الرد

تمثّل هذه السمة الردّ على Firestore.Write.

الحقول
stream_id	string رقم تعريف مصدر البيانات. يتم ضبط الإعداد على الرسالة الأولى فقط عند إنشاء بث جديد.
stream_token	bytes هو رمز مميّز يمثّل موضع هذه الاستجابة في ساحة المشاركات. ويمكن أن يستخدم العميل هذا الإجراء لاستئناف البث عند هذه المرحلة. يتم ضبط هذا الحقل دائمًا.
write_results[]	WriteResult هي نتيجة تطبيق عمليات الكتابة. تتوافق نتيجة i-th write هذه مع الكتابة i-th في الطلب.
commit_time	Timestamp وقت حدوث الالتزام. يمكن ضمان ظهور تأثيرات الكتابة عند قراءة أي قراءة تساوي read_time أو أكبر.

كتابة النتيجة

هي نتيجة تطبيق الكتابة.

الحقول
update_time	Timestamp تمثّل هذه السمة وقت آخر تحديث للمستند بعد تطبيق عملية الكتابة. لم يتم ضبط السياسة بعد delete. إذا لم تكن الكتابة تغير المستند فعليًا، فسيكون هذا هو update_time السابق.
transform_results[]	Value تمثّل هذه السمة نتائج تطبيق كل DocumentTransform.FieldTransform بالترتيب نفسه.