Google Haritalar Platformu web hizmetleri, harita uygulamalarınız için coğrafi veriler sağlayan Google hizmetlerinin HTTP arayüzlerinden oluşan bir koleksiyondur.
Bu kılavuzda, web hizmeti isteklerinizi ayarlamak ve hizmet yanıtlarını işlemek için yararlı olan bazı yaygın uygulamalar açıklanmaktadır. Address Validation API'nin tüm belgeleri için geliştirici kılavuzunu inceleyin.
Web hizmeti nedir?
Google Haritalar Platformu web hizmetleri, harici hizmetlerden Maps API verilerini istemek ve bu verileri Haritalar uygulamalarınızda kullanmak için kullanılan bir arayüzdür. Bu hizmetler, Google Haritalar Platformu Hizmet Şartları'ndaki Lisans Kısıtlamaları uyarınca bir haritayla birlikte kullanılmak üzere tasarlanmıştır.
Haritalar API'leri web hizmetleri, belirli URL'lere yönelik HTTP(S) isteklerini kullanarak URL parametrelerini ve/veya JSON biçimindeki POST verilerini hizmetlere bağımsız değişken olarak iletir. Genel olarak bu hizmetler, uygulamanız tarafından ayrıştırma ve/veya işleme için yanıt gövdesinde JSON olarak veri döndürür.
ValidateAddress yöntemine HTTPPOST isteği göndererek bir adresi doğrulayın:
https://addressvalidation.googleapis.com/v1:validateAddress
Doğrulanacak adresi tanımlayan isteğe bir JSON gövdesi iletin.
Not: Tüm Address Validation API uygulamaları için kimlik doğrulama gerekir. Kimlik doğrulama kimlik bilgileri hakkında daha fazla bilgi edinin.
SSL/TLS Erişimi
HTTPS, API anahtarları kullanan veya kullanıcı verileri içeren tüm Google Haritalar Platformu istekleri için gereklidir. Hassas veri içeren ve HTTP üzerinden yapılan istekler reddedilebilir.
Geçerli bir URL oluşturma
"Geçerli" bir URL'nin kendiliğinden aşikar olduğunu düşünebilirsiniz, ancak bu doğru değildir. Örneğin, bir tarayıcıdaki adres çubuğuna girilen bir URL, özel karakterler (ör."上海+中國") içerebilir. Tarayıcının bu karakterleri iletilmeden önce dahili olarak farklı bir kodlamaya çevirmesi gerekir.
Aynı şekilde, UTF-8 girişini oluşturan veya kabul eden tüm kodlar UTF-8 karakterli URL'leri "geçerli" olarak değerlendirebilir ancak bu karakterleri bir web sunucusuna gönderilmeden önce çevirmesi de gerekir.
Bu işleme
URL kodlama veya yüzde kodlama denir.
Özel karakterler
Tüm URL'lerin Tek Tip Kaynak Tanımlayıcısı (URI) spesifikasyonunda belirtilen söz dizimine uyması gerektiğinden özel karakterleri çevirmemiz gerekir. Aslında bu, URL'lerin yalnızca ASCII karakterlerinin özel bir alt kümesini içermesi gerektiği anlamına gelir: Bilindik alfasayısal simgeler ve URL'lerde kontrol karakterleri olarak kullanılmak üzere ayrılmış bazı karakterler. Bu tabloda şu karakterler özetlenmektedir:
| Ayarla | karakter | URL kullanımı |
|---|---|---|
| Alfanümerik | n | Metin dizeleri, şema kullanımı (http), bağlantı noktası (8080) vb. |
| Ayrılmamış | - _ . ~ | Metin dizeleri |
| Rezervasyon yapıldı | ! * ' ( ) ; : @ & = + TL , / ? # [ ] yüzdesi | Karakterleri ve/veya Metin Dizelerini kontrol etme |
Geçerli bir URL oluştururken, yalnızca Geçerli URL Karakterleri Özeti tablosunda gösterilen karakterleri içerdiğinden emin olmalısınız. Bir URL'nin bu karakter grubunu kullanacak şekilde değiştirilmesi, genellikle biri eksiklik, diğeri değiştirme olmak üzere iki soruna yol açar:
- İşlemek istediğiniz karakterler yukarıdaki kümenin dışında var. Örneğin,
上海+中國gibi yabancı dillerdeki karakterler yukarıdaki karakterler kullanılarak kodlanmalıdır. Yaygın bir kural olarak, boşluklar (URL'lerde kullanılmasına izin verilmez) genellikle artı'+'karakteri kullanılarak da gösterilir. - Yukarıdaki karakterler, ayrılmış karakterler olarak ayarlanmış olsa da birbirlerinin yerine kullanılmaları gerekir.
Örneğin,
?parametresi URL'lerde sorgu dizesinin başlangıcını belirtmek için kullanılır. "? ve Gizemler" dizesini kullanmak isterseniz'?'karakterini kodlamanız gerekir.
URL kodlanacak tüm karakterler, bir '%' karakteri ve UTF-8 karakterine karşılık gelen iki karakterlik onaltılık değer kullanılarak kodlanır. Örneğin, UTF-8'de 上海+中國, %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B olarak URL olarak kodlanır. ? and the Mysterians dizesi, %3F+and+the+Mysterians veya %3F%20and%20the%20Mysterians olarak URL olarak kodlanır.
Kodlama gerektiren yaygın karakterler
Kodlanması gereken bazı yaygın karakterler şunlardır:
| Güvenli olmayan karakter | Kodlanmış değer |
|---|---|
| Boşluk | %20 |
| " | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
Kullanıcı girişinden aldığınız bir URL'yi dönüştürmek bazen zordur. Örneğin, bir kullanıcı "İstanbul Büyükdere Caddesi" olarak bir adres girebilir. Genel olarak, URL'nizi parçalarından oluşturmalısınız ve tüm kullanıcı girişlerini değişmez karakter olarak ele alın.
Ayrıca, tüm Google Haritalar Platformu web hizmetleri ve statik web API'leri için URL'ler 16.384 karakterle sınırlıdır. Çoğu hizmette bu karakter sınırına nadiren yaklaşılır. Ancak belirli hizmetlerde, uzun URL'lere neden olabilecek çeşitli parametreler bulunduğunu unutmayın.
Google API'lerinin Sonradan Kullanımı
Kötü tasarlanmış API istemcileri hem internet hem de Google sunucularına gerekenden daha fazla yük yükleyebilir. Bu bölümde, API müşterilerine yönelik bazı en iyi uygulamalar yer almaktadır. Bu en iyi uygulamaları izleyerek, API'lerin yanlışlıkla kötüye kullanılması nedeniyle uygulamanızın engellenmesini önleyebilirsiniz.
Üstel Geri Alma
Nadir durumlarda isteğinizi yerine getirirken bir şeyler ters gidebilir. 4XX veya 5XX HTTP yanıt kodu alabilirsiniz ya da TCP bağlantısı istemciniz ve Google'ın sunucusu arasındaki bir yerde başarısız olabilir. Takip isteği, orijinal istek başarısız olduğunda başarılı olabileceğinden genellikle isteği yeniden deneyebilirsiniz. Ancak Google'ın sunucularına sürekli olarak istek göndermekten kaçınmak önemlidir. Bu döngü davranışı, istemcinizle Google arasındaki ağı aşırı yükleyerek birçok taraf için sorunlara yol açabilir.
Denemeler arasında artan gecikmeleri azaltarak tekrar denemek daha iyi bir yaklaşımdır. Genellikle gecikme, her denemede üstel geri çekilme olarak bilinen bir yaklaşım olan çarpımsal bir faktörle artar.
Örneğin, bu isteği Time Zone API'ye yapmak isteyen bir uygulamayı düşünün:
https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510×tamp=1331161200&key=YOUR_API_KEY
Aşağıdaki Python örneğinde, eksponansiyel geri yükleme ile nasıl istekte bulunulacağı gösterilmektedir:
import json
import time
import urllib.error
import urllib.parse
import urllib.request
# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"
def timezone(lat, lng, timestamp):
# Join the parts of the URL together into one string.
params = urllib.parse.urlencode(
{"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
)
url = f"{TIMEZONE_BASE_URL}?{params}"
current_delay = 0.1 # Set the initial retry delay to 100ms.
max_delay = 5 # Set the maximum retry delay to 5 seconds.
while True:
try:
# Get the API response.
response = urllib.request.urlopen(url)
except urllib.error.URLError:
pass # Fall through to the retry loop.
else:
# If we didn't get an IOError then parse the result.
result = json.load(response)
if result["status"] == "OK":
return result["timeZoneId"]
elif result["status"] != "UNKNOWN_ERROR":
# Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
# ZERO_RESULTS. There is no point retrying these requests.
raise Exception(result["error_message"])
if current_delay > max_delay:
raise Exception("Too many retry attempts.")
print("Waiting", current_delay, "seconds before retrying.")
time.sleep(current_delay)
current_delay *= 2 # Increase the delay each time we retry.
if __name__ == "__main__":
tz = timezone(39.6034810, -119.6822510, 1331161200)
print(f"Timezone: {tz}")
Ayrıca, uygulama çağrı zincirinde hızlı bir şekilde art arda tekrarlanan isteklere yol açan daha üst düzey yeniden deneme kodu olmadığına da dikkat etmeniz gerekir.
Senkronize İstekler
Google'ın API'lerine yapılan çok sayıda senkronize istek, Google'ın altyapısına yönelik bir Dağıtılmış Hizmet Reddi (DDoS) saldırısı gibi görünebilir ve buna göre ele alınır. Bunu önlemek için API isteklerinin istemciler arasında senkronize edilmediğinden emin olun.
Örneğin, saati geçerli saat diliminde görüntüleyen bir uygulamayı ele alalım. Bu uygulama muhtemelen dakikanın başında istemci işletim sisteminde alarmı uyandırarak görüntülenen saatin güncellenebilmesini sağlar. Uygulama, o alarmla ilişkili işlemin parçası olarak herhangi bir API çağrısı yapmamalıdır.
Sabit bir alarma yanıt olarak API çağrıları yapmak, API çağrılarının farklı cihazlar arasında bile zaman içinde eşit olarak dağıtılmak yerine dakikanın başlangıcıyla senkronize edilmesine neden olduğu için kötü bir durumdur. Bunu yapan kötü tasarlanmış bir uygulama, her dakikanın başında trafikte normal seviyelerde altmış kat artışa neden olur.
Bunun yerine olası iyi tasarımlardan biri rastgele seçilen bir zamana ikinci bir alarm ayarlamaktır. Bu ikinci alarm etkinleştiğinde uygulama, ihtiyacı olan API'leri çağırır ve sonuçları depolar. Uygulama, dakikanın başında görüntüsünü güncellemek istediğinde API'yi tekrar çağırmak yerine önceden depolanan sonuçları kullanır. Bu yaklaşımda API çağrıları zamanla eşit şekilde yayılır. Ayrıca ekran güncellendiğinde API çağrıları oluşturma işlemini geciktirmez.
Dakikanın başlangıcından ayrı olarak, hedeflememeye dikkat etmeniz gereken diğer yaygın senkronizasyon zamanları bir saatin başında ve her günün başlangıcı gece yarısıdır.
Yanıtlar İşleniyor
Bu bölümde, bu değerlerin web hizmeti yanıtlarından dinamik olarak nasıl çıkarılacağı açıklanmaktadır.
Google Haritalar web hizmetleri, anlaşılması kolay ama kullanıcı dostu olmayan yanıtlar sunar. Bir sorgu gerçekleştirirken bir veri kümesini görüntülemek yerine muhtemelen belirli birkaç değeri ayıklamak istersiniz. Genellikle, web hizmetinden yanıtları ayrıştırmak ve yalnızca sizi ilgilendiren değerleri ayıklamak istersiniz.
Kullandığınız ayrıştırma şeması, çıktıyı JSON'da döndürüp döndürmediğinize bağlıdır. Halihazırda Javascript nesneleri biçiminde olan JSON yanıtları, istemcide JavaScript içinde işlenebilir.