Street View Static API'yi kullanmayla ilgili en iyi uygulamalar

Bir HTTP arayüzleri koleksiyonu olan Google Haritalar Platformu statik web API'leri, doğrudan web sayfanıza yerleştirilecek resimler oluşturur.

Google Haritalar Platformu web hizmetleri, harita uygulamalarınız için coğrafi veriler sağlayan bir HTTP arayüzleri koleksiyonudur.

Bu kılavuzda, resim ve web hizmeti isteklerinizi ayarlarken ve hizmet yanıtlarını işlerken faydalı olan bazı yaygın uygulamalar açıklanmaktadır. Street View Static API hakkında daha fazla bilgi için geliştirici kılavuzuna bakın.

Street View Static API, statik bir web API'si gibi davranırken meta veri hizmeti bir web hizmeti gibi davranır. Meta veri hizmeti hakkında daha fazla bilgi için Street View görüntü meta verileri başlıklı makaleyi inceleyin.

Statik web API'si nedir?

Google Haritalar Platformu statik web API'leri, JavaScript veya herhangi bir dinamik sayfa yüklemesi gerektirmeden web sayfanıza bir Google Haritalar resmi yerleştirmenize olanak tanır. Statik web API'leri, standart bir HTTPS isteği kullanılarak gönderilen URL parametrelerine dayalı bir resim oluşturur.

Tipik bir Street View Static API isteği aşağıdaki biçime sahiptir:

  https://www.googleapis.com/streetview/z/x/y?parameters

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.

Haritalar API'leri web hizmetleri, belirli URL'lere HTTP veya HTTPS istekleri göndererek URL parametrelerini ya da 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 veya işlenmek üzere yanıt gövdesinde JSON olarak veri döndürür.

Street View Static API meta veri isteği aşağıdaki biçimdedir:

https://maps.googleapis.com/maps/api/streetview/parameters

SSL ve TLS erişimi

API anahtarlarının kullanıldığı veya kullanıcı verilerinin bulunduğu tüm Google Haritalar Platformu istekleri için 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 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 bu karakterleri bir web sunucusuna göndermeden önce çevirmesi gerekir. Bu işleme URL kodlama veya yüzde kodlama adı verilir.

Ö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, URL'lerin yalnızca ASCII karakterlerinin özel bir alt kümesini içermesi gerektiği anlamına gelir: tanıdık alfanümerik semboller ve URL'lerde kontrol karakteri olarak kullanılmak üzere ayrılmış bazı karakterler. Bu karakterler aşağıdaki tabloda özetlenmiştir:

Geçerli bir URL oluştururken yalnızca tabloda gösterilen karakterleri içerdiğinden emin olmanız gerekir. Bir URL'nin bu karakter kümesini kullanacak şekilde uyarlanması 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, yabancı dillerdeki 上海+中國 gibi karakterlerin yukarıdaki karakterler kullanılarak kodlanması gerekir. Yaygın bir uygulamaya 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, ?, URL'lerde sorgu dizesinin başlangıcını belirtmek için 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'de URL olarak kodlanmış şekilde %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B olur. ? and the Mysterians dizesi, %3F+and+the+Mysterians veya %3F%20and%20the%20Mysterians olarak URL kodlamalı olur.

Kodlanması gereken yaygın karakterler

Kodlanması gereken bazı yaygın karakterler şunlardır:

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 şekilde kullanımı

Kötü tasarlanmış API istemcileri, internete ve sunuculara ağır yükler bindirebilir. Bu bölümde, API istemcileriyle ilgili en iyi uygulamalar yer almaktadır. Bu en iyi uygulamaları izlemek, uygulamanızın API'lerin yanlışlıkla kötüye kullanılması nedeniyle engellenmesini önlemeye yardımcı olabilir.

Eksponansiyel geri yükleme

Nadir durumlarda isteğinizle ilgili 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 yerde başarısız olabilir. Genellikle, ilk istek başarısız olduğunda takip eden istek başarılı olabileceğinden isteği yeniden denemek faydalı olur. Ancak Google'ın sunucularına tekrar tekrar istek göndermemeniz ö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. Gecikme genellikle her denemede çarpımsal bir faktörle artar. Bu yaklaşım, eksponansiyel geri yükleme olarak bilinir.

Örneğin, Time Zone API'ye şu isteği gönderen bir uygulamayı ele alalım:

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, üstel geri çekilme 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 in the following code 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 the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry 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 on each retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Uygulama çağrısı zincirinde, hızlı bir şekilde tekrarlanan isteklere yol açan daha yüksek bir yeniden deneme kodu olmadığından emin olun.

Senkronize edilmiş istekler

Google'ın API'lerine yapılan çok sayıda senkronize istek, Google'ın altyapısına yönelik dağıtılmış hizmet reddi (DDoS) saldırısı gibi görünebilir ve buna göre işlem görebilir. Bu sorunu önlemek için API isteklerinin istemciler arasında senkronize edilmediğinden emin olun.

Örneğin, geçerli saat dilimindeki saati gösteren bir uygulamayı ele alalım. Bu uygulama, gösterilen saatin güncellenebilmesi için istemci işletim sisteminde dakikanın başında uyandırmak üzere bir alarm ayarlıyor olabilir. Uygulamada, bu alarm ile ilişkili işleme kapsamında herhangi bir API çağrısı yapmayın.

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ılmak yerine farklı cihazlar arasında bile dakikanın başlangıcına senkronize edilmesiyle sonuçlandığı için kötü bir uygulamadır. Bunu yapan kötü tasarlanmış bir uygulama, her dakikanın başında normal seviyelerin 60 katı kadar trafik artışına neden olur.

Bunun yerine, uygulamayı rastgele seçilmiş bir zamanda ikinci bir alarm çalacak şekilde tasarlayabilirsiniz. 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üncellerken 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üncellendiğinde oluşturmayı geciktirmez.

Dakikanın başlangıcı dışında, diğer yaygın senkronizasyon zamanlarını (ör. saatin başlangıcı ve her gün gece yarısı) hedeflemeyin.

Yanıtları işleme

Bir web hizmeti isteğine verilen bireysel yanıtların tam biçimi garanti edilmediğinden (bazı öğeler eksik olabilir veya birden fazla yerde bulunabilir) belirli bir yanıt için döndürülen biçimin farklı sorgular için aynı olduğunu varsaymayın. Bunun yerine, yanıtı işleyin ve ifadeleri kullanarak uygun değerleri seçin.

Bu bölümde, bu değerlerin web hizmeti yanıtlarından nasıl dinamik olarak ayıklanacağı açıklanmaktadır.

Google Haritalar web hizmetleri, anlaşılır ancak kullanıcı dostu olmayan yanıtlar veriyor. Sorgu yaparken bir veri kümesi görüntülemek yerine muhtemelen birkaç belirli değeri ayıklamak istersiniz. Genellikle web hizmetinden gelen yanıtları ayrıştırın ve yalnızca ilgilendiğiniz değerleri çıkarın.

Kullandığınız ayrıştırma şeması, çıktıyı JSON olarak döndürüp döndürmediğinize bağlıdır. Zaten JavaScript nesneleri biçiminde olan JSON yanıtları, istemcide JavaScript'in kendisinde işlenebilir.