Package google.firestore.v1

الفهرس

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 بالترتيب نفسه.