Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

ค้นหาและดึงข้อมูลเอกสาร

คู่มือนี้จะแสดงวิธีใช้ Developer Knowledge API เพื่อค้นหาและดึงเอกสารประกอบสำหรับนักพัฒนาแอปแบบสาธารณะของ Google โดยใช้โปรแกรม API นี้จะช่วยให้แอปพลิเคชันของคุณค้นหาสนิปเพ็ตข้อความที่เกี่ยวข้องหรือดึงเอกสาร Markdown ฉบับเต็มได้ แทนที่จะต้องขูดข้อมูลจากหน้าเว็บด้วยตนเอง

ในเอกสารนี้ คุณจะพบตัวอย่างสำหรับงานต่อไปนี้

การค้นหาคลังเอกสาร
การแบ่งหน้าผ่านผลการค้นหา
การใช้ตัวกรองที่ซับซ้อนกับการค้นหา
การดึงเนื้อหาเอกสารฉบับเต็ม
การเพิ่มประสิทธิภาพเพย์โหลดการตอบกลับเพื่อลดเวลาในการตอบสนอง

โปรดตรวจสอบว่าคุณได้เปิดใช้ API และสร้าง คีย์ Developer Knowledge APIแล้วก่อนที่จะเริ่ม จากนั้นบันทึกคีย์ลงในตัวแปรสภาพแวดล้อม

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

ค้นหาเอกสารด้วย `SearchDocumentChunks`

ใช้ documents.searchDocumentChunks เมธอดเพื่อค้นหา Chunk ของเอกสารที่ตรงกับสตริงคำค้นหา ผลการค้นหาจะมี Chunk ของเนื้อหาจากเอกสารที่ตรงกัน พร้อมด้วยข้อมูลอ้างอิง parent ที่คุณใช้ดึงเนื้อหาฉบับเต็มของเอกสารเหล่านั้นได้

ตัวอย่างต่อไปนี้จะค้นหาเอกสารที่ตรงกับ "BigQuery"

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&key=$DEVELOPERKNOWLEDGE_API_KEY"

เอาต์พุตจะมีลักษณะคล้ายกับตัวอย่างต่อไปนี้

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "BigQuery overview",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z"
      },
      "relevanceScore": 0.92
    }
  ]
}

ผลการค้นหาแต่ละรายการในรายการ results จะมีข้อมูลต่อไปนี้

parent: ชื่อทรัพยากรของเอกสาร (เช่น documents/docs.cloud.google.com/bigquery/docs/introduction)
id: ตัวระบุ Chunk ภายในเอกสาร (เช่น chunk_0)
content: สนิปเพ็ตข้อความที่ตรงกันจากเอกสาร
document: ข้อมูลเมตาเกี่ยวกับเอกสารต้นฉบับ เช่น title, uri, dataSource และ updateTime
relevanceScore: คะแนนความเกี่ยวข้องของ Chunk กับคำค้นหาในช่วง [0.0, 1.0]

ดูข้อมูลเพิ่มเติมเกี่ยวกับสคีมาการตอบกลับและช่องข้อมูลเมตา ทั้งหมดที่มีได้ที่ เอกสารอ้างอิง documents.searchDocumentChunks API

แบ่งหน้าผลการค้นหา

เมื่อคำค้นหาแสดงผลการค้นหาหลายรายการ คุณสามารถเลื่อนดูชุดผลการค้นหาได้โดยใช้พารามิเตอร์การแบ่งหน้าต่อไปนี้

pageSize (จำนวนเต็ม): ระบุจำนวนผลการค้นหาสูงสุดที่จะแสดงต่อหน้า หากไม่ได้ระบุ API จะแสดงผลการค้นหา 5 รายการโดยค่าเริ่มต้น ค่าสูงสุดที่อนุญาตคือ 100 และระบบจะบังคับให้ค่าที่มากกว่า 100 เป็น 100
pageToken (สตริง): ระบุโทเค็นที่ได้รับในการตอบกลับก่อนหน้าเพื่อดึงผลการค้นหาหน้าถัดไป

ขอหน้าแรก

หากต้องการตั้งค่าขนาดหน้า ให้ส่งพารามิเตอร์ pageSize ในคำขอ

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&key=$DEVELOPERKNOWLEDGE_API_KEY"

