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

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