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

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

  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 เพื่อใช้ตัวกรองที่เข้มงวดกับผลการค้นหา นิพจน์ตัวกรองจะมีผลกับข้อมูลเมตาของเอกสารหลักสำหรับแต่ละ ก้อน

นิพจน์ตัวกรองมีจำนวนอักขระสูงสุด 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"

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

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