แนวทางปฏิบัติแนะนำสำหรับการใช้บริการเว็บ Roads API

บริการเว็บของ Google Maps Platform เป็นชุดอินเทอร์เฟซ HTTP ที่ส่งไปยัง Google ซึ่งเป็นบริการที่ให้ข้อมูลทางภูมิศาสตร์สำหรับแอปพลิเคชันแผนที่ของคุณ

คู่มือนี้จะอธิบายแนวทางปฏิบัติทั่วไปบางส่วนที่มีประโยชน์สำหรับการตั้งค่า เว็บเซอร์วิส และประมวลผลการตอบกลับของบริการ ดูคู่มือสำหรับนักพัฒนาซอฟต์แวร์ เพื่อดูเอกสารประกอบฉบับเต็มเกี่ยวกับ Roads API

บริการทางเว็บคืออะไร

บริการบนเว็บของ Google Maps Platform คืออินเทอร์เฟซสําหรับขอข้อมูล Maps API จาก บริการภายนอกและการใช้ข้อมูลภายในแอปพลิเคชันแผนที่ของคุณ บริการเหล่านี้ เพื่อใช้ร่วมกับแผนที่ ตาม ข้อจำกัดของใบอนุญาต ในข้อกำหนดในการให้บริการของ Google Maps Platform

บริการบนเว็บของ Maps API ใช้คำขอ HTTP(S) ไปยัง URL ที่เฉพาะเจาะจง โดยส่งผ่านพารามิเตอร์ของ URL และ/หรือ ข้อมูล POST ในรูปแบบ JSON เป็นอาร์กิวเมนต์ไปยังบริการ โดยทั่วไป บริการเหล่านี้จะแสดงข้อมูลใน เนื้อหาการตอบกลับเป็น JSON สำหรับการแยกวิเคราะห์ และ/หรือกำลังประมวลผลโดยแอปพลิเคชันของคุณ

คำขอบริการผ่านเว็บของ Roads API โดยทั่วไปจะเป็น แบบฟอร์มต่อไปนี้:

https://roads.googleapis.com/v1/snapToRoads?parameters&key=YOUR_API_KEY

โดยที่ snapToRoads จะระบุบริการเฉพาะที่ขอ ถนนอื่นๆ บริการประกอบด้วย nearestRoads และ speedLimits

หมายเหตุ: แอปพลิเคชัน Roads API ทั้งหมดต้องมีการตรวจสอบสิทธิ์ ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์

การเข้าถึง SSL/TLS

ต้องใช้ HTTPS สำหรับคำขอ Google Maps Platform ทั้งหมดที่ใช้คีย์ API หรือมีผู้ใช้ คำขอที่ส่งผ่าน HTTP ซึ่งมีข้อมูลที่ละเอียดอ่อนอาจถูกปฏิเสธ

การสร้าง URL ที่ถูกต้อง

คุณอาจคิดว่า "ถูกต้อง" URL ชัดเจน แต่มีความชัดเจน ยังไม่ใช่แบบนั้น URL ที่ป้อนในแถบที่อยู่เว็บใน อาจมีสัญลักษณ์พิเศษ (เช่น "上海+中國"); เบราว์เซอร์จำเป็นต้องแปลเป็นการภายใน อักขระเหล่านั้นเป็นการเข้ารหัสที่แตกต่างกันก่อนส่ง โทเค็นเดียวกันจะหมายถึงโค้ดที่สร้างหรือยอมรับอินพุต UTF-8 อาจถือว่า URL ที่มีอักขระ UTF-8 นั้น "ถูกต้อง" แต่ก็ต้อง เพื่อแปลอักขระเหล่านั้นก่อนที่จะส่งไปยังเว็บเซิร์ฟเวอร์ กระบวนการนี้เรียกว่า การเข้ารหัส URL หรือการเข้ารหัสเปอร์เซ็นต์

อักขระพิเศษ

เราจำเป็นต้องแปลอักขระพิเศษเนื่องจาก URL ทั้งหมดต้องสอดคล้องกับไวยากรณ์ที่ระบุโดย เครื่องแบบ ข้อกำหนดของตัวระบุทรัพยากร (URI) ในความเป็นจริงหมายความว่า URL จะต้องประกอบด้วยชุดย่อยพิเศษของอักขระ ASCII ได้แก่ สัญลักษณ์ที่เป็นตัวอักษรและตัวเลขคละกัน และอักขระที่สงวนไว้บางตัวเพื่อใช้เป็นตัวควบคุม อักขระภายใน URL ตารางนี้จะสรุปอักขระเหล่านี้

