Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

Dokümanları arama ve alma

Bu belgede, Google'ın herkese açık geliştirici belgelerini programatik olarak aramak ve almak için Developer Knowledge API'yi nasıl kullanacağınız açıklanmaktadır. API, web sayfalarını manuel olarak kazımak yerine uygulamalarınızın alakalı metin snippet'lerini bulmasına veya tam Markdown dokümanlarını getirmesine yardımcı olur.

Bu dokümanda, aşağıdaki görevlerle ilgili örnekler bulabilirsiniz:

Belge kümesinde arama yapılıyor.
Arama sonuçlarında sayfalara ayırma.
Aramanıza karmaşık filtreler uyguladığınızda
Belgenin tüm içeriğini alma
Gecikmeyi azaltmak için yanıt yüklerini optimize etme

Başlamadan önce, tercih ettiğiniz araç için ortamınızı ayarlayın:

gcloud

gcloud CLI'yı yükleyip yapılandırın ve Developer Knowledge API'yi etkinleştirin.

REST

API'yi etkinleştirin ve Developer Knowledge API anahtarı oluşturun. Ardından anahtarınızı bir ortam değişkenine kaydedin:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

YOUR_API_KEY kısmını Developer Knowledge API anahtarınızla değiştirin.

Belge arama

Bir sorgu dizesiyle eşleşen belge parçalarını bulmak için gcloud developer-knowledge documents search-chunks komutunu veya documents.searchDocumentChunks REST yöntemini kullanın. Sonuçlar, eşleşen dokümanlardan içerik parçaları ve bu dokümanların tam içeriğini almak için kullanabileceğiniz bir parent referansı içerir.

Aşağıdaki örnekte "BigQuery" ile eşleşen dokümanlar aranmaktadır:

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery"

REST

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

Çıkış şuna benzer:

