Roads API Web Hizmetlerini Kullanmayla İlgili En İyi Uygulamalar

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 hizmetinizin isteklerini ayarlamak ve hizmet yanıtlarını işlemek için faydalı olabilecek bazı yaygın uygulamalar açıklanmaktadır. Roads API'nin tam dokümanları için geliştirici kılavuzuna bakın.

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 harita ile birlikte kullanılmak üzere tasarlanmıştır.

Maps API'lerin 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. Bu hizmetler genellikle, uygulamanız tarafından ayrıştırılması ve/veya işlenmesi için yanıt gövdesinde verileri JSON olarak 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 belirli hizmeti gösterir. Diğer yol hizmetleri arasında nearestRoads ve speedLimits yer alır.

Not: Tüm Roads API uygulamaları için kimlik doğrulama gerekir. Kimlik doğrulama kimlik bilgileri hakkında daha fazla bilgi edinin.

SSL/TLS Erişimi

API anahtarları kullanan veya kullanıcı verileri içeren tüm Google Haritalar Platformu isteklerinde HTTPS gereklidir. HTTP üzerinden yapılan ve hassas veriler içeren istekler reddedilebilir.

Geçerli bir URL oluşturma

"Geçerli" bir URL'nin ne olduğunu anlamak kolay gibi görünse de durum tam olarak böyle değil. Örneğin, bir tarayıcıdaki adres çubuğuna girilen bir URL özel karakterler (ör."上海+中國") içerebilir. Tarayıcının, bu karakterleri iletmeden önce dahili olarak farklı bir kodlamaya çevirmesi gerekir. Aynı şekilde, UTF-8 girişi oluşturan veya kabul eden herhangi bir kod, UTF-8 karakterleri içeren URL'leri "geçerli" olarak değerlendirebilir ancak bu karakterleri bir web sunucusuna göndermeden önce çevirmesi de gerekir. Bu işleme URL kodlama veya yüzde kodlama denir.

Özel karakterler

Tüm URL'lerin Tekdüzen Kaynak Tanımlayıcı (URI) spesifikasyonu tarafından belirtilen söz dizimi kurallarına uyması gerektiğinden özel karakterleri çevirmemiz gerekir. Bu, URL'lerin yalnızca ASCII karakterlerinin özel bir alt kümesini içermesi gerektiği anlamına gelir: Bilinen alfanümerik semboller ve URL'lerde kontrol karakteri olarak kullanılmak üzere ayrılmış bazı karakterler. Bu tabloda bu karakterler özetlenmiştir:

Hazır	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'nin bu karakter grubunu kullanacak şekilde düzenlenmesi genellikle iki soruna yol açar: biri atlama, diğeri de değiştirme.

• İşlemek istediğiniz karakterler yukarıdaki grubun dışındaysa Örneğin, 上海+中國 gibi yabancı dillerdeki karakterlerin yukarıdaki karakterler kullanılarak kodlanması gerekir. Yaygın bir kurala göre, boşluklar (URL'lerde izin verilmez) genellikle artı '+' karakteri kullanılarak da temsil edilir.
• Yukarıdaki kümede ayrılmış karakterler olarak bulunan karakterlerin, 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 bir 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, URL kodlamalı olarak %3F+and+the+Mysterians veya %3F%20and%20the%20Mysterians şeklinde 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ı "5. Cadde&Ana Cadde" şeklinde bir adres girebilir. Genel olarak, URL'nizi parçalarından oluşturmalı ve tüm kullanıcı girişlerini gerçek karakterler olarak değerlendirmelisiniz.

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ı 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 istemcileri için bazı en iyi uygulamalar yer almaktadır. Bu en iyi uygulamalardan yararlanmak, 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ğinizin sunumu sırasında bir sorun yaşanabilir. 4XX veya 5XX HTTP yanıt kodu alabilir ya da TCP bağlantısı istemciniz ile Google'ın sunucusu arasında bir noktada başarısız olabilir. Orijinal istek başarısız olduğunda takip isteği başarılı olabileceğinden isteği tekrar denemek genellikle faydalıdır. Ancak, Google'ın sunucularına tekrar tekrar istek göndermek yerine, bu işlemi döngü içinde yapmamak önemlidir. Bu döngü davranışı, istemciniz ile Google arasındaki ağı aşırı yükleyebilir ve birçok taraf için soruna neden olabilir.

Daha iyi bir yaklaşım, denemeler arasında artan gecikmelerle yeniden denemektir. Genellikle gecikme, her denemeyle birlikte çarpma faktörü kadar artırılır. Bu yaklaşıma eksponansiyel geri yükleme adı verilir.

Örneğin, Time Zone API'ye şu isteği göndermek isteyen bir uygulamayı düşünün:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

Aşağıdaki Python örneğinde, isteğin üstel geri çekme ile 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ı zincirinin üst kısmında, hızlı bir şekilde art arda tekrarlanan isteklere neden olan bir yeniden deneme kodu olmadığından emin olmanız gerekir.

Senkronize İstekler

Google'ın API'lerine gönderilen ç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ınabilir. 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ı düşünün. Bu uygulama, gösterilen zamanın güncellenebilmesi için istemci işletim sisteminde dakikanın başında istemciyi uyandıran bir alarm ayarlayabilir. Uygulama, bu alarmla ilişkili işlem kapsamında 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ının zaman içinde eşit olarak dağıtılması yerine farklı cihazlar arasında bile dakikanın başlangıcıyla senkronize edilmesine neden olur. Kötü tasarlanmış bir uygulama, her dakikanın başında normal seviyelerin altmış katı kadar trafik sıçraması oluşturur.

Bunun yerine, rastgele seçilen bir saate ayarlanmış ikinci bir alarmın olması iyi bir tasarım olabilir. Bu ikinci alarm tetiklendiğinde uygulama, ihtiyaç duyduğu tüm 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 önceden depolanmış sonuçları kullanır. Bu yaklaşımda API çağrıları zaman içinde eşit şekilde dağıtılır. Ayrıca, API çağrıları ekran güncellenirken oluşturmayı geciktirmez.

Dakikanın başlangıcı dışında, senkronizasyonu hedeflememeniz gereken diğer yaygın zaman aralıkları, bir saatin başlangıcı ve her günün başlangıcı olan gece yarısıdır.

Yanıtları işleme

Not: Web hizmeti isteği içeren bağımsız yanıtların tam biçimi garanti edilmediğinden (bazı öğeler eksik veya birden fazla yerde olabilir) belirli bir yanıt için döndürülen biçimin farklı sorgular için aynı olacağını asla varsaymayın. Bunun yerine, yanıtı işlemeli ve ifadeler aracılığıyla uygun değerleri seçmelisiniz.

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ümesini görüntülemek yerine, muhtemelen birkaç belirli değeri ayıklamak istersiniz. 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ı, çıkışı JSON biçiminde döndürüp döndürmediğinize bağlıdır. JSON yanıtları zaten JavaScript nesnesi biçiminde olduğundan istemcide JavaScript'in kendisinde işlenebilir.