Google Developer Knowledge API Rehberi: Kimlik Doğrulama, Arama ve Ajanlar

Bir kodlama ajanı Google geliştirici sayfalarını scrape edebilir; ancak sayfa düzenini çözmek, içerik keşfi yapmak, tekrarları ayıklamak ve alıntıları yönetmek bu durumda ajanın sorumluluğuna kalır. Google Developer Knowledge API bu işleri belgelenmiş bir arayüzün arkasına taşır. Ajanın güncel Google dokümanlarını denetlenebilir bağlam olarak kullanması gerektiğinde daha doğru varsayılan seçenektir. Yine de önemli bir sınırı var: Kapsadığı içerik tüm Google geliştirici web’i değil, seçilmiş bir doküman koleksiyonudur.

Bu API işlem yapmaz, doküman getirir

Google Developer Knowledge API, Google'ın herkese açık geliştirici dokümanlarını makinelerin işleyebileceği biçimde sunar. Google; belge arama, tam belge getirme, toplu getirme ve dayanaklı yanıtlar için ayrıntıları REST referansında açıklar.

Bu servis, uygulamalar ve ajanlar için salt okunur bir bağlam kaynağıdır. Özel bir Cloud projesine erişim vermez, IAM değişikliğini onaylamaz, kod dağıtımı yapmaz veya üretilen bir komutun güvenli olduğunu doğrulamaz. Ajanın herhangi bir yazma işlemi yapabilmesi için ayrı kimlik bilgilerine ve politika kontrollerine ihtiyacı vardır.

Koleksiyonun sınırını bilmek önemlidir. Google'ın API dokümantasyonu, genel web yerine herkese açık geliştirici dokümanlarını kapsar. Rastgele GitHub depolarında, Stack Overflow'da, özel runbook'larda veya üçüncü taraf kütüphanelerde arama yapmanın yerine geçmez. Google ayrıca dönen Markdown içeriğinin kaynak HTML'den üretildiğini belirtir; dolayısıyla bunu sayfanın tarayıcıda oluşturulan görünümünün byte byte kopyası olarak kabul etmemek gerekir.

Güncel kullanılabilirliği ve davranışı resmi API referansından ve sürüm notlarından doğrulayın.

Google Developer Knowledge API hangi işlemleri sunuyor?

REST yüzeyi, bir ajan politikasına doğrudan modellenebilecek kadar küçüktür:

Arama sonuçları parçalardan oluşur; eksiksiz sayfaların döneceği garanti edilmez. Sonuçtaki parent kaynağı, GetDocument ya da BatchGetDocuments çağrısına geçiş noktasıdır. Sağlam bir istemci, sayfaları getirmeden önce yinelenen parçaları parent değerine göre gruplar. Aksi hâlde tek bir sayfa, çok az ek bağlam sağladığı hâlde birden fazla getirme slotunu tüketebilir.

Tipik bir kaynak adı, belge kaynak biçimini izler:

documents/docs.cloud.google.com/storage/docs/creating-buckets

Bu kaynak adı deseni arama yanıtından sonra işe yarar; ancak ajan, adı belleğinden oluşturmaktansa servisin döndürdüğü tam parent değerini tercih etmelidir.

Arama modları farklı kanıt sözleşmeleri sunar

SearchDocumentChunks, kanıt öncelikli moddur. Ajanın belirli bir flag, parametre, izin, sürüm notu veya kod parçasına ihtiyacı olduğunda bunu kullanın. Çağrıyı yapan taraf parçayı inceleyebilir, belgenin URI bilgisini saklayabilir ve tam sayfanın getirilip getirilmeyeceğine karar verebilir.

GetDocument ve BatchGetDocuments bağlam modlarıdır. Yanıtın; ön koşullara, uyarılara, taşıma notlarına veya tek bir parçanın atlayabileceği komşu bölümlere bağlı olduğu durumlarda aramadan sonra kullanın. Bir tasarım sorusu birkaç resmi sayfayı kapsıyorsa toplu getirme kullanışlıdır.

