Route Optimization API Web Hizmetlerini Kullanan En İyi Uygulamalar

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şleme koymak için yararlanabileceğiniz bazı yaygın uygulamalar açıklanmaktadır. Route Optimization 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 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ılacak şekilde tasarlanmıştır.

Haritalar API'leri web hizmetleri, belirli URL'lere yönelik HTTP(S) isteklerini kullanarak, URL parametrelerini ve/veya JSON biçimli POST verilerini hizmetlere bağımsız değişken olarak iletir. Genellikle bu hizmetler, verileri uygulamanızın ayrıştırılması ve/veya işlenmesi için yanıt gövdesine JSON biçiminde döndürür.

Aşağıdaki örnekte optimizeTours yöntemine gönderilen REST POST isteğinin URL'si gösterilmektedir:

https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER:optimizeTours

PROJECT_NUMBER kısmını, Route Optimization API'nin etkinleştirildiği Cloud projesinin numarası veya kimliğiyle değiştirin.

OptimizeToursRequest iletinizi JSON istek gövdesi olarak ekleyin.

Not: Tüm Route Optimization API uygulamaları kimlik doğrulama gerektirir. 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 istekleri için HTTPS gereklidir. HTTP üzerinden yapılan ve hassas veri içeren istekler reddedilebilir.

Geçerli bir URL oluşturma

"Geçerli" bir URL'nin kolayca anlaşılabileceğini 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. İletim öncesinde tarayıcının bu karakterleri dahili olarak farklı bir kodlamaya çevirmesi gerekir. Aynı jetonla, 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 bu karakterleri web sunucusuna gönderilmeden önce de çevirmeleri gerekir. Bu sürece URL kodlaması veya yüzde kodlaması denir.

Dikkat: Tarayıcılar ve/veya hizmetler, bir istek URI'sını göndermeden önce otomatik olarak URL kodlaması yapabilir. Şifreleme isteği imzalama kullanan API'lerde, URL kodlaması imzalandıktan sonra isteği değiştirirse bu durum imzayı potansiyel olarak geçersiz kılabilir. Bu sorunu önlemek için isteği imzalamadan önce sorgu dizenizi her zaman URL olarak kodlayın.

Özel karakterler

Tüm URL'lerin Birörnek Kaynak Tanımlayıcısı (URI) spesifikasyonunda belirtilen söz dizimine uyması gerektiği için özel karakterleri çevirmemiz gerekir. Gerçekte bu, URL'lerin yalnızca ASCII karakterlerin yalnızca ö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	karakterler	URL kullanımı
Alfanümerik		Metin dizeleri, şema kullanımı (http), bağlantı noktası (8080) vb.
Ayrılmamış	- _ . ~	Metin dizeleri
Rezervasyon yapıldı	! * ' ( ) ; : @ & = + TL , / ? # [ ] yüzdesi	Kontrol karakterleri ve/veya Metin Dizeleri

Geçerli bir URL oluştururken, bu URL'nin yalnızca Geçerli URL Karakterleri Özeti tablosunda gösterilen karakterleri içerdiğinden emin olmanız gerekir. Bir URL'nin bu karakter grubunu kullanacak şekilde oluşturulması, genellikle biri eksiklik, diğeri yer değiştirme olmak üzere iki soruna yol açar:

• İşlemek istediğiniz karakterler yukarıdaki kümenin dışında mevcut. Örneğin, 上海+中國 gibi yabancı dillerdeki karakterlerin yukarıdaki karakterler kullanılarak kodlanması gerekir. Popüler bir kural olarak, boşluklar (URL'lerin içinde kullanılmasına izin verilmez) de çoğu zaman artı '+' karakteri kullanılarak temsil edilir.
• Karakterler, yukarıdaki ayrılmış karakterler olarak mevcuttur ancak bire bir kullanılmaları gerekir. Örneğin, ?, sorgu dizesinin başlangıcını belirtmek için URL'lerin içinde 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 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.

Yaygın olarak kullanılan ve 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 zor bir iş olabilir. Örneğin, bir kullanıcı "5th&Main St" olarak bir adres girebilir. Genel olarak, URL'nizi parçalarından oluşturmanız ve tüm kullanıcı girişlerini gerçek karakterler olarak ele almanız gerekir.

Ayrıca, tüm Google Haritalar Platformu web hizmetleri ve statik web API'leri için URL'ler 16.384 karakterle sınırlandırılmıştır. Çoğu hizmette bu karakter sınırına nadiren yaklaşılır. Ancak belirli 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 uygulamalardan yararlanarak, uygulamanızın API'lerin yanlışlıkla kötüye kullanımı nedeniyle engellenmesini önleyebilirsiniz.

Üstel Geri Alma

Nadir durumlarda isteğiniz yerine getirilirken bir şeyler ters gidebilir. 4XX veya 5XX HTTP yanıt kodu alabilirsiniz ya da TCP bağlantısı istemciniz ile Google'ın sunucusu arasında bir yerde kesilebilir. Takip isteği, orijinal istek başarısız olduğunda da başarılı olabileceği için genellikle isteği yeniden denemekte fayda vardır. Bununla birlikte, Google'ın sunucularına sürekli olarak yapılan istekleri döngüsel olarak yapmak önemli değildir. Bu döngü davranışı, istemcinizle Google arasındaki ağın aşırı yüklenmesine neden olarak birçok taraf için sorunlara yol açabilir.

Bu noktada, denemeler arasında artan gecikmeleri göstererek yeniden denemek daha iyi bir yaklaşımdır. Gecikme genellikle her denemede çarpma faktörü tarafından artırılır. Bu yönteme Üstel Geri Alma adı verilir.

Örneğin, Time Zone API'ye bu istekte bulunmak 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ği, isteğin eksponansiyel geri yüklemeyle nasıl yapılacağını gösterir:

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}")

Uygulama çağrı zincirinde, hızlı bir şekilde tekrarlanan isteklere yol açan yeniden deneme kodunun daha yukarıda bulunmadığından da dikkatli olmanız 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 uygun şekilde 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 uygulama düşünün. Bu uygulama büyük olasılıkla dakikanın başında istemci işletim sisteminde alarmı uyandırarak görüntülenen saatin güncellenebilmesini sağlar. Uygulama, bu alarmla ilişkilendirilen 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 kötüdür. 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 olur. 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 bir tasarım, rastgele seçilen bir zamana ikinci bir alarm ayarlamaktır. Bu ikinci alarm etkinleştiğinde uygulama, ihtiyaç duyduğu 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üncellenirken API çağrıları, oluşturma işlemini geciktirmez.

Dakikanın başlangıcı dışında, hedeflememeye dikkat etmeniz gereken diğer yaygın senkronizasyon zamanları da bir saatin başlangıcında ve her günün gece yarısında başlangıcıdır.

Yanıtları İşleme

Not: Web hizmeti isteği içeren her bir yanıtın tam biçimi garanti edilmediğinden (bazı öğeler eksik veya birden çok konumda olabilir) belirli bir yanıt için döndürülen biçimin farklı sorgularda aynı olacağını asla varsaymamalısınız. Bunun yerine yanıtı işlemeniz ve ifadeler aracılığıyla uygun değerleri seçmeniz gerekir.

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 olmakla birlikte tam olarak kullanıcı dostu olmayan yanıtlar sunar. Bir veri kümesini görüntülemek yerine sorgu gerçekleştirirken muhtemelen birkaç belirli 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'da çıkış döndürüp döndürmediğinize bağlıdır. Zaten Javascript nesnesi biçiminde olan JSON yanıtları, istemcide JavaScript içinde işlenebilir.