เอกสารนี้แสดงวิธีใช้ Developer Knowledge API เพื่อค้นหาและดึงข้อมูลเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์แบบสาธารณะของ Google โดยใช้โปรแกรม API จะช่วยให้แอปพลิเคชันของคุณค้นหาข้อความที่เกี่ยวข้อง หรือดึงเอกสารมาร์กดาวน์ฉบับเต็มได้แทนที่จะต้องคัดลอกข้อมูลจากหน้าเว็บด้วยตนเอง
ในเอกสารนี้ คุณจะเห็นตัวอย่างสำหรับงานต่อไปนี้
- กำลังค้นหาคลังเอกสารประกอบ
- การแบ่งหน้าผ่านผลการค้นหา
- ใช้ตัวกรองที่ซับซ้อนกับการค้นหา
- การดึงเนื้อหาทั้งหมดของเอกสาร
- การเพิ่มประสิทธิภาพเพย์โหลดการตอบกลับเพื่อลดเวลาในการตอบสนอง
ก่อนเริ่มต้น ให้ตั้งค่าสภาพแวดล้อมสำหรับเครื่องมือที่คุณต้องการ ดังนี้
gcloud
ติดตั้งและกำหนดค่า gcloud CLI รวมถึงเปิดใช้ Developer Knowledge API
REST
เปิดใช้ API และสร้างคีย์ API สำหรับ Developer Knowledge จากนั้นบันทึกคีย์ลงในตัวแปรสภาพแวดล้อมโดยทำดังนี้
export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"
แทนที่ YOUR_API_KEY ด้วยคีย์ API ของ Developer Knowledge
ค้นหาเอกสาร
ใช้gcloud developer-knowledge documents search-chunks
คำสั่งหรือเมธอด REST documents.searchDocumentChunks
เพื่อค้นหาชิ้นส่วนเอกสารที่ตรงกับสตริงการค้นหา ผลลัพธ์
ประกอบด้วยเนื้อหาบางส่วนจากเอกสารที่ตรงกัน พร้อมด้วย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_0)content: ข้อมูลโค้ดข้อความที่ตรงกันจากเอกสารdocument: ข้อมูลเมตาเกี่ยวกับเอกสารแหล่งที่มา เช่นtitle,uri,dataSourceและupdateTimerelevanceScore: คะแนนความเกี่ยวข้องของก้อนข้อมูลกับคำค้นหา ในช่วง[0.0, 1.0]
ดูข้อมูลเพิ่มเติมเกี่ยวกับสคีมาการตอบกลับและฟิลด์ข้อมูลเมตาทั้งหมดที่มีได้ที่เอกสารอ้างอิง API ของ documents.searchDocumentChunks
แบ่งหน้าผลการค้นหา
เมื่อคำค้นหาแสดงผลลัพธ์ที่ตรงกันหลายรายการ คุณจะไปยังชุดผลลัพธ์ได้โดยใช้พารามิเตอร์การแบ่งหน้า ดังนี้
--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 เพื่อใช้ตัวกรองที่เข้มงวดกับผลการค้นหา
นิพจน์ตัวกรองจะมีผลกับข้อมูลเมตาของเอกสารหลักสำหรับแต่ละ
ก้อน
นิพจน์ตัวกรองมีจำนวนอักขระสูงสุด 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(หรือ-)
ตัวอย่างการกรอง
ตัวอย่างต่อไปนี้แสดงวิธีสร้างนิพจน์ตัวกรอง เมื่อใช้ 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คำสั่ง
หรือเมธอด REST documents.get เพื่อ
ดึงเนื้อหาทั้งหมดของเอกสารเดียว
ตัวอย่างต่อไปนี้จะดึงข้อมูลเอกสารตามชื่อทรัพยากร
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
ทรัพยากรที่ขอตามลำดับที่คุณขอ
เพิ่มประสิทธิภาพเพย์โหลดการตอบกลับ
เนื้อหาเอกสารในรูปแบบมาร์กดาวน์อาจมีขนาดใหญ่ หากแอปพลิเคชันของคุณต้องการเพียงข้อมูลเมตา (เช่น ชื่อหน้า, 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: จะแสดงช่องข้อมูลเมตาพร้อมกับฟิลด์contentมาร์กดาวน์ นี่คือค่าเริ่มต้นสำหรับ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 เอกสารหลัก 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: โปรเจ็กต์ใช้โควต้าเกิน ดูโควต้าและขีดจำกัด
ขั้นตอนถัดไป
- โปรดดูที่สร้างคำตอบจากเอกสารประกอบ
- เชื่อมต่อกับเซิร์ฟเวอร์ MCP ความรู้สำหรับนักพัฒนาซอฟต์แวร์และติดตั้ง
retrieving-developer-knowledgeทักษะของเอเจนต์เพื่อช่วยผู้ช่วยการเขียนโค้ด AI ในการค้นหาและอ่านเอกสารประกอบอย่างเป็นทางการ - ดูวิธีใช้ไลบรารีของไคลเอ็นต์ใน Python, Node.js, Go หรือ Java
- ดูวิธีใช้ gcloud CLI
- เรียกดูการอ้างอิงคลังข้อความเพื่อดู แหล่งที่มาของเอกสารทั้งหมดที่รองรับ
- ดูข้อกำหนดของเมธอดทั้งหมดได้ที่ข้อมูลอ้างอิง REST API
- ดูโควต้าและขีดจำกัดสำหรับการจำกัดอัตราคำขอและโควต้าของ API