Adresleri yüksek hacimde işlemek için Adres Doğrulama API'sini kullanma

Hedef

Bir geliştirici olarak genellikle iyi kalitede olmayabilecek müşteri adreslerini içeren veri kümeleriyle çalışırsınız. Müşteri kimliği doğrulamasından teslimata kadar çeşitli kullanım alanları için adreslerin doğru olduğundan emin olmanız gerekir.

Address Validation API, bir adresi doğrulamak için kullanabileceğiniz Google Haritalar Platformu ürünüdür. Ancak aynı anda yalnızca bir adres işlenir. Bu belgede, yüksek hacimli adres doğrulamasının API testinden tek seferlik ve yinelenen adres doğrulamaya kadar farklı senaryolarda nasıl kullanılacağını ele alacağız.

Kullanım alanları

Şimdi Yüksek Hacimli Adres Doğrulama özelliğinin faydalı olduğu kullanım alanlarını inceleyelim.

Test

Adres Doğrulama API'sini sık sık binlerce adres çalıştırarak test etmek istersiniz. Adresler bir Virgülle Ayrılmış Değer dosyasında bulunuyor ve adreslerin kalitesini doğrulamak isteyebilirsiniz.

Adresleri tek seferlik doğrulama

Address Validation API'ye ilk katılım sırasında mevcut adres veritabanınızı kullanıcı veritabanına göre doğrulamak istiyorsunuz.

Adreslerin yinelenen doğrulaması

Çeşitli senaryolarda adreslerin tekrar tekrar doğrulanması gerekir:

• Gün içinde yakalanan ayrıntılar için (örneğin, müşteri kayıtları, sipariş ayrıntıları, teslimat programları) adresleri doğrulamak üzere planlanmış işleriniz olabilir.
• Örneğin, satıştan pazarlamaya kadar, farklı departmanların adreslerini içeren veri dökümleri alabilirsiniz. Adresleri alan yeni departman genellikle adresleri kullanmadan önce doğrulamak ister.
• Adresleri anketler veya çeşitli tanıtımlar sırasında toplayabilir ve daha sonra online sistemde güncelleyebilirsiniz. Sisteme girerek adreslerin doğru olduğunu onaylamak istiyorsunuz.

Ayrıntılı teknik inceleme

Bu belgenin amaçları doğrultusunda, aşağıdakilerin kabul edildiğini varsayarız:

• Address Validation API'yi bir müşteri veritabanındaki (ör. müşteri ayrıntılarını içeren bir veritabanı) adreslerle çağırıyorsunuz
• Geçerlilik işaretlerini veritabanınızdaki farklı adreslere göre önbelleğe alabilirsiniz.
• Geçerlilik işaretleri, bir müşteri giriş yaptığında Address Validation API'den alınır.

Hemen deneyin: Google Cloud Console'u ziyaret ederek Address Validation API'yi etkinleştirin.

Üretim kullanımı için önbelleğe alma

Not: Aşağıdaki bölümde açıklanan belirli yanıt öğeleri, art arda en fazla 30 takvim günü boyunca saklanabilir. 30 gün işaretinden sonra tüm bu yanıt öğelerinin silinmesi ZORUNLUDUR.

Address Validation API'yi kullanırken genellikle API çağrısından gelen yanıtın bir kısmını önbelleğe almak istersiniz. Hizmet Şartlarımız hangi verilerin önbelleğe alınabileceğini sınırlandırır. Ancak Address Validation API aracılığıyla önbelleğe alınabilecek tüm veriler, kullanıcı hesabında önbelleğe alınmalıdır. Bu, veritabanında adres veya adres meta verilerinin kullanıcının e-posta adresi ya da başka bir birincil kimliğe göre önbelleğe alınması gerektiği anlamına gelir.

Yüksek Hacimli Adres Doğrulama kullanım alanı için verileri önbelleğe almanın Bölüm 11.3'te açıklanan Address Validation API Hizmete Özel Şartları'na uyması gerekir. Bu bilgilere dayanarak, bir kullanıcının adresinin geçersiz olup olmadığını belirleyebilirsiniz. Bu durumda, uygulamanızla bir sonraki etkileşimi sırasında kullanıcıdan doğru adresi girmenizi istersiniz.

• AddressComponent nesnesinden alınan veriler
  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

