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 سريعة وإدارتها بالكامل بدون خادم ومستنِدة إلى السحابة الإلكترونية، وتسهِّل عملية تخزين البيانات ومزامنتها والاستعلام عنها لتطبيقات الأجهزة الجوّالة والويب وإنترنت الأشياء (IoT) على نطاق عالمي. وتوفّر مكتبات العملاء الخاصة بها إمكانية المزامنة المباشرة والدعم بلا اتصال بالإنترنت، في حين تعمل ميزات الأمان وعمليات الدمج مع Firebase وGoogle Cloud Platform على تسريع عملية إنشاء تطبيقات بدون خوادم.

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

BatchWrite

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

BeginTransaction
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 لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على المصادقة.

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

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

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

ListCollectionIds
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 لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على المصادقة.

PartitionQuery

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 لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على المصادقة.

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

UpdateDocument
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 لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على المصادقة.

AggregationResult

نتيجة لمجموعة واحدة من استعلام تجميع Firestore.

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

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

ArrayValue

تمثّل هذه السمة قيمة مصفوفة.

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

BatchGetDocumentsRequest

طلب 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}.

BatchWriteRequest

طلب Firestore.BatchWrite.

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

BatchWriteResponse

الردّ من Firestore.BatchWrite

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

BeginTransactionRequest

طلب Firestore.BeginTransaction.

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

BeginTransactionResponse

الردّ على Firestore.BeginTransaction.

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

BitSequence

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

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

