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)

เรียกใช้การค้นหาภายในธุรกรรมที่ใช้งานอยู่แล้ว

ค่าในส่วนนี้คือรหัสธุรกรรมที่ไม่ชัดเจนสำหรับดำเนินการค้นหา

สตริงที่เข้ารหัสฐาน 64
newTransaction

object (TransactionOptions)

เริ่มธุรกรรมใหม่และอ่านเอกสาร ค่าเริ่มต้นคือธุรกรรมแบบอ่านอย่างเดียว ระบบจะแสดงรหัสธุรกรรมใหม่เป็นคำตอบแรกในสตรีม
readTime

string (Timestamp format)

อ่านเอกสารแบบเดียวกับ ณ เวลาที่ระบุ

โดยต้องเป็นการประทับเวลาที่แม่นยำในระดับไมโครวินาทีภายใน 1 ชั่วโมงที่ผ่านมา หรือหากเปิดใช้การกู้คืนช่วงเวลาอยู่ ก็อาจเป็นการประทับเวลาแบบเต็มนาทีภายในช่วง 7 วันที่ผ่านมาด้วย

การประทับเวลาจะอยู่ในรูปแบบ RFC3339 UTC "Zulu" ที่มีความละเอียดระดับนาโนวินาทีและมีตัวเลขที่เป็นเศษส่วนได้สูงสุด 9 หลัก ตัวอย่าง: "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 ในคำขอ หากตั้งค่าแล้ว ระบบจะไม่ตั้งค่าช่องอื่นๆ ในการตอบกลับนี้

สตริงที่เข้ารหัสฐาน 64
document

object (Document)

ผลการค้นหาที่ไม่มีการตั้งค่าเมื่อรายงานความคืบหน้าเพียงบางส่วน
readTime

string (Timestamp format)

เวลาที่อ่านเอกสาร จำนวนนี้อาจเพิ่มขึ้นทีละน้อย ในกรณีนี้ เรารับประกันว่าเอกสารก่อนหน้าในสตรีมผลลัพธ์จะไม่มีการเปลี่ยนแปลงระหว่าง readTime กับเอกสารนี้

หากการค้นหาไม่แสดงผลลัพธ์ ระบบจะตอบกลับด้วย readTime และไม่มี document ซึ่งจะแสดงเวลาที่เรียกใช้การค้นหา

การประทับเวลาจะอยู่ในรูปแบบ RFC3339 UTC "Zulu" ที่มีความละเอียดระดับนาโนวินาทีและมีตัวเลขที่เป็นเศษส่วนได้สูงสุด 9 หลัก ตัวอย่าง: "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

ดูข้อมูลเพิ่มเติมได้ที่ภาพรวมการตรวจสอบสิทธิ์