{
  "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 listesindeki her sonuç şunları içerir:

parent: Belge kaynak adı (örneğin, documents/docs.cloud.google.com/bigquery/docs/introduction).
id: Belgedeki parça tanımlayıcısı (ör. chunk_0).
content: Dokümandaki eşleşen metin snippet'i.
document: Kaynak dokümanla ilgili meta veriler (ör. title, uri, dataSource ve updateTime).
relevanceScore: Parçanın arama sorgusuyla alaka düzeyi puanı ([0.0, 1.0] aralığında).

Yanıt şeması ve mevcut tüm meta veri alanları hakkında daha fazla bilgi için documents.searchDocumentChunks API referansına bakın.

Arama sonuçlarını sayfalandırma

Bir arama sorgusu birden fazla eşleşme döndürdüğünde, sayfalama parametrelerini kullanarak sonuç kümesinde gezinebilirsiniz:

--page-size (gcloud CLI) veya pageSize (tam sayı): Sayfa başına döndürülecek maksimum sonuç sayısını belirtir. Belirtilmezse API varsayılan olarak beş sonuç döndürür. İzin verilen maksimum değer 100'dür. 100'den büyük değerler 100'e zorlanır.
--limit (gcloud CLI) veya pageToken (dize): gcloud CLI'da, sayfalar genelinde döndürülen toplam sonuç sayısını kontrol etmek için --limit kullanın. REST isteklerinde, sonuçların sonraki sayfasını getirmek için önceki bir yanıtta alınan pageToken değerini iletin.

gcloud

Sayfa başına sonuç sayısını ve döndürülen toplam sonuç sayısını kontrol etmek için --page-size ve --limit işaretlerini iletin:

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

REST

İlk sayfayı istemek için isteğinizde pageSize parametresini iletin:

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

Ek sonuçlar varsa yanıtta nextPageToken yer alır:

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

Sonraki sayfaları almak için bir sonraki isteğinizde nextPageToken değerini pageToken parametresine iletin:
```
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"
```
Sonuçların son sayfasına ulaştığınızda nextPageToken yanıttan çıkarılır.

Arama sonuçlarını filtreleme

Arama sonuçlarına katı bir filtre uygulamak için gcloud CLI'da --query-filter işaretini veya REST isteklerinde filter parametresini kullanın. Filtre ifadesi, her bir parça için üst dokümanın meta verilerine uygulanır.

Filtre ifadesi 500 karakter sınırlamasına sahiptir.

Desteklenen alanlar

Arama sonuçlarınızı aşağıdaki üst doküman alanlarını kullanarak filtreleyebilirsiniz:

content_length_bytes (tam sayı): Dokümanın content alanının bayt cinsinden uzunluğu.
data_source (dize): Dokümanın kaynak alanı (ör. docs.cloud.google.com veya firebase.google.com). Desteklenen tüm veri kaynakları için grup referansını inceleyin.
update_time (zaman damgası): Belgenin en son güncellendiği zaman damgası. Değerler RFC 3339 biçiminde olmalıdır (örneğin, "2025-01-01T00:00:00Z").
uri (dize): Dokümanın tam URI'si (ör. https://docs.cloud.google.com/bigquery/docs/tables).

Desteklenen operatörler

Filtre ifadesi ayrıştırıcısı, alanın veri türüne bağlı olarak farklı operatörleri destekler:

Dize alanları (data_source, uri): Tam dize eşleştirme için = (eşittir) ve != (eşit değildir) operatörlerini destekler. Kısmi, ön ek ve normal ifade eşleşmeleri desteklenmez.
Zaman damgası alanları (update_time): =, <, <=, > ve >= desteklenir.
Tam sayı alanları (content_length_bytes): =, !=, <, <=, > ve >= operatörlerini destekler.
Mantıksal operatörler: AND, OR ve NOT (veya -) kullanarak koşulları birleştirin.

Filtre örnekleri

Aşağıdaki örneklerde filtre ifadelerinin nasıl oluşturulacağı gösterilmektedir. gcloud CLI'yı kullanırken ifadeyi --query-filter işaretine iletin. REST API'yi curl ile çağırırken filter parametresini URL olarak kodladığınızdan veya --data-urlencode kullandığınızdan emin olun.

Tek bir veri kaynağını eşleştirme

Arama sonuçlarını tek bir doküman alanıyla sınırlama:

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"

Birden fazla veri kaynağını eşleştirme

Birden fazla kaynaktan doküman eklemek için OR simgesini kullanın:

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"

Zaman damgasına göre filtreleme

Belirli bir tarihten sonra güncellenen içerikleri bulmak için RFC 3339 zaman damgalarıyla karşılaştırma operatörlerini kullanın:

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"

İçerik uzunluğuna göre filtreleme

Belgeleri bayt boyutuna göre bulmak için content_length_bytes ile karşılaştırma operatörlerini kullanın:

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"

Veri kaynağı, zaman damgası ve gruplandırmayı birleştirme

Sonuçları belirli bir tarihten sonra güncellenen belirli kaynaklarla kısıtlamak için AND, OR ve parantezleri (...) birleştirin:

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

Veri kaynaklarını hariç tutma

Belirli bir kaynaktan gelen sonuçları hariç tutmak için NOT veya != simgesini kullanın:

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"

Belge alma

Tek bir belgenin tüm içeriğini almak için gcloud developer-knowledge documents describe komutunu veya documents.get REST yöntemini kullanın.

Aşağıdaki örnekte, bir doküman kaynak adına göre alınmaktadır:

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"

Yanıt, meta verileri ve content alanındaki tam Markdown içeriğini barındıran bir Document kaynağıdır.

Kaynak adları ile URI'lerin karşılaştırması

Developer Knowledge API'deki belgelere referans verirken kaynak adları ile web URI'leri arasındaki farka dikkat edin:

Kaynak adı (parent, name): documents/{uri_without_scheme} olarak biçimlendirilir (örneğin, documents/docs.cloud.google.com/storage/docs/creating-buckets). Bu değeri gcloud developer-knowledge documents describe içinde konumsal bağımsız değişken, GetDocument içinde yol parametresi veya BatchGetDocuments öğesinin names parametresi olarak iletin.
Web URI'si (uri): Şemayı içeren tam web URL'si (ör. https://docs.cloud.google.com/storage/docs/creating-buckets). --query-filter veya filter ifadeleri oluştururken uri alanı için bu biçimi kullanın (ör. uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

`BatchGetDocuments` ile birden fazla doküman alma

Tek bir API çağrısında ada göre en fazla 20 belge almak için documents.batchGet yöntemini kullanın. Bu, birden fazla GetDocument isteği göndermekten daha verimlidir.

Aşağıdaki örnekte, iki doküman ada göre alınmaktadır:

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"

Yanıt, istediğiniz Document kaynaklarının istediğiniz sıradaki bir listesini içerir.

Yanıt yüklerini optimize etme

Markdown biçimindeki doküman içerikleri büyük olabilir. Uygulamanız yalnızca meta verilere (sayfa başlıkları, URI'ler veya zaman damgaları gibi) ya da belirli alanlara ihtiyaç duyuyorsa bant genişliğini ve gecikmeyi azaltmak için yük boyutlarını optimize edebilirsiniz.

Doküman görünümlerini kullanma

gcloud CLI'daki --view işareti veya REST isteklerindeki view parametresi, Document mesajlarında hangi alanların doldurulacağını kontrol eder.

--view işareti ve DocumentView enum'u aşağıdaki değerleri destekler:

--view=basic (gcloud CLI) veya DOCUMENT_VIEW_BASIC: Yalnızca temel meta veri alanlarını (name, uri, dataSource, title, description, updateTime ve view) döndürür. content alanı atlanır.
--view=content (gcloud CLI) veya DOCUMENT_VIEW_CONTENT: Markdown content alanı ile birlikte meta veri alanlarını döndürür. Bu, gcloud developer-knowledge documents describe, GetDocument ve BatchGetDocuments için varsayılandır.
--view=full (gcloud CLI) veya DOCUMENT_VIEW_FULL: Tüm doküman alanlarını döndürür.

Büyük Markdown içeriğini indirmeden yalnızca doküman meta verilerini almak için temel doküman görünümünü belirtin:

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 özelliğini BatchGetDocuments ile de kullanabilirsiniz:

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"

Alan maskelerini kullanma

Yanıt yüklerini belirli alanlarla daha fazla sınırlamak için standart Google API'leri fields sorgu parametresini (alan maskesi) kullanın.

`GetDocument` içindeki alanları filtreleme

Bir dokümanın yalnızca title, uri ve updateTime alanlarını almak için:

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

`BatchGetDocuments` içindeki alanları filtreleme

Bir gruptaki her doküman için yalnızca belirli alanları almak istiyorsanız:

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"

`SearchDocumentChunks` içindeki alanları filtreleme

Aramadan yalnızca id ve content parçalarını, title ve uri üst dokümanlarını ve nextPageToken değerini döndürmek için:

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

Hataları işleme

Developer Knowledge API, standart HTTP durum kodları döndürür. Aşağıdaki işlevsel örnekler, Developer Knowledge API'deki HTTP durum kodlarını ve nedenlerini eşler:

400 INVALID_ARGUMENT:
- filter ifadesi dizesi 500 karakteri aşıyor.
- update_time zaman damgası geçersiz (RFC 3339 biçimi kullanılmalıdır).
- Bir BatchGetDocuments istekte 20'den fazla belge adı sağlandı.
401 UNAUTHENTICATED: İstekte API anahtarı veya hamiline ait jeton eksik ya da geçersiz kimlik bilgileri kullanılıyor. Kimlik doğrulama bölümüne bakın.
404 NOT_FOUND: İstenen belge adı mevcut değil veya derlemeye dahil edilmeyen bir alana ait.
429 RESOURCE_EXHAUSTED: Proje, kotasını aşmıştır. Kota ve sınırlar bölümüne bakın.

Sırada ne var?

Belgelerden yanıt oluşturma başlıklı makaleyi inceleyin.
Yapay zeka kod yazma desteğinizin resmi belgeleri arayıp okumasına yardımcı olmak için Developer Knowledge MCP sunucusuna bağlanın ve retrieving-developer-knowledge temsilci becerisini yükleyin.
Python, Node.js, Go veya Java'da istemci kitaplıklarını nasıl kullanacağınızı öğrenin.
gcloud CLI'yı nasıl kullanacağınızı öğrenin.
Desteklenen tüm belge kaynaklarını görüntülemek için derlem referansına göz atın.
Yöntem spesifikasyonlarının tamamı için REST API referansını inceleyin.
API sıklık sınırları ve kotaları için kota ve sınırları kontrol edin.

Dokümanları arama ve alma Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

gcloud

REST

Belge arama

gcloud

REST

Arama sonuçlarını sayfalandırma

gcloud

REST

Arama sonuçlarını filtreleme

Desteklenen alanlar

Desteklenen operatörler

Filtre örnekleri

Tek bir veri kaynağını eşleştirme

gcloud

REST

Birden fazla veri kaynağını eşleştirme

gcloud

REST

Zaman damgasına göre filtreleme

gcloud

REST

İçerik uzunluğuna göre filtreleme

gcloud

REST

Veri kaynağı, zaman damgası ve gruplandırmayı birleştirme

gcloud

REST

Veri kaynaklarını hariç tutma

gcloud

REST

Belge alma

gcloud

REST

Kaynak adları ile URI'lerin karşılaştırması

BatchGetDocuments ile birden fazla doküman alma

Yanıt yüklerini optimize etme

Doküman görünümlerini kullanma

gcloud

REST

Alan maskelerini kullanma

GetDocument içindeki alanları filtreleme

BatchGetDocuments içindeki alanları filtreleme

SearchDocumentChunks içindeki alanları filtreleme

Hataları işleme

Sırada ne var?

Dokümanları arama ve alma

`BatchGetDocuments` ile birden fazla doküman alma

`GetDocument` içindeki alanları filtreleme

`BatchGetDocuments` içindeki alanları filtreleme

`SearchDocumentChunks` içindeki alanları filtreleme