لاسترداد البت الأول، البت 0، احسب: (bitmap[0] & 0x01) != 0. لاسترداد البت الثاني، البت 1، احسب القيمة: (bitmap[0] & 0x02) != 0. لاسترداد البت الثالث، البت 2، احسب: (bitmap[0] & 0x04) != 0. لاسترداد البت الرابع، البت 3، احسب القيمة: (bitmap[0] & 0x08) != 0. لاسترداد البت n، احسب: (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 بيانات فلتر Bloom
hash_count	int32 عدد التجزئات التي تستخدمها الخوارزمية.

CommitRequest

طلب Firestore.Commit.

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

CommitResponse

الردّ على Firestore.Commit.

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

CreateDocumentRequest

طلب 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 إذا كان الموضع قبل القيم المحدّدة أو بعدها مباشرةً، وذلك بالنسبة إلى ترتيب الترتيب المحدّد في طلب البحث.

DeleteDocumentRequest

طلب 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 لطلب بحث.

DocumentChange

تم تغيير Document.

وقد يكون ذلك نتيجة استخدام عدة عناصر writes، بما في ذلك عمليات الحذف، والتي أدّت في النهاية إلى إضافة قيمة جديدة للسمة Document.

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

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

DocumentDelete

تم حذف Document.

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

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

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

DocumentMask

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

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

DocumentRemove

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

يتم إرساله إذا لم يعد المستند ذا صلة بهدف معين وخارجه. يمكن إرسالها بدلاً من DocumentDelete أو DocumentChange (تغيير المستند) إذا لم يتمكن الخادم من إرسال القيمة الجديدة للمستند.

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

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

DocumentTransform

تحويل مستند.

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

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. إذا كان الإدخال يحتوي على قيم مكافئة متعددة، سيتم النظر في القيمة الأولى فقط. ستكون نتيجة Convert_result المقابلة هي القيمة الفارغة.
remove_all_from_array	ArrayValue يجب إزالة جميع العناصر المحددة من الصفيفة في الحقل. إذا لم يكن الحقل صفيفًا أو إذا لم يكن الحقل موجودًا بعد، يتم ضبطه على الصفيف الفارغ. تعتبر الأعداد المكافئة للأنواع المختلفة (مثل 3L و3.0) متساوية عند تحديد ما إذا كان يجب إزالة أحد العناصر أم لا. NaN تساوي NaN وNull تساوي Null. سيؤدي هذا إلى إزالة جميع القيم المكافئة في حال وجود تكرارات. ستكون نتيجة Convert_result المقابلة هي القيمة الفارغة.

ServerValue

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

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

ExecutionStats

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

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

ExistenceFilter

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

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

ExplainMetrics

شرح مقاييس طلب البحث.

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

ExplainOptions

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

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

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 أيام.

ListCollectionIdsRequest

طلب 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 أيام.

ListCollectionIdsResponse

الردّ من 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 إذا كان من المفترض أن تعرض القائمة المستندات المفقودة يكون المستند مفقودًا إذا لم يكن متوفرًا، ولكن توجد مستندات فرعية متداخلة أسفله. عند ضبط القيمة على "صحيح"، سيتم عرض هذه المستندات الناقصة باستخدام مفتاح، ولكن لن يتم ضبط حقول أو 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 رمز مميز لاسترداد الصفحة التالية من المستندات. إذا تم حذف هذا الحقل، لن تكون هناك صفحات لاحقة.

ListenRequest

طلب بقيمة Firestore.Listen

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

ListenResponse

الردّ على Firestore.Listen.

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

MapValue

قيمة خريطة

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

PartitionQueryRequest

طلب 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 أيام.

PartitionQueryResponse

الردّ على 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 في طلب PartitionQuery. إذا كان هذا الحقل فارغًا، ليس هناك المزيد من النتائج.

PlanSummary

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

الحقول
indexes_used[]	Struct الفهارس التي تم اختيارها لطلب البحث For example: [ {"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 عند ضبط هذه السياسة، يجب أن يتوفّر المستند الهدف وأن يكون قد تم إجراء آخر تعديل له في ذلك الوقت. يجب محاذاة الطابع الزمني بالميكرو ثانية.

RollbackRequest

طلب Firestore.Rollback.

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

RunAggregationQueryRequest

طلب 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 أيام.

RunQueryResponse

الردّ على 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 قد أنهى الطلب بالكامل ولن يتم إرجاع المزيد من المستندات.

StructuredAggregationQuery

استعلام 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 الحقل المطلوب التجميع عليه.

StructuredQuery

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

CollectionSelector

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

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

CompositeFilter

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

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

مُشغِّل

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

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

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

اتجاه الترتيب.

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

FieldFilter

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

الحقول
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 يشير ذلك المصطلح إلى فلتر يستخدم وسيطة واحدة فقط.

FindNearest

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

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

DistanceMeasure

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

عمليات التعداد
DISTANCE_MEASURE_UNSPECIFIED	يجب عدم ضبطها.
EUCLIDEAN	تقيس مسافة EUCLIDEAN بين المتجهات. يمكنك الاطّلاع على الإقليدية لمعرفة المزيد.
COSINE	تقارن المتجهات بناءً على الزاوية بينها، مما يسمح لك بقياس التشابه الذي لا يعتمد على مقدار المتجهات. نوصي باستخدام DOT_PRODUCT مع وحدة المتجهات التي تمت تسويتها بدلا من مسافة COSINE، وهي مكافئة رياضيًا مع أداء أفضل. راجِع تشابه جيب التمام لمعرفة المزيد من المعلومات.
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 محدّد. يجب أن يعرف العميل حالة المستندات المطابقة في الوقت الحالي.

DocumentsTarget

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

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

QueryTarget

هدف محدد بطلب بحث.

الحقول
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 طلب بحث مركبة.

TargetChange

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

الحقول
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 فارغًا عندما يصل البث بأكمله إلى لقطة متسقة جديدة. ومن المضمون أن تؤدي رسائل "إضافة" و"حديث" و"إعادة تعيين" (في النهاية) إلى الحصول على نبذة متسقة جديدة (بينما لا يؤدي ذلك إلى NO_CHANGE و"إزالة الرسائل"). بالنسبة إلى بث معيّن، نضمن لك زيادة قيمة "read_time" بشكل رتيب.

TargetChangeType

نوع التغيير.

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

TransactionOptions

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

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

ReadOnly

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

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

ReadWrite

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

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

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

UpdateDocumentRequest

طلب 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 بايت. لا تضع طلبات البحث سوى أول 1500 بايت.
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 يتم تطبيق عملية تحويل على مستند.

WriteRequest

طلب 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> التصنيفات المرتبطة بطلب الكتابة هذا

WriteResponse

الردّ على Firestore.Write.

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

WriteResult

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

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