เอกสารนี้จะแสดงวิธีใช้ Developer Knowledge API เพื่อค้นหาและดึงเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์แบบสาธารณะของ Google โดยใช้โปรแกรม API นี้จะช่วยให้แอปพลิเคชันของคุณค้นหาสนิปเป็ตข้อความที่เกี่ยวข้องหรือดึงเอกสาร Markdown แบบเต็มได้ แทนที่จะต้องขูดข้อมูลจากหน้าเว็บด้วยตนเอง
ในเอกสารนี้ คุณจะพบตัวอย่างสำหรับงานต่อไปนี้
- การค้นหาคลังเอกสาร
- การแบ่งหน้าผ่านผลการค้นหา
- การใช้ตัวกรองที่ซับซ้อนกับการค้นหา
- การดึงเนื้อหาเอกสารแบบเต็ม
- การเพิ่มประสิทธิภาพเพย์โหลดการตอบกลับเพื่อลดเวลาในการตอบสนอง
ก่อนเริ่มต้น ให้ตั้งค่าสภาพแวดล้อมสำหรับเครื่องมือที่คุณต้องการ
gcloud
ติดตั้งและกำหนดค่า gcloud CLI แล้วเปิดใช้ Developer Knowledge API
REST
เปิดใช้ API และสร้างคีย์ Developer Knowledge API จากนั้นบันทึกคีย์ลงในตัวแปรสภาพแวดล้อม
export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"
แทนที่ YOUR_API_KEY ด้วยคีย์ Developer Knowledge API
ค้นหาเอกสาร
ใช้ gcloud developer-knowledge documents search-chunks
คำสั่ง หรือ
documents.searchDocumentChunks
เมธอด REST เพื่อค้นหา Chunk ของเอกสารที่ตรงกับสตริงคำค้นหา ผลการค้นหาจะมี Chunk ของเนื้อหาจากเอกสารที่ตรงกัน พร้อมกับการอ้างอิง parent ที่คุณใช้ดึงเนื้อหาแบบเต็มของเอกสารเหล่านั้นได้
ตัวอย่างต่อไปนี้จะค้นหาเอกสารที่ตรงกับ "BigQuery"
gcloud
gcloud developer-knowledge documents search-chunks \ --query="BigQuery"
REST
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และupdateTimerelevanceScore: คะแนนความเกี่ยวข้องของ Chunk กับคำค้นหาในช่วง[0.0, 1.0]
ดูข้อมูลเพิ่มเติมเกี่ยวกับสคีมาการตอบกลับและช่องข้อมูลเมตาทั้งหมดที่ใช้ได้ที่ข้อมูลอ้างอิงของ documents.searchDocumentChunks API
แบ่งหน้าผลการค้นหา
เมื่อคำค้นหาแสดงผลลัพธ์ที่ตรงกันหลายรายการ คุณจะไปยังชุดผลลัพธ์ต่างๆ ได้โดยใช้พารามิเตอร์การแบ่งหน้าต่อไปนี้
--page-size(gcloud CLI) หรือpageSize(จำนวนเต็ม): ระบุจำนวนผลลัพธ์สูงสุดที่จะแสดงต่อหน้า หากไม่ได้ระบุไว้ API จะแสดงผลลัพธ์ 5 รายการโดยค่าเริ่มต้น ค่าสูงสุดที่อนุญาตคือ 100 ระบบจะบังคับให้ค่าที่มากกว่า 100 เป็น 100--limit(gcloud CLI) หรือpageToken(สตริง): ใน gcloud CLI ให้ใช้--limitเพื่อควบคุมจำนวนผลลัพธ์ทั้งหมดที่แสดงในหน้าต่างๆ ในคำขอ REST ให้ส่งค่าpageTokenที่ได้รับในการตอบกลับก่อนหน้าเพื่อดึงผลลัพธ์หน้าถัดไป
gcloud
ส่งแฟล็ก --page-size และ --limit เพื่อควบคุมจำนวนผลลัพธ์ต่อหน้าและจำนวนผลลัพธ์ทั้งหมดที่แสดง
gcloud developer-knowledge documents search-chunks \ --query="BigQuery" \ --page-size=5 \ --limit=10
REST
หากต้องการขอหน้าแรก ให้ส่งพารามิเตอร์
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ในการตอบกลับ
กรองผลการค้นหา
ใช้แฟล็ก --query-filter ใน gcloud CLI หรือพารามิเตอร์ filter
ในคำขอ REST เพื่อใช้ตัวกรองที่เข้มงวดกับผลการค้นหา ระบบจะใช้นิพจน์ตัวกรองกับข้อมูลเมตาของเอกสารระดับบนสำหรับ Chunk แต่ละรายการ
นิพจน์ตัวกรองมีจำนวนอักขระสูงสุด 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): รองรับ=,!=,<,<=,>, และ>= - โอเปอเรเตอร์เชิงตรรกะ: รวมเงื่อนไขโดยใช้
ANDORและNOT(หรือ-)
ตัวอย่างการกรอง
ตัวอย่างต่อไปนี้แสดงวิธีสร้างนิพจน์ตัวกรอง เมื่อใช้ gcloud CLI ให้ส่งการแสดงผลไปยังแฟล็ก --query-filter เมื่อเรียก REST API ด้วย curl ให้ตรวจสอบว่าได้เข้ารหัส URL พารามิเตอร์ filter หรือใช้ --data-urlencode
จับคู่แหล่งข้อมูลเดียว
จำกัดผลการค้นหาเฉพาะโดเมนเอกสารประกอบเดียว
data_source = "docs.cloud.google.com"
gcloud
gcloud developer-knowledge documents search-chunks \ --query="Cloud Functions deployment" \ --query-filter='data_source = "docs.cloud.google.com"'
REST
curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \ --data-urlencode "query=Cloud Functions deployment" \ --data-urlencode 'filter=data_source = "docs.cloud.google.com"' \ --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"
จับคู่แหล่งข้อมูลหลายแหล่ง
ใช้ OR เพื่อรวมเอกสารจากหลายแหล่ง
data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"
gcloud
gcloud developer-knowledge documents search-chunks \ --query="database" \ --query-filter='data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"'
REST
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"
gcloud
gcloud developer-knowledge documents search-chunks \ --query="BigQuery" \ --query-filter='update_time >= "2025-01-01T00:00:00Z"'
REST
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
gcloud
gcloud developer-knowledge documents search-chunks \ --query="Cloud Storage" \ --query-filter='content_length_bytes < 5000'
REST
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"
gcloud
gcloud developer-knowledge documents search-chunks \ --query="service worker" \ --query-filter='(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"'
REST
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"
gcloud
gcloud developer-knowledge documents search-chunks \ --query="authentication" \ --query-filter='data_source != "firebase.google.com"'
REST
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"
ดึงเอกสาร
ใช้
gcloud developer-knowledge documents describeคำสั่งหรือ
เมธอด documents.get ของ REST เพื่อ
ดึงเนื้อหาแบบเต็มของเอกสารเดียว
ตัวอย่างต่อไปนี้จะดึงเอกสารตามชื่อทรัพยากร
gcloud
gcloud developer-knowledge documents describe \ documents/docs.cloud.google.com/storage/docs/creating-buckets
REST
curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"
การตอบกลับจะเป็น Document
ทรัพยากรที่มีข้อมูลเมตาและเนื้อหา Markdown แบบเต็มในช่อง content
ชื่อทรัพยากรเทียบกับ URI
เมื่ออ้างอิงเอกสารใน Developer Knowledge API โปรดทราบความแตกต่างระหว่างชื่อทรัพยากรกับ URI ของเว็บ
- ชื่อทรัพยากร (
parent,name): จัดรูปแบบเป็นdocuments/{uri_without_scheme}(เช่นdocuments/docs.cloud.google.com/storage/docs/creating-buckets) ส่ง ค่านี้เป็นอาร์กิวเมนต์ตำแหน่งในgcloud developer-knowledge documents describe, พารามิเตอร์เส้นทางในGetDocumentหรือในพารามิเตอร์namesของBatchGetDocuments - URI ของเว็บ (
uri): URL แบบเต็มของเว็บรวมถึงสคีมา (เช่นhttps://docs.cloud.google.com/storage/docs/creating-buckets) ใช้ รูปแบบนี้สำหรับช่องuriเมื่อสร้าง--query-filterหรือfilterการแสดงผล (เช่นuri = "https://docs.cloud.google.com/storage/docs/creating-buckets")
ดึงเอกสารหลายรายการด้วย 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 ใน gcloud CLI หรือพารามิเตอร์ view ในคำขอ REST
จะควบคุมช่องที่จะแสดงใน
Document ข้อความ
แฟล็ก --view และ DocumentView
Enum รองรับค่าต่อไปนี้
--view=basic(gcloud CLI) หรือDOCUMENT_VIEW_BASIC: แสดง เฉพาะช่องข้อมูลเมตาพื้นฐาน (name,uri,dataSource,title,description,updateTimeและview) ระบบจะไม่แสดงช่องcontent--view=content(gcloud CLI) หรือDOCUMENT_VIEW_CONTENT: แสดงช่องข้อมูลเมตาพร้อมกับช่องcontentMarkdown ซึ่งเป็นค่าเริ่มต้นสำหรับgcloud developer-knowledge documents describe,GetDocument,และBatchGetDocuments--view=full(gcloud CLI) หรือDOCUMENT_VIEW_FULL: แสดงช่องเอกสารทั้งหมด
หากต้องการดึงเฉพาะข้อมูลเมตาของเอกสารโดยไม่ต้องดาวน์โหลดเนื้อหา Markdown ขนาดใหญ่ ให้ระบุมุมมองเอกสารพื้นฐาน
gcloud
gcloud developer-knowledge documents describe \ documents/docs.cloud.google.com/storage/docs/creating-buckets \ --view=basic
REST
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 หรือโทเค็น Bearer หรือใช้ข้อมูลเข้าสู่ระบบที่ไม่ถูกต้อง โปรดดู การตรวจสอบสิทธิ์404 NOT_FOUND: ชื่อเอกสารที่ขอไม่มีอยู่หรือเป็นของโดเมนที่ไม่ได้รวมอยู่ในคลังเอกสาร429 RESOURCE_EXHAUSTED: โปรเจ็กต์ใช้โควต้าเกิน ดูโควต้าและขีดจำกัด
ขั้นตอนถัดไป
- โปรดดูหัวข้อ สร้างคำตอบจากเอกสารประกอบ
- เชื่อมต่อกับเซิร์ฟเวอร์ MCP ของ Developer Knowledge และติดตั้ง
retrieving-developer-knowledgeทักษะเอเจนต์ เพื่อช่วยผู้ช่วยการเขียนโค้ด AI ค้นหาและอ่านเอกสารประกอบอย่างเป็นทางการ - ดูวิธี ใช้ไลบรารีของไคลเอ็นต์ใน Python, Node.js, Go หรือ Java
- ดูวิธี ใช้ gcloud CLI
- เรียกดูข้อมูลอ้างอิงของคลังเอกสารเพื่อดู แหล่งเอกสารประกอบทั้งหมดที่รองรับ
- ตรวจสอบข้อมูลอ้างอิงของ REST API เพื่อดูข้อกำหนด เมธอดทั้งหมด
- ตรวจสอบ โควต้าและขีดจำกัด สำหรับการจำกัดอัตราคำขอและโควต้าของ API