เมื่อสร้าง URL ที่ถูกต้อง คุณต้องตรวจสอบว่า URL นั้นมีเฉพาะอักขระที่แสดงใน การปฏิบัติตาม URL เพื่อใช้ชุดอักขระนี้โดยทั่วไป จะก่อให้เกิดปัญหา 2 ประการ อันหนึ่งคือ การละเว้นสิ่งใดสิ่งหนึ่ง และการทดแทนอีกอย่างหนึ่งอย่างนั้น

• มีอักขระที่คุณต้องการจัดการอยู่นอก ข้างต้น ตัวอย่างเช่น อักขระในภาษาต่างประเทศ เช่น 上海+中國 จำเป็นต้องเข้ารหัสโดยใช้ ที่อยู่เหนืออักขระ ตามการประชุมยอดนิยม การเว้นวรรค (ซึ่งก็คือ ไม่อนุญาตภายใน URL) มักจะแสดงโดยใช้เครื่องหมายบวก '+' อักขระด้วย
• อักขระอยู่ภายในชุดด้านบนเป็นอักขระสงวน แต่จำเป็นต้องใช้จริงๆ ตัวอย่างเช่น ? จะใช้ภายใน URL เพื่อระบุว่า จุดเริ่มต้นของสตริงการค้นหา หากคุณต้องการใช้ สตริง "? และเรื่องลึกลับ" คุณจะต้องเข้ารหัส '?' อักขระ

อักขระทั้งหมดที่จะเข้ารหัส URL จะเข้ารหัส โดยใช้อักขระ '%' และเลขฐานสิบหก 2 ตัว ที่สอดคล้องกับอักขระ UTF-8 ตัวอย่างเช่น 上海+中國 ใน UTF-8 จะเข้ารหัส URL เป็น %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B สตริง ? and the Mysterians จะมีการเข้ารหัส URL เป็น %3F+and+the+Mysteriansหรือ%3F%20and%20the%20Mysterians

อักขระทั่วไปที่ต้องเข้ารหัส

อักขระทั่วไปที่จะต้องเข้ารหัสมีดังนี้

การแปลง URL ที่คุณได้รับจากข้อมูลจากผู้ใช้เป็นบางครั้ง ซับซ้อน ตัวอย่างเช่น ผู้ใช้สามารถป้อนที่อยู่เป็น "5th&Main St." โดยทั่วไป คุณควรสร้าง URL จากชิ้นส่วน โดยถือ ข้อมูลจากผู้ใช้เป็นอักขระลิเทอรัล

นอกจากนี้ URL จะมีอักขระได้ไม่เกิน 16, 384 ตัวสำหรับบริการบนเว็บของ Google Maps Platform ทั้งหมด และเว็บ API แบบคงที่ สำหรับบริการส่วนใหญ่ จำนวนอักขระสูงสุดนี้แทบจะไม่ได้ใช้เลย อย่างไรก็ตาม โปรดทราบว่าบริการบางอย่างมีพารามิเตอร์หลายรายการที่อาจทำให้เกิด URL แบบยาว

การใช้ Google APIs อย่างสุภาพ

ไคลเอ็นต์ API ซึ่งออกแบบมาไม่ดีอาจมีภาระงานมากเกินความจำเป็นทั้งบนโลกอินเทอร์เน็ตและ เซิร์ฟเวอร์ของ Google ส่วนนี้ประกอบด้วยแนวทางปฏิบัติที่ดีที่สุดบางส่วนสำหรับไคลเอ็นต์ของ API กำลังติดตาม แนวทางปฏิบัติแนะนำเหล่านี้จะช่วยให้คุณสามารถป้องกันไม่ให้แอปพลิเคชันถูกบล็อกเนื่องจากการละเมิด API

Exponential Backoff

ในบางกรณีที่เกิดขึ้นไม่บ่อยนัก อาจเกิดความผิดพลาดในการดำเนินการตามคำขอของคุณ คุณอาจได้รับ HTTP 4XX หรือ 5XX หรือการเชื่อมต่อ TCP อาจล้มเหลวระหว่างไคลเอ็นต์ของคุณและ เซิร์ฟเวอร์ บ่อยครั้งที่คุ้มค่าที่จะลองส่งคำขอใหม่ คำขอติดตามผลอาจสำเร็จเมื่อการดำเนินการครั้งแรกล้มเหลว อย่างไรก็ตาม คุณไม่ควรเพียงแค่ ส่งคำขอไปยังเซิร์ฟเวอร์ของ Google ซ้ำๆ การทำงานแบบวนซ้ำนี้อาจทำให้ เครือข่ายระหว่างไคลเอ็นต์ของคุณและ Google ซึ่งทำให้เกิดปัญหากับหลายฝ่าย

