Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Menelusuri dan mengambil dokumen

Dokumen ini menunjukkan cara menggunakan Developer Knowledge API untuk menelusuri dan mengambil dokumentasi developer publik Google secara terprogram. Daripada melakukan scraping halaman web secara manual, API ini membantu aplikasi Anda menemukan cuplikan teks yang relevan atau mengambil dokumen Markdown lengkap.

Dalam dokumen ini, Anda akan menemukan contoh untuk tugas berikut:

Menelusuri korpus dokumentasi.
Menelusuri hasil penelusuran.
Menerapkan filter kompleks ke penelusuran Anda.
Mengambil konten dokumen lengkap.
Mengoptimalkan payload respons untuk mengurangi latensi.

Sebelum memulai, siapkan lingkungan untuk alat pilihan Anda:

gcloud

Instal dan konfigurasi gcloud CLI, lalu aktifkan Developer Knowledge API.

REST

Aktifkan API dan buat kunci API Developer Knowledge. Kemudian, simpan kunci Anda ke variabel lingkungan:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Ganti YOUR_API_KEY dengan kunci API Developer Knowledge Anda.

Menelusuri dokumen

Gunakan perintah gcloud developer-knowledge documents search-chunks atau metode REST documents.searchDocumentChunks untuk menemukan potongan dokumen yang cocok dengan string kueri. Hasilnya mencakup potongan konten dari dokumen yang cocok, beserta referensi parent yang dapat Anda gunakan untuk mengambil konten lengkap dokumen tersebut.

Contoh berikut menelusuri dokumen yang cocok dengan "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"

Outputnya mirip dengan hal berikut ini:

{
  "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
    }
  ]
}

Setiap hasil dalam daftar results mencakup:

parent: nama resource dokumen (misalnya, documents/docs.cloud.google.com/bigquery/docs/introduction).
id: ID potongan dalam dokumen (misalnya, chunk_0).
content: cuplikan teks yang cocok dari dokumen.
document: metadata tentang dokumen sumber, seperti title, uri, dataSource, dan updateTime.
relevanceScore: skor relevansi potongan dengan kueri penelusuran, dalam rentang [0.0, 1.0].

Untuk mengetahui informasi selengkapnya tentang skema respons dan semua kolom metadata yang tersedia, lihat referensi API documents.searchDocumentChunks.

Memberi nomor halaman pada hasil penelusuran

Saat kueri penelusuran menampilkan beberapa kecocokan, Anda dapat menelusuri kumpulan hasil menggunakan parameter penomoran halaman:

--page-size (gcloud CLI) atau pageSize (integer): menentukan jumlah maksimum hasil yang akan ditampilkan per halaman. Jika tidak ditentukan, API secara default akan menampilkan lima hasil. Nilai maksimum yang diizinkan adalah 100; nilai yang lebih besar dari 100 akan dikonversi menjadi 100.
--limit (gcloud CLI) atau pageToken (string): di gcloud CLI, gunakan --limit untuk mengontrol jumlah total hasil yang ditampilkan di seluruh halaman. Dalam permintaan REST, teruskan nilai pageToken yang diterima dalam respons sebelumnya untuk mengambil halaman hasil berikutnya.

gcloud

Teruskan tanda --page-size dan --limit untuk mengontrol jumlah hasil per halaman dan jumlah total hasil yang ditampilkan:

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --page-size=5 \
  --limit=10

REST

Untuk meminta halaman pertama, teruskan parameter pageSize dalam permintaan Anda:

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

Jika hasil tambahan tersedia, respons akan menyertakan 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"
}

Untuk mengambil halaman berikutnya, teruskan nilai nextPageToken ke parameter pageToken dalam permintaan berikutnya:
```
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"
```
Saat Anda mencapai halaman hasil terakhir, nextPageToken akan dihilangkan dari respons.

Memfilter hasil penelusuran

Gunakan tanda --query-filter di gcloud CLI atau parameter filter dalam permintaan REST untuk menerapkan filter ketat pada hasil penelusuran. Ekspresi filter diterapkan ke metadata dokumen induk untuk setiap bagian.

Ekspresi filter memiliki batas 500 karakter.

Kolom yang didukung

Anda dapat memfilter hasil penelusuran menggunakan kolom dokumen induk berikut:

