Google Haritalar Platformu web hizmetleri, harita uygulamalarınız için coğrafi veriler sağlayan Google hizmetlerine yönelik HTTP arayüzleri koleksiyonudur.
Bu kılavuzda, web hizmeti isteklerinizi ayarlamak ve hizmet yanıtlarını işlemek için yararlanabileceğiniz bazı yaygın uygulamalar açıklanmaktadır. Aerial View API ile ilgili tüm belgeler için geliştirici kılavuzuna bakın.
Web hizmeti nedir?
Google Haritalar Platformu web hizmetleri, harici hizmetlerden Maps API verileri istemek ve Haritalar uygulamalarınızdaki verileri kullanmak için bir arayüzdür. Bu hizmetler, Google Haritalar Platformu Hizmet Şartları'ndaki Lisans Kısıtlamaları uyarınca bir haritayla birlikte kullanılacak şekilde tasarlanmıştır.
Maps API'leri web hizmetleri, belirli URL'lere gönderilen HTTP(S) isteklerini kullanarak URL parametrelerini ve/veya JSON biçimli POST verilerini hizmetlere bağımsız değişken olarak iletir. Genel olarak bu hizmetler, uygulamanız tarafından ayrıştırmak ve/veya işlemek için yanıt gövdesinde verileri JSON olarak döndürür.
lookupVideo yöntemine HTTP GET isteği göndererek mevcut bir havadan videoyu döndürün:
https://aerialview.googleapis.com/v1/videos:lookupVideo
Adresi veya video kimliğini belirtmek için isteğe sorgu parametreleri iletin.
Not: Tüm Aerial View API 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 gereklidir. HTTP üzerinden yapılan ve hassas veriler içeren istekler reddedilebilir.
Geçerli bir URL oluşturma
"Geçerli" bir URL'nin kendiliğinden açıkça ortaya çıktığını düşünebilirsiniz, ancak bu doğru değildir. Örneğin, bir tarayıcıda 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ı jetonla, UTF-8 girişi oluşturan veya kabul eden tüm kodlar UTF-8 karakterlerine sahip URL'leri "geçerli" olarak değerlendirebilir ancak bu karakterleri bir web sunucusuna göndermeden önce çevirmesi de gerekir.
Bu sürece
URL kodlaması veya yüzde kodlaması adı verilir.
Özel karakterler
Tüm URL'lerin Tek Tip Kaynak Tanımlayıcı (URI) spesifikasyonunda belirtilen söz dizimine uygun olması gerektiğinden özel karakterleri çevirmemiz gerekir. Bu, aslında URL'lerin ASCII karakterlerin yalnızca özel bir alt kümesini içermesi gerektiği anlamına gelir: bilinen 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 | a b c d e f g h i j k l m n o p q r s t u v g x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 | Metin dizeleri, şema kullanımı (http), bağlantı noktası (8080) vb. |
| Ayrılmamış | - _ . ~ | Metin dizeleri |
| Rezervasyon yapıldı | ! * ' ( ) ; : @ & = + TL , / ? % # [ ] | Kontrol karakterleri ve/veya Metin Dizeleri |
Geçerli bir URL oluştururken yalnızca tabloda gösterilen karakterleri içerdiğinden emin olmalısınız. Bu karakter grubunu kullanmak için bir URL oluşturmak, genellikle biri atlama, diğeri değiştirme olmak üzere iki soruna neden olur:
- İşlemek istediğiniz karakterler yukarıdaki grubun dışında bulunuyor. Örneğin, yabancı dillerdeki
上海+中國gibi karakterlerin yukarıdaki karakterler kullanılarak kodlanması gerekir. Popüler kurallara göre, boşluklar (URL'lerde izin verilmeyen alanlar) genellikle artı'+'karakteri kullanılarak gösterilir. - Yukarıdaki karakterler arasında ayrılmış karakterler olarak yer almaktadır ancak gerçek anlamda kullanılmaları gerekir.
Örneğin,
?, URL'lerde sorgu dizesinin başlangıcını belirtmek için kullanılır. "? ve Gizemler" dizesini kullanmak isterseniz'?'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 bir değer kullanılarak kodlanır. Örneğin, UTF-8'deki 上海+中國, %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.
Yaygın olarak kodlama gerektiren karakterler
Kodlanması gereken bazı yaygın karakterler şunlardır:
| Güvenli olmayan karakter | Kodlanmış değer |
|---|---|
| Alan | %20 |
| " | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
Kullanıcı girişinden aldığınız bir URL'yi dönüştürmek bazen karmaşık bir iştir. Örneğin, bir kullanıcı "5th&Main Street" olarak bir adres girebilir. Genel olarak, tüm kullanıcı girişlerini sabit karakterler olarak ele alarak, URL'nizi kendi bölümlerinden oluşturmanız gerekir.
Ayrıca URL'ler, tüm Google Haritalar Platformu web hizmetleri ve statik web API'leri için 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 olduğunu unutmayın.
Google API'lerinin Sonradan Kullanımı
Kötü tasarlanmış API istemcileri hem internette hem de Google'ın sunucularında gerekenden daha fazla yük taşıyabilir. Bu bölümde, API istemcileri için bazı en iyi uygulamalar yer almaktadır. Bu en iyi uygulamalardan yararlanmanız, uygulamanızın API'lerin yanlışlıkla kötüye kullanımı nedeniyle engellenmesini önlemenize yardımcı olabilir.
Üstel Geri Alma
Nadir durumlarda, isteğinizin yerine getirilmesi sırasında bir şeyler ters gidebilir. 4XX veya 5XX HTTP yanıt kodu alabilirsiniz ya da TCP bağlantısı istemciniz ile Google sunucusu arasında bir yerde başarısız olabilir. Takip isteği, orijinal istek başarısız olduğunda başarılı olabileceğinden genellikle yeniden denemek faydalı olur. Ancak Google'ın sunucularına sürekli olarak istek göndermekle yetinmemek de önemlidir. Bu döngüsel davranış, istemciniz ile Google arasındaki ağda aşırı yüklenerek birçok taraf için soruna neden olabilir.
Daha iyi bir yaklaşım, denemeler arasındaki gecikmeleri artırarak tekrar denemektir. Genellikle gecikme her denemede çarpma faktörüyle artırılır. Bu yaklaşım Üstel Geri Alma olarak bilinir.
Örneğin, Time Zone API'ye bu isteği göndermek isteyen bir uygulamayı ele alalım:
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 gönderileceği 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 arka arkaya tekrarlanan isteklere yol açan daha yüksek bir yeniden deneme kodu olmadığından da emin olmalısınız.
Senkronize İstekler
Google'ın API'lerine yapılan çok sayıda senkronize edilmiş istek, Google altyapısına yönelik Dağıtılmış Hizmet Reddi (DDoS) saldırısı gibi görünebilir ve gerekli şekilde ele alınabilir. Bundan kaçınmak için API isteklerinin istemciler arasında senkronize edilmediğinden emin olmanız gerekir.
Örneğin, saati geçerli saat diliminde gösteren bir uygulamayı ele alalım. Bu uygulama muhtemelen istemci işletim sisteminde alarm kurarak dakikanın başında uyandırır. Böylece, görüntülenen süre güncellenebilir. Uygulama, söz konusu alarmla ilişkili işlemin bir parçası olarak API çağrısı yapmamalıdır.
Sabit bir alarma yanıt olarak API çağrıları yapmak kötüdür, çünkü API çağrıları zaman içinde eşit olarak dağıtmak yerine, farklı cihazlar arasında bile dakikanın başında senkronize edilir. Bunu yapan kötü tasarlanmış bir uygulama, her dakikanın başında normal düzeylerde altmış kat artışa neden olur.
Bunun yerine, rastgele seçilen bir zamana ayarlanmış ikinci bir alarm olması olası iyi bir tasarımdır. Bu ikinci alarm etkinleştiğinde uygulama, ihtiyacı olan API'leri çağırır ve sonuçları depolar. Uygulama dakika başında ekranını güncellemek istediğinde, API'yi tekrar çağırmak yerine önceden depolanan sonuçları kullanır. Bu yaklaşımda, API çağrıları zaman içinde eşit olarak yayılır. Ayrıca API çağrıları, ekran güncellenirken oluşturmayı geciktirmez.
Dakikanın başlangıcı dışında, diğer yaygın senkronizasyon zamanlarını hedeflememenize dikkat etmeniz gerekir.
Yanıtlar İşleniyor
Bu bölümde, bu değerlerin web hizmeti yanıtlarından dinamik olarak nasıl ayıklanacağı anlatılmaktadır.
Google Haritalar web hizmetleri kolay anlaşılır ancak tam olarak kullanıcı dostu yanıtlar verir. Bir sorgu gerçekleştirirken, bir veri kümesi görüntülemek yerine muhtemelen birkaç belirli değeri ayıklamak istersiniz. Genel olarak, web hizmetinden gelen 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 biçiminde döndürüp döndürmediğinize bağlıdır. Zaten JavaScript nesneleri biçiminde olan JSON yanıtları, istemcide JavaScript'in kendi içinde işlenebilir.