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

Menelusuri dan mengambil dokumen

Panduan 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, pastikan Anda telah mengaktifkan API dan membuat kunci Developer Knowledge API. Kemudian, simpan kunci Anda ke variabel lingkungan:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Menelusuri dokumen dengan `SearchDocumentChunks`

Gunakan metode documents.searchDocumentChunks 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":

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.

Menelusuri hasil penelusuran

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

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.
pageToken (string): menentukan token yang diterima dalam respons sebelumnya untuk mengambil halaman hasil berikutnya.

Meminta halaman pertama

Untuk menetapkan ukuran halaman, 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"
}

Mengambil halaman berikutnya

Teruskan nilai nextPageToken ke parameter pageToken dalam permintaan Anda 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 parameter filter 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 memanggil REST API dengan curl, pastikan untuk mengenkode URL parameter filter atau menggunakan --data-urlencode.

Mencocokkan beberapa sumber data

Gunakan OR untuk menyertakan dokumen dari beberapa sumber:

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

Permintaan curl:

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

Permintaan curl:

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 berdasarkan panjang konten

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

content_length_bytes < 5000

Permintaan curl:

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"

Permintaan curl:

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"

Permintaan curl:

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 dengan `GetDocument`

Gunakan documents.get metode untuk mengambil konten lengkap satu dokumen.

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 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 ekspresi filter (misalnya, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Contoh berikut mengambil dokumen berdasarkan nama resource-nya:

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.

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

Parameter view mengontrol kolom mana yang diisi dalam Document pesan.

Enum DocumentView mendukung nilai berikut:

DOCUMENT_VIEW_BASIC: hanya menampilkan kolom metadata dasar (name, uri, data_source, title, description, update_time, dan view). Kolom content dihilangkan.
DOCUMENT_VIEW_CONTENT: menampilkan kolom metadata beserta kolom content Markdown. Ini adalah nilai default untuk GetDocument dan BatchGetDocuments.
DOCUMENT_VIEW_FULL: menampilkan semua kolom dokumen.

Untuk hanya mengambil metadata dokumen tanpa mendownload konten Markdown yang besar, tetapkan view=DOCUMENT_VIEW_BASIC:

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 hanya mengambil 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 hanya mengambil 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 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 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 Menjawab kueri dengan pembuatan yang didasarkan pada data.
Pelajari cara menggunakan library klien di Python, Node.js, Go, atau Java.
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 batas kapasitas API.

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

Menelusuri dokumen dengan SearchDocumentChunks

Menelusuri hasil penelusuran

Meminta halaman pertama

Mengambil halaman berikutnya

Memfilter hasil penelusuran

Kolom yang didukung

Operator yang didukung

Contoh filter

Mencocokkan beberapa sumber data

Memfilter berdasarkan stempel waktu

Memfilter berdasarkan panjang konten

Menggabungkan sumber data, stempel waktu, dan pengelompokan

Mengecualikan sumber data

Mengambil dokumen dengan GetDocument

Nama resource versus URI

Mengambil beberapa dokumen dengan BatchGetDocuments

Mengoptimalkan payload respons

Menggunakan tampilan dokumen

Menggunakan mask kolom

Memfilter kolom di GetDocument

Memfilter kolom di BatchGetDocuments

Memfilter kolom di SearchDocumentChunks

Menangani error

Langkah berikutnya

Menelusuri dan mengambil dokumen

Menelusuri dokumen dengan `SearchDocumentChunks`

Mengambil dokumen dengan `GetDocument`

Mengambil beberapa dokumen dengan `BatchGetDocuments`

Memfilter kolom di `GetDocument`

Memfilter kolom di `BatchGetDocuments`

Memfilter kolom di `SearchDocumentChunks`