Bir arama API'sinden göç: envanter, alan eşleme ve güvenli geçiş

Arama API'leri emekliye ayrılır, yeniden fiyatlanır, yeniden yapılandırılır ya da kullanım koşulları sessizce değişir; üzerine kurulan uygulama da taşınmak zorunda kalır. Bing Web Search API pek çok geliştiricinin bildiği örnektir: ekipler ürünlerini onun yanıt biçimine göre kurdu, Microsoft ise sonrasında geliştiricileri bağımsız Bing Search API'lerinden kendi ajan servislerinin içindeki kaynak dayandırma özelliğine yönlendirdi. Güncel durum ve olası halef ürün için Microsoft'un kendi dokümantasyonuna bakın. Taşınma nedeniniz ne olursa olsun iş aynı dört adımı izler: her bağımlılığı bulun, veri modelini çevirin, yeni sağlayıcıyı kendi trafiğinizle kanıtlayın ve uçurum kenarı olmadan geçiş yapın. Bu rehber bu adımları tek tek ele alıyor.

Eski API'nin kullanıldığı her yeri envantere alın

Göze batan çağrı noktası nadiren tek noktadır. Kodda ve yapılandırmada uç noktanın alan adını, anahtar başlığını (Bing için Ocp-Apim-Subscription-Key), istemci kütüphanelerini ve ortam değişkenlerini arayın. Sonra ana kod tabanının ötesine bakın: zamanlanmış işler, not defterleri, birinin yazdığı bir tablo makrosu, sizin servisinizi çağıran ve sizin servisinizin de arama API'sini çağırdığı bir iş ortağı entegrasyonu.

Her kullanım için şunları kaydedin:

• Hangi uç noktaları çağırdığı: web, haber, görsel, video, varlık, otomatik öneri, yazım denetimi, özel arama.
• Hangi parametreleri gönderdiği ve yanıttaki hangi alanları gerçekten okuduğu.
• Hacim ve kullanım biçimi: kullanıcı başına etkileşimli çağrılar, toplu işler, bir ajan döngüsü.
• Sonuçların saklanıp saklanmadığı, kullanıcılara gösterilip gösterilmediği ya da bir modele verilip verilmediği; ne kadar süre kaldıkları.
• Sahibinin kim olduğu ve durursa gözle görülür biçimde neyin bozulacağı.

En değerli çıktı, okunan alanların listesidir. Uygulamanın yalnızca birkaç alana dokunduğunu fark edebilirsiniz; bu, göçü korktuğunuzdan küçük kılar. Ya da tek bir sıra dışı özelliğe bağlı olduğunu görürsünüz; bu da yeni sağlayıcı seçimini belirler.

Alanları ve parametreleri eşleyin

Yanıt alanları

Uygulama içinde kullanılacak, sağlayıcıdan bağımsız bir sonuç biçimi tanımlayın ve yeni bir sağlayıcıyı eşlemeden önce eskisini bu biçime eşleyin. Web sonuçları için bir taslak:

İstek parametreleri ve davranış

• Pazar ve dil. Bing, en-US ya da tr-TR gibi mkt kodlarını ve arayüz dili için setLang parametresini kullanır. Yeni sağlayıcı ülke ve dili ayrı parametrelere bölebilir ya da daha az bölgeyi kapsayabilir.
• Güncellik. Bing'in freshness parametresi gün, hafta ya da aya göre filtreler. Yeni sağlayıcının yayın tarihine mi, tarama tarihine mi, yoksa bambaşka bir şeye mi göre filtrelediğini kontrol edin.
• Güvenli arama. safeSearch seviyeleri birebir eşleşmeyebilir; emin olamadığınızda daha katı ayarı seçin.
• Sayfalama. count ve offset, imleçlere ya da sayfa numaralarına dönüşebilir ve gidilebilecek azami derinlik farklı olabilir.
• Siteyle sınırlama. site: işlecine dayanan sorgular yerine ayrı bir alan adı filtresi gerekebilir.
• Dikey aramalar. Haber, görsel ve video başka sağlayıcılarda ayrı ürünler olabilir ya da hiç olmayabilir.

Önce araya ince bir bağdaştırıcı koyun

Hiçbir şeyi değiştirmeden önce bütün çağrıları, bağımsız biçimi döndüren tek bir iç arayüzden geçirin. Bu değişikliği arkasında hâlâ eski sağlayıcı varken yayına alın ve kullanıcılar için hiçbir şeyin değişmediğini doğrulayın. Bundan sonra göç, yeniden yazım değil bir yapılandırma değişikliğidir; bir sonraki göç de öyle olacaktır.

Hataları normalleştirmenin doğru yeri de bu bağdaştırıcıdır. Zaman aşımı, istek sınırı, kimlik doğrulama hatası ve boş sonuç birbirinden ayrı sonuçlar olarak çıkmalıdır. Eski entegrasyon bunların bazılarını boş bir listeye indirgiyorsa, ajanlarınız servis aslında arızalıyken hiçbir şeyin var olmadığını bildiriyor olabilir. Arayüzü sıfırdan tasarlıyorsanız web arama API'si nedir yazısı hareketli parçaları özetliyor.

Kendi trafiğinizle yan yana değerlendirin

