Dokümanları arama ve alma

Bu kılavuzda, Google'ın herkese açık geliştirici dokümanlarını programatik olarak aramak ve almak için Developer Knowledge API'yi nasıl kullanacağınız gösterilmektedir. 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 bulacaksınız:

  • Doküman gövdesinde arama yapma
  • Arama sonuçları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ükleri optimize edildi.

Başlamadan önce API'yi etkinleştirdiğinizden ve bir Developer Knowledge API anahtarı oluşturduğunuzdan emin olun. Ardından, anahtarınızı bir ortam değişkenine kaydedin:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

SearchDocumentChunks ile doküman arama

Bir sorgu dizesiyle eşleşen doküman parçalarını bulmak için documents.searchDocumentChunks yöntemini kullanın. Sonuçlarda, 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 parent referans yer alır.

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

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 kaynağının adı (örneğin, documents/docs.cloud.google.com/bigquery/docs/introduction).
  • id: Belgedeki parça tanımlayıcısı (örneğin, 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ılabilir 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:

  • 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.
  • pageToken (dize): Sonraki sonuç sayfasını getirmek için önceki yanıtta alınan jetonu belirtir.

İlk sayfayı isteyin

Sayfa boyutunu ayarlamak 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ı alma

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ıtın dışında bırakılır.

Arama sonuçlarını filtreleme

Arama sonuçlarına katı bir filtre uygulamak için filter parametresini kullanın. Filtre ifadesi, her bir parça için üst dokümanın meta verilerine uygulanır.

filter ifadesi 500 karakterle sınırlıdır.

Desteklenen alanlar

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

  • content_length_bytes (tam sayı): Belgenin 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şmesi için = (eşittir) ve != (eşit değildir) operatörlerini destekler. Kısmi, önek ve normal ifade eşleşmeleri desteklenmez.
  • Zaman damgası alanları (update_time): =, <, <=, > ve >= değerlerini 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. REST API'yi curl ile çağırırken filtre parametresini URL olarak kodladığınızdan veya --data-urlencode kullandığınızdan emin olun.

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"

curl isteği:

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"

curl isteği:

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

curl isteği:

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"

curl isteği:

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"

curl isteği:

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"

GetDocument ile doküman alma

Tek bir belgenin içeriğinin tamamını almak için documents.get yöntemini kullanın.

Kaynak adları ve URI'ler

Developer Knowledge API'de belgelere referans verirken kaynak adları ve 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 GetDocument içindeki yol parametresi olarak veya BatchGetDocuments öğesinin names parametresinde iletin.
  • Web URI'si (uri): Şema dahil tam web URL'si (örneğin, https://docs.cloud.google.com/storage/docs/creating-buckets). 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").

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

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 verileri ve tam Markdown içeriğini içeren bir Document kaynağıdır.

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.

Doküman görünümlerini kullanma

view parametresi, Document iletilerinde hangi alanların doldurulacağını kontrol eder.

DocumentView numaralandırması aşağıdaki değerleri destekler:

  • DOCUMENT_VIEW_BASIC: Yalnızca temel meta veri alanlarını (name, uri, data_source, title, description, update_time ve view) döndürür. content alanı atlanır.
  • DOCUMENT_VIEW_CONTENT: Markdown content alanı ile birlikte meta veri alanlarını döndürür. Bu, GetDocument ve BatchGetDocuments için varsayılandır.
  • 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: view=DOCUMENT_VIEW_BASIC değerini ayarlayın:

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 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 üzere:

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"

Yalnızca id ve content parçalarını, üst doküman title ve uri'ü ve bir aramadan 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 başlıklı makaleyi 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 bölümüne bakın.

Sırada ne var?