หากมีผลการค้นหาเพิ่มเติม การตอบกลับจะมี nextPageToken

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "What is BigQuery?",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z",
        "view": "DOCUMENT_VIEW_BASIC"
      },
      "relevanceScore": 0.88
    }
  ],
  "nextPageToken": "CAUQABgB"
}

ดึงหน้าถัดไป

ส่งค่า nextPageToken ไปยังพารามิเตอร์ pageToken ในคำขอถัดไป

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"

เมื่อไปถึงหน้าผลการค้นหาสุดท้าย ระบบจะไม่แสดง nextPageToken ในการตอบกลับ

กรองผลการค้นหา

ใช้พารามิเตอร์ filter เพื่อใช้ตัวกรองที่เข้มงวดกับผลการค้นหา ระบบจะใช้นิพจน์ตัวกรองกับข้อมูลเมตาของเอกสารหลักสำหรับ Chunk แต่ละรายการ

นิพจน์ filter มีจำนวนอักขระสูงสุด 500 ตัว

ช่องที่รองรับ

คุณสามารถกรองผลการค้นหาโดยใช้ช่องเอกสารหลักต่อไปนี้

content_length_bytes (จำนวนเต็ม): ความยาวของช่อง content ของเอกสารเป็นไบต์
data_source (สตริง): โดเมนแหล่งที่มาของเอกสาร เช่น docs.cloud.google.com หรือ firebase.google.com ดูแหล่งข้อมูลทั้งหมดที่รองรับได้ที่ ข้อมูลอ้างอิงคลังเอกสาร
update_time (การประทับเวลา): การประทับเวลาเมื่อเอกสารได้รับการอัปเดตล่าสุด ค่าต้องใช้รูปแบบ RFC 3339 (เช่น, "2025-01-01T00:00:00Z")
uri (สตริง): URI แบบเต็มของเอกสาร (เช่น https://docs.cloud.google.com/bigquery/docs/tables)

โอเปอเรเตอร์ที่รองรับ

ตัวแยกวิเคราะห์นิพจน์ตัวกรองรองรับโอเปอเรเตอร์ต่างๆ ขึ้นอยู่กับประเภทข้อมูลของช่อง

ช่องสตริง (data_source, uri): รองรับ = (เท่ากับ) และ != (ไม่เท่ากับ) สำหรับการจับคู่สตริงที่แน่นอน ไม่รองรับการจับคู่บางส่วน การจับคู่คำนำหน้า และการจับคู่การแสดงผลปกติ
ช่องการประทับเวลา (update_time): รองรับ =, <, <=, >, และ >=
ช่องจำนวนเต็ม (content_length_bytes): รองรับ =, !=, <, <=, >, และ >=
โอเปอเรเตอร์เชิงตรรกะ: รวมเงื่อนไขโดยใช้ AND OR และ NOT (หรือ -)

ตัวอย่างการกรอง

ตัวอย่างต่อไปนี้แสดงวิธีสร้างการแสดงผลตัวกรอง เมื่อเรียก REST API ด้วย curl ให้ตรวจสอบว่าได้เข้ารหัส URL พารามิเตอร์ตัวกรองหรือใช้ --data-urlencode แล้ว

จับคู่แหล่งข้อมูลหลายแหล่ง

ใช้ OR เพื่อรวมเอกสารจากหลายแหล่ง

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

คำขอ curl

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=database" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

กรองตามการประทับเวลา

ใช้โอเปอเรเตอร์การเปรียบเทียบกับการประทับเวลา RFC 3339 เพื่อค้นหาเนื้อหาที่อัปเดตหลังจากวันที่ที่ระบุ

update_time >= "2025-01-01T00:00:00Z"

คำขอ curl

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=BigQuery" \
  --data-urlencode 'filter=update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

กรองตามความยาวเนื้อหา

ใช้โอเปอเรเตอร์การเปรียบเทียบกับ content_length_bytes เพื่อค้นหาเอกสารตามขนาดเป็นไบต์

content_length_bytes < 5000

คำขอ curl

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Storage" \
  --data-urlencode 'filter=content_length_bytes < 5000' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

รวมแหล่งข้อมูล การประทับเวลา และการจัดกลุ่ม

รวม AND, OR และวงเล็บ (...) เพื่อจำกัดผลการค้นหาให้แสดงเฉพาะแหล่งที่มาที่เฉพาะเจาะจงซึ่งอัปเดตหลังจากวันที่ที่กำหนด

(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"

คำขอ curl

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=service worker" \
  --data-urlencode 'filter=(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

ยกเว้นแหล่งข้อมูล

ใช้ NOT หรือ != เพื่อยกเว้นผลการค้นหาจากแหล่งที่มาที่เฉพาะเจาะจง

data_source != "firebase.google.com"

คำขอ curl

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=authentication" \
  --data-urlencode 'filter=data_source != "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

ดึงเอกสารด้วย `GetDocument`

ใช้ documents.get เมธอด เพื่อดึงเนื้อหาฉบับเต็มของเอกสารเดียว

ชื่อทรัพยากรเทียบกับ URI

เมื่ออ้างอิงเอกสารใน Developer Knowledge API โปรดทราบความแตกต่างระหว่างชื่อทรัพยากรกับ URI ของเว็บ

ชื่อทรัพยากร (parent, name): จัดรูปแบบเป็น documents/{uri_without_scheme} (เช่น documents/docs.cloud.google.com/storage/docs/creating-buckets) ส่ง ค่านี้เป็นพารามิเตอร์เส้นทางใน GetDocument หรือในพารามิเตอร์ names ของ BatchGetDocuments
URI ของเว็บ (uri): URL แบบเต็มของเว็บรวมถึงสคีมา (เช่น https://docs.cloud.google.com/storage/docs/creating-buckets) ใช้ รูปแบบนี้สำหรับช่อง uri เมื่อสร้างการแสดงผล filter (เช่น uri = "https://docs.cloud.google.com/storage/docs/creating-buckets")

ตัวอย่างต่อไปนี้จะดึงเอกสารตามชื่อทรัพยากร

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

การตอบกลับจะเป็น Document ทรัพยากรที่มีข้อมูลเมตาและเนื้อหา Markdown ฉบับเต็มในช่อง content

ดึงเอกสารหลายรายการด้วย `BatchGetDocuments`

ใช้ documents.batchGet เมธอด เพื่อดึงเอกสารได้สูงสุด 20 รายการตามชื่อในการเรียก API ครั้งเดียว ซึ่งมีประสิทธิภาพมากกว่าการส่งคำขอ GetDocument หลายรายการ

ตัวอย่างต่อไปนี้จะดึงเอกสาร 2 รายการตามชื่อ

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&key=$DEVELOPERKNOWLEDGE_API_KEY"

การตอบกลับจะมีรายการทรัพยากรที่ขอ Document ตามลำดับที่คุณขอ

เพิ่มประสิทธิภาพเพย์โหลดการตอบกลับ

เนื้อหาเอกสารในรูปแบบ Markdown อาจมีขนาดใหญ่ หากแอปพลิเคชันของคุณต้องการเพียงข้อมูลเมตา (เช่น ชื่อหน้า URI หรือการประทับเวลา) หรือช่องที่เฉพาะเจาะจง คุณสามารถเพิ่มประสิทธิภาพขนาดเพย์โหลดเพื่อลดแบนด์วิดท์และเวลาในการตอบสนองได้

ใช้มุมมองเอกสาร

พารามิเตอร์ view จะควบคุมช่องที่จะแสดงใน Document ข้อความ

Enum DocumentView รองรับค่าต่อไปนี้

DOCUMENT_VIEW_BASIC: แสดงเฉพาะช่องข้อมูลเมตาพื้นฐาน (name, uri, data_source, title, description, update_time และ view) ระบบจะไม่แสดงช่อง content
DOCUMENT_VIEW_CONTENT: แสดงช่องข้อมูลเมตาพร้อมกับช่อง content Markdown ซึ่งเป็นค่าเริ่มต้นสำหรับ GetDocument และ BatchGetDocuments
DOCUMENT_VIEW_FULL: แสดงช่องเอกสารทั้งหมด

หากต้องการดึงเฉพาะข้อมูลเมตาของเอกสารโดยไม่ต้องดาวน์โหลดเนื้อหา Markdown ขนาดใหญ่ ให้ตั้งค่า view=DOCUMENT_VIEW_BASIC

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

นอกจากนี้ คุณยังใช้ view=DOCUMENT_VIEW_BASIC กับ BatchGetDocuments ได้ด้วย

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

ใช้มาสก์ของช่อง

หากต้องการจำกัดเพย์โหลดการตอบกลับให้แสดงเฉพาะช่องที่เฉพาะเจาะจง ให้ใช้พารามิเตอร์การค้นหา fields ของ Google APIs (มาสก์ของช่อง) มาตรฐาน

กรองช่องใน `GetDocument`

หากต้องการดึงเฉพาะช่อง title, uri และ updateTime ของเอกสาร ให้ทำดังนี้

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?fields=title,uri,updateTime&key=$DEVELOPERKNOWLEDGE_API_KEY"

กรองช่องใน `BatchGetDocuments`

หากต้องการดึงเฉพาะช่องที่เฉพาะเจาะจงสำหรับเอกสารแต่ละรายการในชุด ให้ทำดังนี้

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&fields=documents(name,title,uri)&key=$DEVELOPERKNOWLEDGE_API_KEY"

กรองช่องใน `SearchDocumentChunks`

หากต้องการแสดงเฉพาะ id และ content ของ Chunk, title และ uri ของเอกสารหลัก รวมถึง nextPageToken จากการค้นหา ให้ทำดังนี้

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&fields=results(id,content,document(title,uri)),nextPageToken&key=$DEVELOPERKNOWLEDGE_API_KEY"

จัดการข้อผิดพลาด

Developer Knowledge API จะแสดงรหัสสถานะ HTTP มาตรฐาน ตัวอย่างการทำงานต่อไปนี้จะแสดงการจับคู่รหัสสถานะ HTTP และสาเหตุใน Developer Knowledge API

400 INVALID_ARGUMENT:
- สตริงนิพจน์ filter มีอักขระเกิน 500 ตัว
- การประทับเวลา update_time ไม่ถูกต้อง (ต้องใช้รูปแบบ RFC 3339)
- มีการระบุชื่อเอกสารมากกว่า 20 รายการในคำขอ BatchGetDocuments
401 UNAUTHENTICATED: คำขอไม่มีคีย์ API หรือใช้คีย์ที่ไม่ถูกต้อง ดูการตรวจสอบสิทธิ์
404 NOT_FOUND: ชื่อเอกสารที่ขอไม่มีอยู่หรือเป็นของโดเมนที่ไม่ได้รวมอยู่ในคลังเอกสาร
429 RESOURCE_EXHAUSTED: โปรเจ็กต์ใช้โควต้าเกิน ดูโควต้าและขีดจำกัด

ขั้นตอนถัดไป

ดู หัวข้อตอบคำค้นหาด้วยการสร้างคำตอบโดยอิงตามข้อมูล
สำรวจวิธี ใช้ไลบรารีของไคลเอ็นต์ใน Python, Node.js, Go หรือ Java
เรียกดูข้อมูลอ้างอิงคลังเอกสารเพื่อดู แหล่งเอกสารทั้งหมดที่รองรับ
อ่านข้อมูลอ้างอิง REST API เพื่อดูข้อกำหนดเมธอดทั้งหมด
ตรวจสอบโควต้าและขีดจำกัดสำหรับโควต้าและขีดจำกัดอัตรา API

ค้นหาเอกสารด้วย SearchDocumentChunks

แบ่งหน้าผลการค้นหา

ขอหน้าแรก

ดึงหน้าถัดไป

กรองผลการค้นหา

ช่องที่รองรับ

โอเปอเรเตอร์ที่รองรับ

ตัวอย่างการกรอง

จับคู่แหล่งข้อมูลหลายแหล่ง

กรองตามการประทับเวลา

กรองตามความยาวเนื้อหา

รวมแหล่งข้อมูล การประทับเวลา และการจัดกลุ่ม

ยกเว้นแหล่งข้อมูล

ดึงเอกสารด้วย GetDocument

ชื่อทรัพยากรเทียบกับ URI

ดึงเอกสารหลายรายการด้วย BatchGetDocuments

เพิ่มประสิทธิภาพเพย์โหลดการตอบกลับ

ใช้มุมมองเอกสาร

ใช้มาสก์ของช่อง

กรองช่องใน GetDocument

กรองช่องใน BatchGetDocuments

กรองช่องใน SearchDocumentChunks

จัดการข้อผิดพลาด

ขั้นตอนถัดไป

ค้นหาเอกสารด้วย `SearchDocumentChunks`

ดึงเอกสารด้วย `GetDocument`

ดึงเอกสารหลายรายการด้วย `BatchGetDocuments`

กรองช่องใน `GetDocument`

กรองช่องใน `BatchGetDocuments`

กรองช่องใน `SearchDocumentChunks`