Gerçek adresle ilgili herhangi bir bilgiyi önbelleğe almak istiyorsanız, bu veriler yalnızca kullanıcının izniyle önbelleğe alınmalıdır. Bu sayede kullanıcı, belirli bir hizmetin adresini neden sakladığını bilir ve adresini paylaşma açısından sorun yaşamaz.

Kullanıcı iznine örnek olarak, bir ödeme sayfasındaki e-ticaret adres formuyla doğrudan etkileşim verilebilir. Paket gönderiminde adresi önbelleğe alıp işleyeceğinize dair bir anlayış vardır.

Kullanıcının izniyle, yanıttaki formattedAddress ve diğer temel bileşenleri önbelleğe alabilirsiniz. Ancak, gözetimsiz bir senaryoda adres doğrulaması arka uçtan gerçekleştiği için kullanıcılar izin veremez. Dolayısıyla, bu gözetimsiz senaryoda çok sınırlı bilgileri önbelleğe alabilirsiniz.

Yanıtı anlama

Not: Yanıtı nasıl yorumlayacağınızı açıklayan Doğrulama mantığınızı oluşturma konulu harika bir kılavuz da bulunmaktadır.

Address Validation API yanıtı aşağıdaki işaretçileri içeriyorsa giriş adresinin teslimat kalitesinde olduğundan emin olabilirsiniz:

• Karar nesnesindeki addressComplete işaretçisi true ise
• Sonuç nesnesindeki validationGranularity PREMISE veya SUB_PREMISE ise
• AddressComponent öğelerinin hiçbiri şu şekilde işaretlenmez:
  • Inferred(Not: inferred=trueaddressComplete=true olduğunda gerçekleşebilir)
  • spellCorrected
  • replaced
  • unexpected ve
• confirmationLevel: AddressComponent'deki onay düzeyi CONFIRMEDveyaUNCONFIRMED_BUT_PLAUSIBLE olarak ayarlanmıştır

API yanıtı yukarıdaki işaretçileri içermiyorsa giriş adresi büyük olasılıkla düşük kalitededir. Bu durumu yansıtmak için veritabanınızda işaretleri önbelleğe alabilirsiniz. Önbelleğe alınan işaretler adresin bir bütün olarak düşük kaliteli olduğunu belirtirken, Yazım Düzeltildi gibi daha ayrıntılı işaretler, adres kalitesi sorununun belirli bir türünü belirtir. Müşterilerin, düşük kaliteli olarak işaretlenmiş bir adresle kurduğu bir sonraki etkileşimde, Adres Doğrulama API'sini mevcut adresle çağırabilirsiniz. Address Validation API, kullanıcı arayüzü istemi aracılığıyla görüntüleyebileceğiniz düzeltilmiş adresi döndürür. Müşteri, biçimlendirilmiş adresi kabul ettikten sonra yanıttan aşağıdakileri önbelleğe alabilirsiniz:

• formattedAddress
• postalAddress
• addressComponent componentNamesveya
• UspsData standardizedAddress

Gözetimsiz Adres doğrulaması uygulama

Not: Gözetimsiz kullanım nedir? Sunucu tarafında veya komut satırında yürütülen komut dosyası gibi, grafik kullanıcı arayüzü olmayan bir cihazda çalışabilen yazılım. Bu terimi, yazılımın GUI olmadan kullanıldığını açıklamak için kullanacağız.

Yukarıdaki tartışmaya göre:

• İşle ilgili nedenlerle, Address Validation API'den gelen yanıtın bir kısmını önbelleğe almak genellikle gerekir.
• Ancak Google Haritalar Platformu'ndaki Hizmet Şartları, hangi verilerin önbelleğe alınabileceğini kısıtlamaktadır.

Aşağıdaki bölümde, Hizmet Şartları'na uyma ve yüksek hacimli adres doğrulamasını uygulama ile ilgili iki adımlı bir süreci ele alacağız.

1. Adım:

İlk adımda, mevcut bir veri hattından yüksek hacimli adres doğrulama komut dosyasının nasıl uygulanacağını inceleyeceğiz. Bu işlem, Address Validation API yanıtındaki belirli alanları Hizmet Şartları'na uygun bir şekilde depolamanıza olanak tanır.