AnswerQuery ise sentez modudur. Yanıtın koleksiyondaki kaynaklara dayanması isteniyorsa, “Hangi güncel Google Cloud seçeneği bu kısıtları karşılıyor?” gibi sınırları belli sorular için uygundur. Ancak referansları kontrol etmeden akıcı bir yanıtı olduğu gibi kabul etme gerekçesi değildir. Yüksek riskli kod değişikliklerinde arama ile tam belge getirmeyi birlikte kullanmak, ajana daha incelenebilir bir kanıt zinciri sağlar.

Kimlik doğrulamayı çağırana göre seçin

Pratikte üç kimlik doğrulama yaklaşımı vardır; fakat her biri aynı çağıran türüne uygun değildir.

Hızlı başlangıç için bir Google Cloud projesi oluşturun veya seçin, developerknowledge.googleapis.com hizmetini etkinleştirin ve yalnızca Developer Knowledge API ile sınırlandırılmış bir API anahtarı oluşturun. Kısıtlanmamış bir anahtarı ajan prompt'una, depoya, istemci tarafı pakete veya hata ayıklama günlüklerine koymayın.

Hizmeti etkinleştirmek için gereken en temel komut şudur:

gcloud services enable developerknowledge.googleapis.com \
  --project="$PROJECT_ID"

Yönetilen uygulamalarda ADC genellikle daha temiz bir sınır sunar. Google'ın Python istemci referansı, ortamdan bulunan kimlik bilgilerini, senkron ve asenkron istemcilerle birlikte belgeler. Böylece uygulamanın yapılandırma metninden anahtar ayrıştırması gerekmez; dağıtım ortamı çalışma anında kimliği sağlar.

OAuth, bağlantıyı paylaşılan statik bir giz yerine kullanıcının yetkilendirdiği etkileşimli ajanlar için uygundur. Kesin OAuth akışı MCP host'una bağlıdır. İstemcinin kimlik doğrulama desteği, API'nin kendisinden bağımsız olarak doğrulanmalıdır; MCP URL'sini kabul eden bir istemci bile header'ları, gizli değişkenleri veya token yenilemeyi farklı ele alabilir.

En yalın getirme akışı

Üretimdeki bir ajan, getirme sınırını açık biçimde tanımlamalıdır:

1. Sorudan gizli bilgileri ve konuyla ilgisiz depo içeriğini çıkarın.
2. Resmi koleksiyonda SearchDocumentChunks ile arama yapın.
3. Sonuçları üst belge kaynağına göre tekilleştirin.
4. Görev çevresel bağlam gerektiriyorsa en ilgili tam belgeleri getirin.
5. Dönen URI'yi, başlığı, zaman damgasını veya meta veriyi ve seçilen alıntıları saklayın.
6. Modelden yalnızca saklanan kanıtlara dayanarak yanıt vermesini isteyin.
7. Ajan kodu veya altyapıyı değiştirmeden önce testleri ve politika kontrollerini çalıştırın.

Arama için REST endpoint'i, Google'ın REST referansında belgelenmiştir:

GET https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks

Basit bir API anahtarı isteği şu şekildedir:

curl --get \
  'https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks' \
  --data-urlencode 'query=Cloud Storage bucket retention policy' \
  --data-urlencode 'pageSize=5' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Bir ayrıştırıcıyı sabitlemeden önce kesin yanıt şemasını ve alan adlarını güncel REST referansından kontrol edin. Arama; parçalar ve üst belge adları üretir, belge getirme işlemleri de bu adları tüketir.

Ajanı; boş sonuçlar, eksik parent değerleri, sayfalama, kimlik doğrulama hataları, kota veya hız sınırı yanıtları için mock'lanmış ya da snapshot alınmış yanıtlarla test edin. Yeniden denemeleri model prompt'unun dışında tutun; sınırlı backoff uygulayın ve kanıt getirilemediğinde kullanılacak açık bir fallback belirleyin.

