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

เอกสารนี้จะแสดงวิธีใช้ 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 และ updateTime
  • relevanceScore: คะแนนความเกี่ยวข้องของ 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

  1. หากต้องการขอหน้าแรก ให้ส่งพารามิเตอร์ 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"
    }
    
  2. หากต้องการดึงหน้าถัดไป ให้ส่งค่า 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): รองรับ =, !=, <, <=, >, และ >=
  • โอเปอเรเตอร์เชิงตรรกะ: รวมเงื่อนไขโดยใช้ 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คำสั่งหรือ เมธอด 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: แสดงช่องข้อมูลเมตาพร้อมกับช่อง content Markdown ซึ่งเป็นค่าเริ่มต้นสำหรับ 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"

หากต้องการแสดงเฉพาะ 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: โปรเจ็กต์ใช้โควต้าเกิน ดูโควต้าและขีดจำกัด

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