content_length_bytes (integer): panjang kolom content dokumen dalam byte.
data_source (string): domain sumber dokumen, seperti docs.cloud.google.com atau firebase.google.com. Lihat referensi korpus untuk semua sumber data yang didukung.
update_time (stempel waktu): stempel waktu saat dokumen terakhir diperbarui. Nilai harus menggunakan format RFC 3339 (misalnya, "2025-01-01T00:00:00Z").
uri (string): URI lengkap dokumen (misalnya, https://docs.cloud.google.com/bigquery/docs/tables).

Operator yang didukung

Parser ekspresi filter mendukung operator yang berbeda-beda, bergantung pada jenis data kolom:

Kolom string (data_source, uri): mendukung = (sama dengan) dan != (tidak sama dengan) untuk pencocokan string yang tepat. Pencocokan sebagian, awalan, dan ekspresi reguler tidak didukung.
Kolom stempel waktu (update_time): mendukung =, <, <=, >, dan >=.
Kolom bilangan bulat (content_length_bytes): mendukung =, !=, <, <=, >, dan >=.
Operator logika: menggabungkan kondisi menggunakan AND, OR, dan NOT (atau -).

Contoh Filter

Contoh berikut menunjukkan cara membuat ekspresi filter. Saat menggunakan gcloud CLI, teruskan ekspresi ke flag --query-filter. Saat memanggil REST API dengan curl, pastikan untuk mengenkode parameter filter ke URL atau menggunakan --data-urlencode.

Mencocokkan satu sumber data

Membatasi hasil penelusuran ke satu domain dokumentasi:

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"

Mencocokkan beberapa sumber data

Gunakan OR untuk menyertakan dokumen dari berbagai sumber:

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"

Memfilter menurut stempel waktu

Gunakan operator perbandingan dengan stempel waktu RFC 3339 untuk menemukan konten yang diperbarui setelah tanggal tertentu:

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"

Memfilter menurut panjang konten

Gunakan operator perbandingan dengan content_length_bytes untuk menemukan dokumen berdasarkan ukuran byte-nya:

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"

Menggabungkan sumber data, stempel waktu, dan pengelompokan

Gabungkan AND, OR, dan tanda kurung (...) untuk membatasi hasil ke sumber tertentu yang diperbarui setelah tanggal tertentu:

(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"

Mengecualikan sumber data

Gunakan NOT atau != untuk mengecualikan hasil dari sumber tertentu:

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"

Mengambil dokumen

Gunakan perintah gcloud developer-knowledge documents describe atau metode REST documents.get untuk mengambil konten lengkap satu dokumen.

Contoh berikut mengambil dokumen berdasarkan nama resource-nya:

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"

Responsnya adalah resource Document yang berisi metadata dan konten Markdown lengkap di kolom content.

Nama resource versus URI

Saat mereferensikan dokumen di Developer Knowledge API, perhatikan perbedaan antara nama resource dan URI web:

Nama resource (parent, name): diformat sebagai documents/{uri_without_scheme} (misalnya, documents/docs.cloud.google.com/storage/docs/creating-buckets). Teruskan nilai ini sebagai argumen posisi di gcloud developer-knowledge documents describe, parameter jalur di GetDocument, atau di parameter names BatchGetDocuments.
URI web (uri): URL web lengkap termasuk skema (misalnya, https://docs.cloud.google.com/storage/docs/creating-buckets). Gunakan format ini untuk kolom uri saat membuat ekspresi --query-filter atau filter (misalnya, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Mengambil beberapa dokumen dengan `BatchGetDocuments`

Gunakan metode documents.batchGet untuk mengambil hingga 20 dokumen menurut nama dalam satu panggilan API. Cara ini lebih efisien daripada membuat beberapa permintaan GetDocument.

Contoh berikut mengambil dua dokumen berdasarkan nama:

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"

Respons berisi daftar resource Document yang diminta dalam urutan yang Anda minta.

Mengoptimalkan payload respons

Konten dokumen dalam format Markdown bisa berukuran besar. Jika aplikasi Anda hanya memerlukan metadata (seperti judul halaman, URI, atau stempel waktu) atau kolom tertentu, Anda dapat mengoptimalkan ukuran payload untuk mengurangi bandwidth dan latensi.

Menggunakan tampilan dokumen

Flag --view di gcloud CLI atau parameter view dalam permintaan REST mengontrol kolom mana yang diisi dalam pesan Document.

Flag --view dan enum DocumentView mendukung nilai berikut:

--view=basic (gcloud CLI) atau DOCUMENT_VIEW_BASIC: menampilkan hanya kolom metadata dasar (name, uri, dataSource, title, description, updateTime, dan view). Kolom content tidak ditampilkan.
--view=content (gcloud CLI) atau DOCUMENT_VIEW_CONTENT: menampilkan kolom metadata bersama dengan kolom content Markdown. Ini adalah default untuk gcloud developer-knowledge documents describe, GetDocument, dan BatchGetDocuments.
--view=full (gcloud CLI) atau DOCUMENT_VIEW_FULL: menampilkan semua kolom dokumen.

Untuk mengambil hanya metadata dokumen tanpa mendownload konten Markdown yang besar, tentukan tampilan dokumen dasar:

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"

Anda juga dapat menggunakan view=DOCUMENT_VIEW_BASIC dengan 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"

Menggunakan mask kolom

Untuk lebih membatasi payload respons ke kolom tertentu, gunakan parameter kueri fields (mask kolom) Google API standar.

Memfilter kolom di `GetDocument`

Untuk mengambil hanya kolom title, uri, dan updateTime dari dokumen:

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

Memfilter kolom di `BatchGetDocuments`

Untuk mengambil hanya kolom tertentu untuk setiap dokumen dalam batch:

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"

Memfilter kolom di `SearchDocumentChunks`

Untuk hanya menampilkan potongan id dan content, dokumen induk title dan uri, serta nextPageToken dari penelusuran:

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

Menangani error

Developer Knowledge API menampilkan kode status HTTP standar. Contoh fungsional berikut memetakan kode status HTTP dan penyebabnya di Developer Knowledge API:

400 INVALID_ARGUMENT:
- String ekspresi filter melebihi 500 karakter.
- Stempel waktu update_time tidak valid (harus menggunakan format RFC 3339).
- Lebih dari 20 nama dokumen diberikan dalam BatchGetDocuments permintaan.
401 UNAUTHENTICATED: permintaan tidak memiliki kunci API atau menggunakan kunci yang tidak valid. Lihat Autentikasi.
404 NOT_FOUND: nama dokumen yang diminta tidak ada atau termasuk dalam domain yang tidak disertakan dalam korpus.
429 RESOURCE_EXHAUSTED: project telah melampaui kuotanya. Lihat Kuota dan batas.

Langkah berikutnya

Lihat Menghasilkan jawaban dari dokumentasi.
Hubungkan ke server MCP Developer Knowledge dan instal kemampuan agen retrieving-developer-knowledge untuk membantu asisten pengodean AI Anda menelusuri dan membaca dokumentasi resmi.
Pelajari cara menggunakan library klien di Python, Node.js, Go, atau Java.
Pelajari cara menggunakan gcloud CLI.
Jelajahi referensi korpus untuk melihat semua sumber dokumentasi yang didukung.
Tinjau referensi REST API untuk mengetahui spesifikasi metode selengkapnya.
Periksa kuota dan batas untuk pembatasan kapasitas dan kuota API.

Menelusuri dan mengambil dokumen Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

gcloud

REST

Menelusuri dokumen

gcloud

REST

Memberi nomor halaman pada hasil penelusuran

gcloud

REST

Memfilter hasil penelusuran

Kolom yang didukung

Operator yang didukung

Contoh Filter

Mencocokkan satu sumber data

gcloud

REST

Mencocokkan beberapa sumber data

gcloud

REST

Memfilter menurut stempel waktu

gcloud

REST

Memfilter menurut panjang konten

gcloud

REST

Menggabungkan sumber data, stempel waktu, dan pengelompokan

gcloud

REST

Mengecualikan sumber data

gcloud

REST

Mengambil dokumen

gcloud

REST

Nama resource versus URI

Mengambil beberapa dokumen dengan BatchGetDocuments

Mengoptimalkan payload respons

Menggunakan tampilan dokumen

gcloud

REST

Menggunakan mask kolom

Memfilter kolom di GetDocument

Memfilter kolom di BatchGetDocuments

Memfilter kolom di SearchDocumentChunks

Menangani error

Langkah berikutnya

Menelusuri dan mengambil dokumen

Mengambil beberapa dokumen dengan `BatchGetDocuments`

Memfilter kolom di `GetDocument`

Memfilter kolom di `BatchGetDocuments`

Memfilter kolom di `SearchDocumentChunks`