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'nin nasıl kullanılacağı açıklanmaktadır. API, web sayfalarını manuel olarak kazımak yerine uygulamalarınızın alakalı metin snippet'leri bulmasına veya tam Markdown belgelerini getirmesine yardımcı olur.

Bu belgede, aşağıdaki görevlerle ilgili örnekler bulabilirsiniz:

Belge derlemi aranıyor.
Arama sonuçları arasında sayfalandı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ümanlardaki içerik parçalarının yanı sıra bu dokümanların tam içeriğini almak için kullanabileceğiniz bir parentreferans içerir.

Aşağıdaki örnekte, "BigQuery" ile eşleşen belgeler aranı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: Belgedeki eşleşen metin snippet'i.
document: Kaynak dokümanla ilgili meta veriler (ör. title, uri, dataSource ve updateTime).
relevanceScore: Arama sorgusuyla ilgili olarak parçanın alaka düzeyi puanı, [0.0, 1.0] aralığında.

Yanıt şeması ve kullanılabilen 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, sonuç kümesinde gezinmek için sayfalama parametrelerini kullanabilirsiniz:

--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 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 corpus 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): belgenin tam URI'si (örneğin, 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 >= biçimlerini destekler.
Tam sayı alanları (content_length_bytes): =, !=, <, <=, > ve >= değerlerini 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

Bayt boyutlarına göre doküman 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 kaynaklarla sınırlamak 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 belge kaynak adına göre alını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, content alanında meta veriler ve tam Markdown içeriğini içeren bir Document kaynağıdır.

Kaynak adları ve URI'ler

Geliştirici Bilgisi API'sinde belgelere referans verirken kaynak adları ve web URI'leri arasındaki farkı unutmayın:

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 (örneğin, 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 (örneğin, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

`BatchGetDocuments` ile birden fazla dokümanı alma

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

Aşağıdaki örnekte, ada göre iki belge alını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, istenen Document kaynakların, istediğiniz sırayla listesini içerir.

Yanıt yüklerini optimize etme

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

Belge görünümlerini kullanma

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

--view işareti ve DocumentView enum 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 belge 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 uygulamasını 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 da sınırlamak için standart Google API'leri fields sorgu parametresini (alan maskesi) kullanın.

`GetDocument` alanlarını 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` alanlarını 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` alanlarını filtreleme

Yalnızca id ve content parçalarını, üst doküman title ve uri'ü ve aramadaki nextPageToken'i 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ı eksik veya geçersiz bir anahtar kullanılıyor. Kimlik doğrulama konusunu inceleyin.
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 başlıklı makaleyi inceleyin.

Sırada ne var?

Belgelerden yanıt oluşturma başlıklı makaleyi inceleyin.
Developer Knowledge MCP sunucusuna bağlanın ve yapay zeka kod yazma desteği asistanınızın resmi belgeleri arayıp okumasına yardımcı olmak için retrieving-developer-knowledge agent skill'i yükleyin.
Python, Node.js, Go veya Java'da istemci kitaplıklarını kullanma hakkında bilgi edinin.
gcloud CLI'yı nasıl kullanacağınızı öğrenin.
Desteklenen tüm doküman kaynaklarını görüntülemek için corpus 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ırlamaları 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ı ve URI'ler

BatchGetDocuments ile birden fazla dokümanı alma

Yanıt yüklerini optimize etme

Belge görünümlerini kullanma

gcloud

REST

Alan maskelerini kullanma

GetDocument alanlarını filtreleme

BatchGetDocuments alanlarını filtreleme

SearchDocumentChunks alanlarını filtreleme

Hataları işleme

Sırada ne var?

Dokümanları arama ve alma

`BatchGetDocuments` ile birden fazla dokümanı alma

`GetDocument` alanlarını filtreleme

`BatchGetDocuments` alanlarını filtreleme

`SearchDocumentChunks` alanlarını filtreleme