Method: projects.databases.documents.partitionQuery

لتقسيم استعلام عن طريق عرض مؤشرات الأقسام التي يمكن استخدامها لتشغيل الاستعلام بشكل متوازٍ. مؤشرات التقسيم المعروضة هي نقاط تقسيم يمكن استخدامها بواسطة Docs.runQuery كنقاط بداية/نهاية لنتائج الاستعلام.

طلب HTTP

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

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

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

المَعلمات
parent

string

مطلوب. اسم المورد الرئيسي. بالتنسيق: projects/{projectId}/databases/{databaseId}/documents. أسماء موارد المستندات غير متوافقة؛ يمكن تحديد أسماء موارد قاعدة البيانات فقط.

نص الطلب

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

تمثيل JSON 
{
  "partitionCount": string,
  "pageToken": string,
  "pageSize": integer,

  // 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:
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
الحقول
partitionCount

string (int64 format)

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

على سبيل المثال، قد يتم ضبط ذلك على عدد أقل بمقدار واحد من عدد طلبات البحث المتوازية المراد تشغيلها، أو عند تشغيل مهمة مسار بيانات، أقل من عدد العاملين أو مثيلات الحوسبة المتاحة.
pageToken

string

القيمة nextPageToken التي تم عرضها من استدعاء سابق إلى Docs.partitionQuery التي يمكن استخدامها للحصول على مجموعة إضافية من النتائج. وليس هناك ضمانات ترتيب بين مجموعات النتائج. وبالتالي، سيتطلب استخدام مجموعات متعددة من النتائج دمج مجموعات النتائج المختلفة.

على سبيل المثال، قد يتم عرض طلبَين تاليَين يستخدمان pageToken:

  • المؤشر B، المؤشر M، المؤشر Q
  • المؤشر A، المؤشر U، المؤشر W

للحصول على مجموعة نتائج كاملة مرتبة حسب نتائج طلب البحث المقدم إلى document.partitionQuery، يجب دمج مجموعات النتائج: المؤشر A، المؤشر B، المؤشر M، المؤشر Q، المؤشر U، المؤشر W
pageSize

integer

الحد الأقصى لعدد الأقسام المطلوب عرضها في هذه المكالمة، ويخضع لـ partitionCount.

على سبيل المثال، إذا كان partitionCount = 10 وpageSize = 8، فسيعرض الاستدعاء الأول لـdocument.partitionQuery ما يصل إلى 8 أقسام والرمز nextPageToken في حالة وجود المزيد من النتائج. سيؤدي استدعاء الإجراء الثاني إلى Docs.partitionQuery إلى قسمَين إلى قسمَين، لإكمال إجمالي 10 أقسام محدَّدة في partitionCount.
حقل الاتحاد query_type. الاستعلام المطلوب تقسيمه. يمكن أن يكون query_type واحدًا فقط مما يلي:
structuredQuery

object (StructuredQuery)

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

string (Timestamp format)

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

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

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

نص الاستجابة

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

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

تمثيل JSON 
{
  "partitions": [
    {
      object (Cursor)
    }
  ],
  "nextPageToken": string
}
الحقول
partitions[]

object (Cursor)

نتائج التقسيم يُعد كل قسم نقطة تقسيم يمكن استخدامها بواسطة المستندات.runQuery كنقطة بداية أو نهاية لنتائج الاستعلام. يجب إجراء طلبات المستندات.runQuery باستخدام طلب البحث نفسه المتوفّر في طلب document.partitionQuery هذا. سيتم ترتيب مؤشرات الأقسام وفقًا للترتيب نفسه الخاص بنتائج طلب البحث المقدَّم في document.partitionQuery.

على سبيل المثال، إذا عرض طلب المستندات.partitionQuery مؤشري القسمين A وB، فسيؤدي تشغيل الاستعلامات الثلاثة التالية إلى عرض مجموعة النتائج الكاملة للاستعلام الأصلي:

  • استعلام، endAt A
  • استعلام، startAt A، endAt B
  • استعلام، startAt B

قد تشير النتيجة الفارغة إلى أنّ عدد النتائج قليل جدًا ولا يمكن تقسيمها في طلب البحث، أو أنّ عملية التقسيم غير متاحة بعد.
nextPageToken

string

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

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

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

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

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