Halaman ini diterjemahkan oleh Cloud Translation API.

Praktik Terbaik Menggunakan Layanan Web Geolocation API

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

Panduan ini menjelaskan beberapa praktik umum yang berguna untuk menyiapkan layanan web permintaan dan memproses respons layanan. Lihat panduan developer untuk dokumentasi lengkap Geolocation 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 dalam aplikasi Maps Anda. Layanan ini dirancang untuk digunakan bersama peta, sesuai dengan Pembatasan Lisensi di Persyaratan Layanan Google Maps Platform.

Layanan web Maps API menggunakan permintaan HTTP(S) ke URL tertentu, dengan meneruskan parameter URL, dan/atau Data POST format JSON sebagai argumen ke layanan. Biasanya, layanan ini mengembalikan data di isi respons sebagai JSON untuk penguraian dan/atau pemrosesan oleh aplikasi Anda.

Permintaan geolokasi dikirim menggunakan POST ke URL berikut:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

Catatan: Semua aplikasi Geolocation 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 pengguna layanan otomatis dan data skalabel. Permintaan yang dibuat melalui HTTP yang berisi data sensitif dapat ditolak.

Penggunaan Moderat Google API

Klien API yang tidak dirancang dengan baik dapat menempatkan lebih banyak beban daripada yang diperlukan di Internet dan Server Google. Bagian ini berisi beberapa praktik terbaik untuk klien API. Mengikuti praktik terbaik ini dapat membantu Anda agar aplikasi Anda tidak diblokir karena penyalahgunaan yang tidak disengaja API.

Backoff Eksponensial

Dalam kasus yang jarang terjadi, mungkin terjadi error saat melayani permintaan Anda; Anda mungkin menerima HTTP 4XX atau 5XX kode respons, atau koneksi TCP mungkin gagal di antara klien Anda dan jaringan server tertentu. Sering kali ada gunanya mencoba kembali permintaan sebagai permintaan tindak lanjut mungkin berhasil jika permintaan asli gagal. Namun, penting untuk tidak hanya melakukan loop berulang kali ke server Google. Perilaku pengulangan ini dapat membebani jaringan antara klien Anda dan Google yang menyebabkan masalah bagi banyak pihak.

Pendekatan terbaik adalah mencoba ulang dengan meningkatkan waktu tunda antar percobaan. Biasanya penundaan meningkat dengan faktor perkalian dengan setiap percobaan, pendekatan yang dikenal sebagai Backoff Eksponensial.

Misalnya, pertimbangkan aplikasi yang ingin membuat permintaan ini untuk 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 bahwa tidak ada percobaan ulang kode yang lebih tinggi dalam panggilan aplikasi rantai yang mengarah ke permintaan berulang dengan cepat.

Permintaan yang Disinkronkan

Permintaan yang disinkronkan ke API Google dalam jumlah besar akan terlihat seperti permintaan Serangan Denial of Service (DDoS) pada infrastruktur Google, dan diperlakukan sebagaimana mestinya. Kepada menghindari hal ini, Anda harus memastikan bahwa permintaan API tidak disinkronkan antar klien.

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

Melakukan panggilan API untuk merespons alarm yang sudah diperbaiki adalah hal yang buruk karena mengakibatkan panggilan API menjadi disinkronkan hingga awal menit, bahkan di antara perangkat yang berbeda, alih-alih didistribusikan secara merata seiring waktu. Aplikasi yang didesain dengan buruk yang melakukan hal ini akan menghasilkan lonjakan lalu lintas pada enam puluh kali tingkat normal pada awal setiap menit.

Sebagai gantinya, satu rancangan yang mungkin baik adalah menyetel alarm kedua ke waktu terpilih yang acak. Saat alarm kedua ini terpicu, aplikasi akan memanggil API apa pun yang diperlukannya dan menyimpan hasil pengujian tersebut. Ketika ingin memperbarui tampilannya di awal menit, aplikasi akan menggunakan hasil yang disimpan sebelumnya daripada memanggil API lagi. Dengan pendekatan ini, panggilan API akan tersebar secara merata dari waktu ke waktu. Selanjutnya, panggilan API tidak menunda rendering saat tampilan diperbarui.

Selain waktu mulai menit, waktu sinkronisasi umum lainnya harus berhati-hati tidak menargetkan 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, tapi tidak mudah digunakan. Saat melakukan kueri, bukan daripada menampilkan satu set data, Anda mungkin ingin mengekstrak beberapa masing-masing. Biasanya, Anda ingin mengurai respons dari web layanan dan hanya ekstrak nilai-nilai yang Anda minati.

Skema penguraian yang Anda gunakan bergantung pada apakah Anda mengembalikan di JSON. Respons JSON, yang sudah dalam bentuk Objek JavaScript, dapat diproses dalam JavaScript itu sendiri pada klien.