Google Haritalar Platformu web hizmetleri, harita uygulamalarınız için coğrafi veriler sağlayan Google hizmetlerine yönelik bir HTTP arayüzleri koleksiyonudur.
Bu kılavuzda, web hizmeti isteklerinizi ayarlamak ve hizmet yanıtlarını işlemek için faydalı olan bazı yaygın uygulamalar açıklanmaktadır. Roads API'nin tüm belgeleri için geliştirici kılavuzunu inceleyin.
Web hizmeti nedir?
Google Haritalar Platformu web hizmetleri, harici hizmetlerden Maps API verileri 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 yapılan HTTP(S) isteklerini, URL parametrelerini ve/veya JSON biçimli POST verilerini hizmetlere bağımsız değişken olarak iletir. Genellikle bu hizmetler, verileri uygulamanız tarafından ayrıştırılmak ve/veya işlemek için yanıt gövdesinde JSON biçiminde döndürür.
Tipik bir Roads API web hizmeti isteği genellikle aşağıdaki biçimdedir:
https://roads.googleapis.com/v1/snapToRoads?parameters&key=YOUR_API_KEY
Burada snapToRoads, istenen hizmeti belirtir. Diğer Yol hizmetleri arasında nearestRoads ve speedLimits yer alır.
Not: Tüm Yollar API'si uygulamaları kimlik doğrulama gerektirir. 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 zorunludur. Hassas veriler içeren HTTP üzerinden yapılan istekler reddedilebilir.
Geçerli bir URL oluşturma
"Geçerli" bir URL'nin kendiliğinden görünür 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şlerini 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şlem,
URL kodlaması veya yüzde kodlaması olarak adlandırılır.
Ö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 özel bir ASCII karakterler 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 | karakterler | URL kullanımı |
|---|---|---|
| Alfanümerik | Metin dizeleri, şema kullanımı (http), bağlantı noktası (8080) vb. |
|
| Ayrılmamış | - _ . ~ | Metin dizeleri |
| Rezervasyon yapıldı | ! * ' ( ) ; : @ & = + ₺ , / ? % # [ ] | 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 olmanız gerekir. Bir URL'nin bu karakter kümesini kullanacak şekilde oluşturulması, genellikle biri eksiklik, diğeri değiştirme olmak üzere iki soruna yol açar:
- İşlemek istediğiniz karakterler yukarıdaki grubun dışında bulunuyor. Örneğin,
上海+中國gibi yabancı dillerdeki karakterler yukarıdaki karakterler kullanılarak kodlanmalıdır. Popüler bir kural olarak, boşluklar (URL'lerde kullanılmasına izin verilmez) genellikle artı'+'karakteri kullanılarak da temsil edilir. - Karakterler, yukarıdaki grupta ayrılmış karakterler olarak bulunur ancak birbirlerinin yerine kullanılmaları gerekir.
Örneğin,
?, URL'lerde sorgu dizesinin başlangıcını belirtmek için kullanılır. "? ve Gizemler" dizesini kullanmak istiyorsanız'?'karakterini kodlamanız gerekir.
URL olarak 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şlerinden aldığınız bir URL'yi dönüştürmek bazen zor bir iş olabilir. Örneğin, bir kullanıcı "5. ve Ana Cad." olarak bir adres girebilir. Genel olarak, URL'nizi parçalarından oluşturmalısınız ve tüm kullanıcı girişlerini harf karakterleri olarak işlemelisiniz.
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 bazı hizmetlerde, uzun URL'lere neden olabilecek birkaç parametre 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 istemcileri için bazı en iyi uygulamalar yer almaktadır. Bu en iyi uygulamaları izlemek, API'lerin yanlışlıkla kötüye kullanılması nedeniyle uygulamanızın engellenmesini önlemenize yardımcı olabilir.
Üstel Geri Alma
Nadir durumlarda isteğiniz yerine getirilirken bir şeyler ters gidebilir; 4XX veya 5XX HTTP yanıt kodu alabilirsiniz ya da istemcinizle Google'ın sunucusu arasındaki bir yerde TCP bağlantısı kesilebilir. Takip isteği, orijinal istek başarısız olduğunda başarılı olabileceğinden genellikle isteği yeniden denemek faydalı olur. Bununla birlikte, Google'ın sunucularına tekrar tekrar istek yapılmasını döngüye almak önemli değildir. 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 kullanarak tekrar denemek daha iyi bir yaklaşımdır. Gecikme, genellikle her denemede üstel Geri Yükleme olarak bilinen bir yaklaşım olan çarpımsal bir faktörle artar.
Örneğin, bu isteği Time Zone API'ye göndermek 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, isteğin eksponansiyel geri yüklemeyle nasıl yapılacağı 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 tekrarlanan isteklere yol açan daha üst düzey yeniden deneme kodları olmadığından da emin olmalısınız.
Senkronize İstekler
Google'ın API'lerine yapılan senkronize edilmiş çok sayıda istek, Google'ın altyapısına yönelik bir Dağıtılmış Hizmet Reddi (DDoS) saldırısı gibi görünebilir ve uygun şekilde ele alınır. Bunu önlemek için API isteklerinin istemciler arasında senkronize edilmediğinden emin olmanız gerekir.
Örneğin, saati geçerli saat diliminde görüntüleyen bir uygulamayı düşünün. Bu uygulama büyük olasılıkla, görüntülenen saatin güncellenebilmesi için istemcinin işletim sisteminde alarm ayarlanır ve dakikanın başında uyandırılır. Uygulama, söz konusu alarmla ilişkili işlemin parçası olarak 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ına kadar senkronize edilmesine neden olduğu için kötüdür. Bunu yapan kötü tasarlanmış bir uygulama, her dakikanın başında trafikte normal seviyelerden altmış kat artışa neden olur.
Bunun yerine olası iyi bir tasarım, 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şımla, API çağrıları zamanla eşit şekilde dağıtı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, hedeflemeye dikkat etmemeniz gereken diğer yaygın senkronizasyon zamanları da bir saatin başında ve her günün gece yarısında başlar.
Yanıtları İşleme
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ümesi görüntülemek yerine muhtemelen belirli birkaç değeri ayıklamak istersiniz. Genellikle, web hizmetinden yanıtları ayrıştırmak ve yalnızca ilginizi çeken değerleri ayıklamak istersiniz.
Kullandığınız ayrıştırma şeması, JSON'de çıkış döndürüp döndürmediğinize bağlıdır. Halihazırda Javascript nesnesi biçiminde olan JSON yanıtları, istemcide JavaScript içinde işlenebilir.