Method: projects.databases.documents.runQuery

لتنفيذ استعلام.

طلب HTTP

POST https://firestore.googleapis.com/v1beta1/{parent=projects/*/databases/*/documents}:runQuery

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

مَعلمات المسار

المَعلمات
parent

string

يجب ملء الحقل. اسم المورد الرئيسي. بالتنسيق: projects/{projectId}/databases/{databaseId}/documents أو projects/{projectId}/databases/{databaseId}/documents/{document_path}. على سبيل المثال: projects/my-project/databases/my-database/documents أو projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "explainOptions": {
    object (ExplainOptions)
  },

  // Union field query_type can be only one of the following:
  "structuredQuery": {
    object (StructuredQuery)
  }
  // End of list of possible types for union field query_type.

  // Union field consistency_selector can be only one of the following:
  "transaction": string,
  "newTransaction": {
    object (TransactionOptions)
  },
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
الحقول
explainOptions

object (ExplainOptions)

هذه السمة اختيارية. شرح خيارات الاستعلام. وفي حال ضبطها، سيتم عرض إحصاءات إضافية لطلبات البحث. وإذا لم يكن الأمر كذلك، فسيتم عرض نتائج الاستعلام فقط.
حقل الاتحاد query_type. الاستعلام المطلوب تنفيذه. يمكن أن يكون query_type واحدًا فقط مما يلي:
structuredQuery

object (StructuredQuery)

طلب بحث منظم.
حقل الاتحاد consistency_selector. وضع الاتساق لهذه المعاملة وفي حال تم ترك السياسة بدون ضبط، سيتم تطبيق القيمة التلقائية على مستوى الاتساق القوي. يمكن أن يكون consistency_selector واحدًا فقط مما يلي:
transaction

string (bytes format)

نفِّذ الاستعلام ضمن معاملة نشطة بالفعل.

القيمة هنا هي معرّف المعاملة المبهم لتنفيذ الاستعلام فيه.

سلسلة بترميز base64.
newTransaction

object (TransactionOptions)

يبدأ معاملة جديدة ويقرأ المستندات. يتم استخدام القيمة التلقائية لمعاملة القراءة فقط. سيتم عرض معرِّف المعاملة الجديد كأول ردّ في مصدر البيانات.
readTime

string (Timestamp format)

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

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

طابع زمني بتنسيق RFC3339 UTC "Zulu"، بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".

نص الاستجابة

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

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "transaction": string,
  "document": {
    object (Document)
  },
  "readTime": string,
  "skippedResults": integer,
  "explainMetrics": {
    object (ExplainMetrics)
  },

  // Union field continuation_selector can be only one of the following:
  "done": boolean
  // End of list of possible types for union field continuation_selector.
}
الحقول
transaction

string (bytes format)

المعاملة التي بدأت كجزء من هذا الطلب. لا يمكن ضبط هذا الإعداد إلا في الرد الأول، وفي حال ضبط السمة RunQueryRequest.new_transaction في الطلب فقط. في حال ضبط هذه السياسة، لن يتم ضبط أي حقول أخرى في هذه الاستجابة.

سلسلة بترميز base64.
document

object (Document)

نتيجة طلب بحث، لم يتم ضبطها عند الإبلاغ عن التقدّم الجزئي.
readTime

string (Timestamp format)

تمثّل هذه السمة وقت قراءة المستند. وقد يكون هذا في ازدياد ثابت، وفي هذه الحالة، نضمن عدم تغيير المستندات السابقة في تدفق النتائج بين readTime وهذا المستند.

إذا لم يعرض طلب البحث أي نتائج، سيتم إرسال ردّ بـ readTime بدون document، ويمثّل ذلك وقت تنفيذ طلب البحث.

طابع زمني بتنسيق RFC3339 UTC "Zulu"، بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
skippedResults

integer

عدد النتائج التي تم تخطّيها بسبب الفارق بين الردّ الأخير والاستجابة الحالية.
explainMetrics

object (ExplainMetrics)

مقاييس شرح طلب البحث ولا تتوفّر هذه السمة إلا عند توفير RunQueryRequest.explain_options، ويتم إرسالها مرة واحدة فقط مع آخر ردّ في ساحة المشاركات.
حقل الاتحاد continuation_selector. وضع المتابعة للاستعلام. في حال توفُّرها، يعني ذلك أنّ سلسلة الردود الحالية على طلب البحث قد انتهت. يمكن ضبط هذه السياسة مع توفُّر document أو بدونه، ولكن عند ضبطها، لن يتم عرض المزيد من النتائج. يمكن أن يكون continuation_selector واحدًا فقط مما يلي:
done

boolean

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

نطاقات الأذونات

يتطلب هذا الإعداد أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.