1. Gerçek sorgulardan örneklem alın. Kayıtlarınızdan, uzun kuyruk ve İngilizce dışı sorgular dâhil her kullanım türünü kapsayan sorgular seçin.
2. Yeni sağlayıcıyı gölgede çalıştırın. Aynı sorguları ikisine birden gönderin, kullanıcılara eskisinden hizmet vermeye devam edin ve iki yanıtı da saklayın.
3. Önce mekanik karşılaştırma yapın: ilk sıralardaki adreslerin örtüşmesi, tarihlerin varlığı, özet uzunluğu, hata ve zaman aşımı oranları, kendi sunucularınızdan ölçülen yanıt süreleri.
4. Sonra bir örneklemi elle puanlayın; hangi listenin hangi sağlayıcıdan geldiğini bilmeden. Düşük örtüşme tek başına başarısızlık değildir; yeni sonuçlar daha iyi olabilir. Bunu ancak puanlama söyler.
5. Aşağı akıştaki davranışı sınayın. Sonuçları bir model kullanıyorsa aynı istemleri ikisiyle de çalıştırın ve yalnızca sonuç listelerini değil, yanıtları ve atıflarını da karşılaştırın.

Kabul ölçütünü veriler gelmeden önce yazın. Örneğin: puanlanan örneklemde yeni sağlayıcı her sorgu sınıfında en az eskisi kadar alakalıdır, sonuçların çoğunda kullanılabilir bir tarih döndürür ve hiçbir sınıfta hata ya da zaman aşımı kötüleşmez. Puanlamanın ayrıntıları için web aramayı kendi sorgularınızla değerlendirme ve kapsama ve doğruluğu değerlendirme rehberlerine bakın.

Güvenli geçiş yapın

• Her seferinde tek bir kullanımı taşıyın, en düşük riskliden başlayın: kullanıcıya dönük aramadan önce şirket içi araçlar ve toplu işler.
• Bir bayrak kullanın. Her kullanım yeni bir yayına gerek kalmadan geri dönebilsin; trafiği kademeli artırın.
• Doğru sinyalleri izleyin: boş sonuç oranı, hata oranı, yavaş kuyruktaki yanıt süresi, sorgusunu yeniden yazan kullanıcılar ve aramaya atıf yapan model yanıtlarının kalitesi.
• Eski sağlayıcıyı erişilebilir tutun. Yeni sağlayıcı, haftalık ve aylık işler dâhil trafiğinizin tam bir döngüsünden geçene kadar.
• Temizlik yapın: eski anahtarları iptal edin, eski koşulların silinmesini istediği önbellekteki sonuçları silin, dokümantasyonu ve işletim kılavuzlarını güncelleyin.

Yeni sağlayıcının kullanım koşullarını API başvuru belgesi kadar dikkatle okuyun. Saklama, gösterme ve eğitim kuralları farklıdır; eski sözleşmede izin verilen bir önbellek yenisinde yasak olabilir. Yeni sağlayıcının kendisini seçmek için web arama API'si seçme rehberiyle başlayın.

GoCux nerede durur

GoCux bir arama API'si değildir; dolayısıyla yerine geçecek bir aday da değildir. Ama bir göç, tam da bir ajanın yürütebileceği ve bir ekibin inceleyebilmesi gereken türden çok adımlı bir iştir. GoCux'ta bir iş emri olarak çerçevelendiğinde işin bir hedefi (haftalık haber özetini yeni sağlayıcıya taşımak), bir kapsamı (ilgisiz servisler değil, bağdaştırıcı ve yapılandırması) ve yukarıdakine benzer kabul ölçütleri olur. Her adım yürürken iş emrinin kaydına yazılır; dışarıya rapor göndermek ya da tekrarlanan bir iş zamanlamak gibi sonuç doğuran eylemlerden önce iş, ekipten biri karar verene kadar karar bekleyen durumda durur. Sonuç, kanıtı ve bu kararlar tek bir kayıtta durur; biri sonradan arama sonuçlarının neden değiştiğini sorduğunda istediğiniz de budur. Ölçütün neden önce geldiğini ajan başlamadan kabul ölçütlerini yazın notu açıklıyor; alanları da görev tanımlama rehberinde görebilirsiniz.

Göç kontrol listesi

• Her çağrı noktası, zamanlanmış iş ve dolaylı tüketici, okuduğu alanlarla birlikte envanterde.
• Sağlayıcıdan bağımsız bir sonuç biçimi var ve eski sağlayıcı bu biçime eşleniyor.
• Tarama tarihleri ve yayın tarihleri eşlemede ayrı duruyor.
• Pazar, güncellik, güvenli arama ve sayfalama davranışları ya eşlendi ya da bilerek bırakıldı.
• Bağdaştırıcı sonuç, boş, hata, zaman aşımı ve istek sınırı için ayrı sonuçlar döndürüyor.
• Gölge trafik, haftalık ve aylık işleri kapsayacak kadar uzun çalıştı.
• Kör puanlanan bir örneklem, önceden yazılmış bir kabul ölçütünü karşıladı.
• Her kullanım bir bayrakla geri dönebiliyor.
• Eski anahtarlar iptal edildi ve önbellekteki sonuçlar eski koşulların gerektirdiği biçimde ele alındı.