วิธีที่ดีกว่าคือลองอีกครั้งโดยให้ความล่าช้าเพิ่มขึ้นระหว่างการดำเนินการแต่ละครั้ง โดยปกติ ความล่าช้าจะเพิ่มขึ้นตามตัวคูณของความพยายามแต่ละครั้ง ซึ่งเราเรียกกันว่า Exponential Backoff

ตัวอย่างเช่น ลองพิจารณาแอปพลิเคชันที่ต้องการส่งคำขอนี้ไปยัง Time Zone API

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

ตัวอย่าง Python ต่อไปนี้แสดงวิธีส่งคำขอด้วย Exponential Backoff

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

คุณควรระมัดระวังไม่ให้ลองเขียนโค้ดอีกครั้งในการเรียกใช้แอปพลิเคชัน เชนที่นําไปสู่คําขอซ้ำๆ ติดต่อกันอย่างรวดเร็ว

คำขอที่ซิงค์

คำขอที่ซิงค์จำนวนมากไปยัง API ของ Google อาจดูเหมือนคำขอที่ กระจาย การโจมตีการปฏิเสธการให้บริการ (DDoS) บนโครงสร้างพื้นฐานของ Google และควรปฏิบัติอย่างเหมาะสม ถึง เพื่อหลีกเลี่ยงปัญหานี้ คุณควรตรวจสอบว่าคำขอ API ไม่มีการซิงค์ ระหว่างไคลเอ็นต์

ตัวอย่างเช่น ลองพิจารณาแอปพลิเคชันที่แสดงเวลาในเขตเวลาปัจจุบัน แอปพลิเคชันนี้น่าจะตั้งปลุกในระบบปฏิบัติการของไคลเอ็นต์เพื่อให้เริ่มทำงานในเวลา จุดเริ่มต้นของนาทีเพื่อให้อัปเดตเวลาที่แสดงได้ แอปพลิเคชันควร ไม่เรียก API ใดๆ เป็นส่วนหนึ่งของการประมวลผลที่เชื่อมโยงกับการปลุกนั้น

การเรียก API ตามการปลุกแบบคงที่นั้นไม่ดี เนื่องจากจะทำให้การเรียก API ซิงค์ตั้งแต่นาทีแรก แม้กระทั่งระหว่างอุปกรณ์ต่างๆ จะกระจายอย่างเท่าๆ กันเมื่อเวลาผ่านไป แอปพลิเคชันที่ออกแบบไว้ไม่ดี ซึ่งมีส่วนทำให้ การเข้าชมที่ระดับปกติหกสิบเท่า ณ จุดเริ่มต้นของแต่ละนาที

แต่วิธีออกแบบที่ดีที่เป็นไปได้อย่างหนึ่งคือ ตั้งปลุกครั้งที่ 2 ตามเวลาที่เลือกแบบสุ่ม เมื่อการปลุกครั้งที่ 2 เริ่มทํางาน แอปพลิเคชันจะเรียก API ที่จำเป็นต้องใช้และจัดเก็บ ผลลัพธ์ เมื่อแอปพลิเคชันต้องการอัปเดตการแสดงผลตั้งแต่เริ่มต้นนาที แอปพลิเคชันจะใช้ ผลลัพธ์ที่จัดเก็บไว้ก่อนหน้านี้ แทนการเรียกใช้ API อีกครั้ง วิธีนี้ทำให้การเรียก API จะกระจายอย่างเท่าๆ กันเมื่อเวลาผ่านไป นอกจากนี้ การเรียก API จะไม่ทำให้การแสดงผลล่าช้าเมื่อ กำลังอัปเดต

นอกจากเวลาเริ่มนาทีแล้ว เวลาซิงค์ทั่วไปอื่นๆ ที่ควรระมัดระวัง ไม่ ในการกําหนดเป้าหมายคือจุดเริ่มต้นของชั่วโมงและเริ่มต้นของแต่ละวันตอนเที่ยงคืน

กำลังประมวลผลคำตอบ

ส่วนนี้จะกล่าวถึงวิธีดึงค่าเหล่านี้แบบไดนามิกจากการตอบกลับของบริการเว็บ

บริการบนเว็บของ Google Maps ให้คำตอบที่ เข้าใจ แต่ไม่ค่อยใช้งานง่ายนัก เมื่อดำเนินการค้นหา คุณอาจต้องการแยกชุดข้อมูล โดยทั่วไป คุณจะต้องแยกวิเคราะห์คำตอบจากเว็บ บริการและแยกเฉพาะค่าที่คุณสนใจ

รูปแบบการแยกวิเคราะห์ที่คุณใช้จะขึ้นอยู่กับว่าคุณกำลังส่งคืน เป็น JSON การตอบกลับ JSON อยู่ในรูปแบบของ ออบเจ็กต์ JavaScript อาจประมวลผลภายใน JavaScript เอง ไคลเอ็นต์