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.
Menavigasi 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 Developer Knowledge API. Kemudian, simpan kunci Anda ke variabel lingkungan:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Ganti YOUR_API_KEY dengan kunci Developer Knowledge API Anda.

Menelusuri dokumen

Gunakan gcloud developer-knowledge documents search-chunks perintah atau documents.searchDocumentChunks metode REST untuk menemukan bagian dokumen yang cocok dengan string kueri. Hasilnya mencakup bagian 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 bagian 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 bagian 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.

Menavigasi hasil penelusuran

Jika kueri penelusuran menampilkan beberapa kecocokan, Anda dapat menavigasi kumpulan hasil menggunakan parameter penomoran halaman:

--page-size (gcloud CLI) atau pageSize (bilangan bulat): menentukan jumlah maksimum hasil yang akan ditampilkan per halaman. Jika tidak ditentukan, API akan menggunakan lima hasil secara default. 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 flag --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 flag --query-filter di gcloud CLI atau filter parameter dalam permintaan REST untuk menerapkan filter ketat ke 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 (bilangan bulat): 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, bergantung pada jenis data kolom:

Kolom string (data_source, uri): mendukung = (sama dengan) dan != (tidak sama dengan) untuk pencocokan string yang tepat. Pencocokan ekspresi reguler, awalan, dan sebagian 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 URL parameter filter 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 beberapa 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 gcloud developer-knowledge documents describe perintah 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 Document resource 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 dari 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 --query-filter atau filter ekspresi (misalnya, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Mengambil beberapa dokumen dengan `BatchGetDocuments`

Gunakan documents.batchGet metode untuk mengambil hingga 20 dokumen berdasarkan 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 yang diminta Document 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 Document pesan.

Flag --view dan DocumentView enum mendukung nilai berikut:

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

Untuk mengambil metadata dokumen saja 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 Google APIs fields (mask kolom).

Memfilter kolom di `GetDocument`

Untuk mengambil kolom title, uri, dan updateTime dokumen saja:

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 kolom tertentu saja 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 id dan content bagian, title dan uri dokumen induk, 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 fungsi 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 permintaan BatchGetDocuments.
401 UNAUTHENTICATED: permintaan tidak memiliki kunci API atau token Bearer, atau menggunakan kredensial 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 retrieving-developer-knowledge kemampuan agen untuk membantu asisten coding AI Anda menelusuri dan membaca dokumentasi resmi.
Pelajari cara menggunakan library klien di Python, Node.js, Go, atau Java.
Pelajari cara me nggunakan gcloud CLI.
Telusuri referensi korpus untuk melihat semua sumber dokumentasi yang didukung.
Tinjau referensi REST API untuk mengetahui spesifikasi metode lengkap.
Periksa kuota dan batas untuk kuota dan pembatasan kapasitas API.

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

gcloud

REST

Menelusuri dokumen

gcloud

REST

Menavigasi 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`