A diyagramı: Aşağıdaki şema, bir veri ardışık düzeninin Yüksek Hacimli Adres Doğrulama mantığıyla nasıl geliştirilebileceğini göstermektedir.

• Hizmet Şartları uyarınca , adresleri gözetimsiz bir şekilde doğrularken addressComplete, validationGranularity and validationFlags etiketini önbelleğe alabilirsiniz.

• addressComplete,validationGranularity and validationFlags, PlaceID veri kümesini müşteri veritabanındaki belirli bir UserID'ye göre önbelleğe alabilirsiniz.

Dolayısıyla, uygulamanın bu adımında yukarıda bahsedilen alanları UserID'ye göre önbelleğe alacağız.

Daha fazla bilgi için gerçek veri yapısı ile ilgili ayrıntıları inceleyin.

2. Adım:

1. adımda, giriş veri kümesindeki bazı adreslerin yüksek kalitede olmayabileceğine dair geri bildirim topladık. Bir sonraki adımda, bu işaretli adresleri alıp kullanıcıya sunacak ve kayıtlı adresin düzeltilmesi için kullanıcının iznini alacağız.

B diyagramı: Bu şema, kullanıcı izin akışının uçtan uca entegrasyonunun nasıl görünebileceğini gösterir:

1. Kullanıcı giriş yaptığında, öncelikle sisteminizde aşağıdakiler gibi doğrulama işaretlerini önbelleğe alıp almadığınızı kontrol edin:

   • addressComplete doğru
   • validationGranularity, PREMISE veya SUB_PREMISE değil
   • validationFlags, inferred,spellCorrected,replaced,unexpected anlamına geliyor.
     • Hiç işaret yoksa mevcut önbelleğe alınmış adresin iyi kalitede olduğuna dair güven düzeyi yüksektir ve bu adres kullanılabilir.

2. İşaretler varsa kullanıcıya adresini düzeltmesi/güncellemesi için bir kullanıcı arayüzü sunmanız gerekir.

3. Address Validation API'yi güncellenmiş veya önbelleğe alınmış adresle tekrar çağırabilir ve düzeltilmiş adresi onaylaması için kullanıcıya sunabilirsiniz.

4. Adres iyi kalitedeyse Address Validation API'si formattedAddress döndürür.

5. Düzeltme yapıldıysa bu adresi kullanıcıya sunabilir veya düzeltme yoksa sessizce kabul edebilirsiniz.

6. Kullanıcı kabul ettikten sonra formattedAddress öğesini veritabanında önbelleğe alabilirsiniz.

Not: Bu iş akışı tamamlandıktan sonra, önbelleğe alınan validationFlags silinir.

2. Adım'ı uygulayan sahte kod:

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

Sonuç

Yüksek Hacimli Adres Doğrulama, birçok uygulamada karşılaşabileceğiniz yaygın bir kullanım alanıdır. Bu belgede, Google Haritalar Platformu Hizmet Şartları'na uygun olarak bu tür bir çözümün nasıl uygulanacağına ilişkin bazı senaryolar ve tasarım kalıbı gösterilmiştir.

Ayrıca, GitHub'da açık kaynak kitaplık olarak Yüksek Hacimli Adres Doğrulama uygulamasının bir referans yöntemi de hazırladık. Yüksek Hacimli Adres Doğrulama ile hızlıca derlemeye başlamak için göz atın. Kitaplığın farklı senaryolarda nasıl kullanılacağına ilişkin tasarım kalıpları hakkındaki makaleyi de inceleyebilirsiniz.

Sonraki adımlar

Güvenilir adreslerle ödeme, teslimat ve işlemleri iyileştirme Teknik Belgesini indirin ve Adres Doğrulama ile ödeme, teslimat ve işlemleri iyileştirme web seminerini görüntüleyin.

Önerilen daha fazla bilgi:

• Yüksek Hacimli Adres Doğrulama Uygulamaları
• GitHub'da Python kitaplığı
• Adres Doğrulama demosunu inceleyin.

Katılımcılar

Bu makale Google tarafından saklanmaktadır. Mesajı ilk olarak aşağıdaki katkıda bulunanlar yazmış.
Baş yazarlar:

Henrik Valve | Çözüm Mühendisi
Thomas Anglaret | Çözüm Mühendisi
Sarthak Ganguly | Çözüm Mühendisi