Praktik Terbaik Menggunakan Layanan Web API Ubin Peta

Layanan web Google Maps Platform adalah kumpulan antarmuka HTTP ke layanan Google yang menyediakan data geografis untuk aplikasi peta Anda.

Panduan ini menjelaskan beberapa praktik umum yang berguna untuk menyiapkan permintaan layanan web dan memproses respons layanan. Lihat panduan developer untuk mengetahui dokumentasi lengkap Map Tiles API.

Apa yang dimaksud dengan layanan web?

Layanan web Google Maps Platform adalah antarmuka untuk meminta data Maps API dari layanan eksternal dan menggunakan data tersebut dalam aplikasi Maps Anda. Layanan ini dirancang untuk digunakan bersama dengan peta, sesuai dengan Pembatasan Lisensi dalam Persyaratan Layanan Google Maps Platform.

Layanan web Maps API menggunakan permintaan HTTP(S) ke URL tertentu, yang meneruskan parameter URL dan/atau data POST berformat JSON sebagai argumen ke layanan. Umumnya, layanan ini menampilkan data dalam isi respons sebagai JSON untuk penguraian dan/atau pemrosesan oleh aplikasi Anda.

Contoh permintaan layanan web adalah permintaan metadata Street View, yang memiliki bentuk berikut:

https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId

Catatan: Semua aplikasi Map Tiles API memerlukan autentikasi. Dapatkan informasi selengkapnya tentang kredensial autentikasi.

Akses SSL/TLS

HTTPS diperlukan untuk semua permintaan Google Maps Platform yang menggunakan kunci API atau berisi data pengguna. Permintaan yang dibuat melalui HTTP yang berisi data sensitif dapat ditolak.

Penggunaan Moderat Google API

Klien API yang dirancang dengan buruk dapat memberikan beban yang lebih besar daripada yang diperlukan pada Internet dan server Google. Bagian ini berisi beberapa praktik terbaik untuk klien API. Mengikuti praktik terbaik ini dapat membantu Anda menghindari pemblokiran aplikasi karena penyalahgunaan API yang tidak disengaja.

Backoff Eksponensial

Dalam kasus yang jarang terjadi, mungkin ada masalah saat menyajikan permintaan Anda; Anda mungkin menerima kode respons HTTP 4XX atau 5XX, atau koneksi TCP mungkin gagal di suatu tempat antara klien Anda dan server Google. Sering kali, mencoba ulang permintaan akan bermanfaat karena permintaan lanjutan mungkin berhasil saat permintaan awal gagal. Namun, penting untuk tidak hanya melakukan loop berulang kali saat membuat permintaan ke server Google. Perilaku pengulangan ini dapat membebani jaringan antara klien Anda dan Google, sehingga menyebabkan masalah bagi banyak pihak.

Pendekatan terbaik adalah mencoba ulang dengan meningkatkan waktu tunda antar percobaan. Biasanya, penundaan ditingkatkan dengan faktor perkalian pada setiap percobaan, pendekatan yang dikenal sebagai backoff eksponensial.

Misalnya, pertimbangkan aplikasi yang ingin membuat permintaan ini ke Time Zone API:

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

Contoh Python berikut menampilkan cara membuat permintaan dengan backoff eksponensial:

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

Anda juga harus berhati-hati agar tidak ada kode percobaan ulang yang lebih tinggi dalam rantai panggilan aplikasi yang menyebabkan permintaan berulang secara berurutan.

Permintaan yang Disinkronkan

Permintaan sinkron dalam jumlah besar ke API Google dapat terlihat seperti serangan Distributed Denial of Service (DDoS) pada infrastruktur Google, dan akan diperlakukan sebagaimana mestinya. Untuk menghindarinya, Anda harus memastikan bahwa permintaan API tidak disinkronkan di antara klien.

Misalnya, pertimbangkan aplikasi yang menampilkan waktu dalam zona waktu saat ini. Aplikasi ini mungkin akan menyetel alarm di sistem operasi klien yang membangunkannya di awal menit sehingga waktu yang ditampilkan dapat diperbarui. Aplikasi tidak boleh melakukan panggilan API apa pun sebagai bagian dari pemrosesan yang terkait dengan alarm tersebut.

Melakukan panggilan API sebagai respons terhadap alarm tetap adalah hal yang buruk karena menyebabkan panggilan API disinkronkan ke awal menit, bahkan di antara perangkat yang berbeda, bukan didistribusikan secara merata dari waktu ke waktu. Aplikasi yang dirancang dengan buruk yang melakukan hal ini akan menghasilkan lonjakan traffic enam puluh kali lipat dari tingkat normal di awal setiap menit.

Sebagai gantinya, satu rancangan yang mungkin baik adalah menyetel alarm kedua ke waktu terpilih yang acak. Saat alarm kedua ini diaktifkan, aplikasi akan memanggil API yang diperlukan dan menyimpan hasilnya. Saat aplikasi ingin memperbarui tampilannya di awal menit, aplikasi akan menggunakan hasil yang disimpan sebelumnya, bukan memanggil API lagi. Dengan pendekatan ini, panggilan API disebarkan secara merata dari waktu ke waktu. Selain itu, panggilan API tidak menunda rendering saat tampilan sedang diperbarui.

Selain awal menit, waktu sinkronisasi umum lainnya yang harus Anda perhatikan agar tidak ditargetkan adalah di awal jam, dan awal setiap hari pada tengah malam.

Memproses Respons

Bagian ini membahas cara mengekstrak nilai-nilai ini secara dinamis dari respons layanan web.

Layanan web Google Maps memberikan respons yang mudah dipahami, tetapi tidak terlalu mudah digunakan. Saat menjalankan kueri, daripada menampilkan sekumpulan data, Anda mungkin ingin mengekstrak beberapa nilai tertentu. Umumnya, Anda perlu mengurai respons dari layanan web dan hanya mengekstrak nilai yang Anda minati.

Skema penguraian yang Anda gunakan bergantung pada apakah Anda menampilkan output dalam JSON atau tidak. Respons JSON, yang sudah dalam bentuk objek Javascript, dapat diproses dalam Javascript itu sendiri di klien.