Doğrudan API mi, MCP mi, web sayfası mı?

Aynı dokümantasyon kaynağı üç farklı biçimde sunulabilir:

Google'ın MCP dokümantasyonu, endpoint'i https://developerknowledge.googleapis.com/mcp olarak belirtir. MCP, ajan için bir adaptördür; farklı bir bilgi tabanı değildir. Temsili bir uzak sunucu yapılandırması şöyledir:

{
  "mcpServers": {
    "google-developer-knowledge": {
      "serverUrl": "https://developerknowledge.googleapis.com/mcp",
      "headers": {"x-goog-api-key": "${DEVELOPERKNOWLEDGE_API_KEY}"}
    }
  }
}

Host'un belgelediği gizli değişken söz dizimini kullanın; metin olarak yazılan ${...} ifadesinin her ortamda genişletileceğini varsaymayın. Bağlam maliyeti meselesi de önemini korur: Her göreve her aracı açmak, araç tanımları ve karar verme açısından ek yük getirebilir. Çoklu sunuculu ajan kurulumlarıyla ilgili gerçek bir kullanıcı tartışması bu kaygıyı doğrudan dile getiriyor:

“MCPs are very context heavy compared to skills - which only take up a few lines of text until they are invoked.” — u/junlim, Reddit discussion

Bu, Developer Knowledge MCP server'ından vazgeçmek için değil, onu Google odaklı görevlerde koşullu olarak kullanılabilir yapmak için bir nedendir. Firebase, Android, Google Cloud, Maps veya Flutter üzerinde çalışan bir ajan bu kaynaktan yararlanabilir; ilgisiz bir stack'i düzenleyen ajanın ise bunu varsayılan olarak çağırmaması gerekir.

Google geliştirici dokümanlarında API ne zaman scraping'den daha iyi?

Aşağıdaki koşulların çoğu geçerliyse API'yi kullanın:

• Görev, Google'ın sahip olduğu geliştirici dokümanlarını hedefliyor.
• Ajanın tek seferlik sayfa getirme yerine tekrarlanabilir aramaya ihtiyacı var.
• Yanıtın alıntı veya saklanmış bir kaynak izi içermesi gerekiyor.
• Ajanın ilgili bir parçayı eksiksiz belgeden ayırması gerekiyor.
• Akışın yapılandırılmış sayfalama, toplu işlem veya önbellekleme ihtiyacı var.
• Sayfa tasarımlarındaki değişikliklerin yeni bir HTML ayrıştırıcısı gerektirmemesi isteniyor.

Scraping yine de doğru fallback olabilir. Gereken sayfa desteklenen koleksiyonda yoksa, görev görsel etkileşim içeriyorsa veya tarayıcıda oluşturulan HTML ile gezinme durumunun birebir önemi varsa scraping kullanın. API erişimi yokken yaşanan bir incident sırasında geçici bir yoklama yöntemi olarak da makuldür; ancak fark ettirmeden üretim ortamının getirme sözleşmesine dönüşmemelidir.

API, yeni yayımlanan her sayfanın anında kullanılabilir olacağını garanti etmez. Google'ın sürüm notları indeksleme güncellemelerini açıklar; ancak ajan güncelliği, en yeni sayfanın zaten indekslendiğinin kanıtı olarak değil, doğrulanması gereken bir özellik olarak ele almalıdır. Yayın günü yapılan bir taşıma işleminde dönen meta veriyi güncel resmi sayfayla karşılaştırın ve kanıt eksikse güvenli biçimde durun.

Yayınlayacağım ajan politikası

Google'a özel bir kodlama ajanı için şu yönlendirme kuralını kullanın:

• Kesin uygulama ayrıntısı: Önce SearchDocumentChunks; parçada ön koşullar eksikse üst belgeyi getirin.
• Birden fazla sayfayı kapsayan tasarım sorusu: Arama yapın, ardından az sayıdaki ilgili parent için BatchGetDocuments kullanın.
• Basit açıklama sorusu: AnswerQuery kullanın, ancak yanıtta referansları zorunlu tutun.
• Google dışı veya özel dokümantasyon: Başka bir onaylı bağlayıcıya yönlendirin.
• Kod veya altyapı yazma işlemi: Getirme işlemi tavsiye niteliğindedir; testler, IAM, inceleme ve dağıtım kontrolleri zorunlu olmaya devam eder.

Politikanın izin verdiği durumlarda eksiksiz belgeleri önbelleğe alın, tekrarlanan aramaları debounce edin ve ham gizli bilgiler ya da gereksiz depo bağlamı yerine kaynak URI'lerini günlüğe kaydedin. Getirilen Markdown'ı güvenilmeyen girdi olarak değerlendirin: Kaynağın yetkili olması, içindeki her talimatı yazma yetkisi olan araçlara sahip bir ajan için güvenli kılmaz.

Çözülmemiş ödünleşim basittir. API, HTML scraping'e göre ajana daha temiz ve denetlenebilir bir sözleşme sunar; ancak tarayıcının sağladığı kapsama alanından ve anlık sayfa aslına uygunluğundan vazgeçer. Desteklenen Google dokümanları için API'yi varsayılan tercih edin; ardından scraping'i veya başka bir bağlayıcıyı iki yolu görünmez biçimde karıştırmak yerine açıkça tanımlanmış fallback olarak tutun.

Google Developer Knowledge API: Sık Sorulan Sorular

Developer Knowledge API, Google Search ile aynı şey mi?

Hayır. Bu, desteklenen bir Google geliştirici koleksiyonunda çalışan dokümantasyon getirme servisidir; genel amaçlı bir web arama API'si değildir. Özel dokümanlarda, rastgele GitHub içeriklerinde veya Google ile ilgili tüm sayfalarda otomatik olarak arama yapmaz.

AnswerQuery mi, SearchDocumentChunks mı kullanmalıyım?

Sınırları belirli ve kaynaklara dayanan bir açıklama için AnswerQuery kullanın. Ajanın incelenebilir kanıta, kesin söz dizimine veya kaynak izine ihtiyacı varsa SearchDocumentChunks kullanın; parça yeterli değilse üst belgeyi getirin.

API anahtarı gerekli mi?

Kısıtlanmış API anahtarı, prototip için en hızlı yoldur. Backend istemcileri ADC kullanabilir; etkileşimli MCP entegrasyonları ise host destekliyorsa OAuth kullanabilir. Bir istemcinin desteklediği kimlik doğrulama yönteminin diğerinde de otomatik olarak destekleneceğini varsaymayın.

Bir ajan bu API ile Google Cloud kaynaklarını dağıtabilir mi?

Hayır. API yalnızca dokümantasyon bağlamı sağlar. Dağıtım için yine ayrı araçlar, kimlik bilgileri, IAM izinleri, onaylar ve doğrulama gerekir.

Ne zaman scraping kullanmalıyım?

Sayfa API koleksiyonunun dışındaysa, görsel düzen önemliyse veya indeksin henüz göstermediği bir sayfaya ihtiyacınız varsa scraping yapın ya da bir tarayıcı bağlayıcısı kullanın. Ajanın scrape edilmiş içeriği API destekli alıntı gibi sunmaması için bu fallback'i açıkça kayda geçirin.

API, arama sonucunda eksiksiz bir sayfa döndürür mü?

Hayır. Arama, belge parçaları döndürür. Eksiksiz Markdown sayfasına ihtiyaç duyulduğunda, dönen üst belge kaynağını GetDocument veya BatchGetDocuments ile kullanın.