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. Map Management API'nin tüm belgeleri için geliştirici kılavuzuna bakın.
Web hizmeti nedir?
Google Haritalar Platformu web hizmetleri, harici hizmetlerden Maps API verilerini istemek ve bu verileri Haritalar uygulamalarınızda 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ılmak üzere tasarlanmıştır.
Maps API'leri web hizmetleri, belirli URL'lere HTTP(S) istekleri göndererek URL parametrelerini ve/veya JSON biçimli POST verilerini hizmetlere bağımsız değişken olarak iletir. Genellikle bu hizmetler, uygulamanız tarafından ayrıştırılmak ve/veya işlenmek üzere yanıt gövdesinde JSON olarak veri döndürür.
Aşağıdaki örnekte, list Map Configs yöntemine yönelik bir RESTGET isteği gösterilmektedir:
https://mapmanagement.googleapis.com/v2beta/projects/PROJECT_NUMBER_OR_ID/mapConfigs
İsteğinize Authorization header bölümünde OAuth jetonu ekleyin.
SSL/TLS Erişimi
API anahtarlarının kullanıldığı veya kullanıcı verilerinin yer aldığı tüm Google Haritalar Platformu istekleri için HTTPS gereklidir. Hassas veriler içeren HTTP üzerinden yapılan istekler reddedilebilir.
Geçerli bir URL oluşturma
"Geçerli" bir URL'nin ne anlama geldiği açıkça anlaşılıyor gibi görünse de durum tam olarak böyle 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 iletimden önce farklı bir kodlamaya çevirmesi gerekir.
Aynı şekilde, UTF-8 girişi oluşturan veya kabul eden tüm kodlar, UTF-8 karakterleri içeren URL'leri "geçerli" olarak değerlendirebilir ancak bunları bir web sunucusuna göndermeden önce çevirmesi gerekir.
Bu işleme
URL kodlama veya yüzde kodlama denir.
Özel karakterler
Tüm URL'lerin Tekdüzen Kaynak Tanımlayıcı (URI) spesifikasyonunda belirtilen söz dizimine uyması gerektiğinden özel karakterleri çevirmemiz gerekir. Bu nedenle, URL'ler yalnızca ASCII karakterlerinin özel bir alt kümesini içermelidir: tanıdık alfanümerik semboller ve URL'lerde kontrol karakterleri olarak kullanılmak üzere ayrılmış bazı karakterler. Bu karakterler aşağıdaki tabloda özetlenmiştir:
| Ayarlandı | 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 w 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 7 8 9 | Metin dizeleri, şema kullanımı (http), bağlantı noktası (8080) vb. |
| Ayrılmamış | - _ . ~ | Metin dizeleri |
| Rezervasyon yapıldı | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Kontrol karakterleri ve/veya metin dizeleri |
Geçerli bir URL oluştururken yalnızca tabloda gösterilen karakterleri içerdiğinden emin olmanız gerekir. Bir URL'yi bu karakter kümesini kullanacak şekilde uyarlamak genellikle iki soruna yol açar: biri eksiklik, diğeri ise değiştirme.
- İşlemek istediğiniz karakterler yukarıdaki kümenin dışında yer alıyor. Örneğin,
上海+中國gibi yabancı dillerdeki karakterlerin yukarıdaki karakterler kullanılarak kodlanması gerekir. Yaygın olarak kabul edilen kurala göre, URL'lerde izin verilmeyen boşluklar genellikle artı'+'karakteriyle de gösterilir. - Yukarıdaki kümede ayrılmış karakterler bulunur ancak bunların olduğu gibi kullanılması gerekir.
Örneğin,
?, sorgu dizesinin başlangıcını belirtmek için URL'lerde kullanılır. "? and the Mysterions" dizesini kullanmak istiyorsanız?karakterini kodlamanız gerekir.'?'
URL kodlaması yapılacak tüm karakterler, '%' karakteri ve UTF-8 karakterlerine karşılık gelen iki karakterli onaltılık değer kullanılarak kodlanır. Örneğin, UTF-8'deki 上海+中國, URL olarak %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B şeklinde kodlanır. ? and the Mysterians dizesi, %3F+and+the+Mysterians veya %3F%20and%20the%20Mysterians olarak URL kodlamalı olur.
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 zor olabilir. Örneğin, bir kullanıcı adresi "5th&Main St." olarak girebilir. Genel olarak, URL'nizi parçalarından oluşturmalı ve kullanıcı girişlerini değişmez karakterler olarak ele almalısınız.
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 hizmetlerin uzun URL'lere neden olabilecek çeşitli parametreleri olduğunu unutmayın.
Google API'lerinin Uygun Kullanımı
Kötü tasarlanmış API istemcileri hem internete hem de Google'ın sunucularına gereğinden fazla yük bindirebilir. Bu bölümde, API'lerin istemcileri için bazı en iyi uygulamalar yer almaktadır. Bu en iyi uygulamaları izleyerek uygulamanızın API'lerin yanlışlıkla kötüye kullanılması nedeniyle engellenmesini önleyebilirsiniz.
Üstel Geri Alma
Nadir durumlarda isteğinizin sunulmasıyla ilgili bir sorun oluşabilir. Bu durumda 4XX veya 5XX HTTP yanıt kodu alabilir ya da TCP bağlantısı, istemciniz ile Google'ın sunucusu arasında bir yerde başarısız olabilir. İlk istek başarısız olduğunda takip isteği başarılı olabileceğinden, isteği yeniden denemek genellikle faydalıdır. Ancak Google'ın sunucularına tekrar tekrar istekte bulunmamak önemlidir. Bu döngü davranışı, istemciniz ile Google arasındaki ağı aşırı yükleyerek birçok taraf için sorunlara neden olabilir.
Daha iyi bir yaklaşım, denemeler arasındaki gecikmeleri artırarak yeniden denemektir. Genellikle gecikme, her denemede çarpımsal bir faktörle artırılır. Bu yaklaşım eksponansiyel geri çekilme olarak bilinir.
Örneğin, Time Zone API'ye şu 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_KEYAşağıdaki Python örneğinde, eksponansiyel geri yükleme ile isteğin 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ısı zincirinde daha yüksek bir yeniden deneme kodu olmadığından emin olmalısınız. Bu kod, hızlı bir şekilde tekrarlanan isteklere yol açar.
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 işlem görebilir. Bunu önlemek 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, görüntülenen saatin güncellenebilmesi için istemci işletim sisteminde dakikanın başında sistemi uyandıran bir alarm ayarlayabilir. Uygulama, bu alarm ile ilişkili işlem kapsamında 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 zaman içinde eşit olarak dağıtılması yerine farklı cihazlar arasında bile dakikanın başlangıcına senkronize edilmesine neden olduğundan kötü bir uygulamadır. Bunu yapan kötü tasarlanmış bir uygulama, her dakikanın başında normal seviyenin altmış katı kadar trafik artışına neden olur.
Bunun yerine, rastgele seçilmiş bir zamanda çalacak ikinci bir alarm ayarlamak iyi bir tasarım olabilir. Bu ikinci alarm tetiklendiğinde uygulama, ihtiyaç duyduğu API'leri çağırır ve sonuçları depolar. Uygulama, dakikanın başında ekranını güncellemek istediğinde API'yi tekrar çağırmak yerine daha önce depolanmış sonuçları kullanır. Bu yaklaşımla API çağrıları zaman içinde eşit olarak dağıtılır. Ayrıca, API çağrıları, ekran güncellenirken oluşturmayı geciktirmez.
Dakikanın başlangıcı dışında, hedeflememeye dikkat etmeniz gereken diğer yaygın senkronizasyon zamanları arasında saatin başlangıcı ve her gün gece yarısı başlangıcı yer alır.
Yanıtları iş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 ancak tam olarak kullanıcı dostu olmayan yanıtlar sağlar. Sorgu yaparken bir veri kümesi görüntülemek yerine belirli birkaç değeri çıkarmak isteyebilirsiniz. Genellikle, web hizmetinden gelen yanıtları ayrıştırmak ve yalnızca ilgilendiğiniz değerleri ayıklamak istersiniz.
Kullandığınız ayrıştırma şeması, JSON biçiminde çıkış döndürüp döndürmediğinize bağlıdır. Zaten JavaScript nesneleri biçiminde olan JSON yanıtları, istemcide doğrudan JavaScript içinde işlenebilir.