หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

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

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

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

ตัวอย่างต่อไปนี้แสดง URL ของคำขอ POST ของ REST ไปยังเมธอด optimizeTours

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

แทนที่ PROJECT_NUMBER ด้วยหมายเลขหรือรหัสของโปรเจ็กต์ระบบคลาวด์ที่เปิดใช้ Route Optimization API

ใส่ข้อความ OptimizeToursRequest เป็นเนื้อหาคำขอ JSON

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

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

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

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

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

สัญลักษณ์พิเศษ

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

สรุปอักขระของ URL ที่ถูกต้อง

ตั้งค่า	ตัวละคร	การใช้ URL
ตัวอักษรและตัวเลข	ก ข ค ด ข อ ก ข อ ก ไ ม้ แ ห น ข อ ก ไ ม้ แ ห บ ข อ ก ไ ม้	สตริงข้อความ การใช้รูปแบบ (`http`), พอร์ต (`8080`) ฯลฯ
ไม่ได้จอง	- _ ~	สตริงข้อความ
จองแล้ว	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	อักขระควบคุมและ/หรือสตริงข้อความ

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

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

อักขระทั้งหมดที่จะเข้ารหัส 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

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

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

อักขระที่ไม่ปลอดภัย	ค่าที่เข้ารหัส
พื้นที่	`%20`
"	`%22`
<	`%3C`
>	`%3E`
#	`%23`
%	`%25`
\|	`%7C`

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

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

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

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

Exponential Backoff

ในบางกรณีที่เกิดขึ้นไม่บ่อยนักอาจเกิดข้อผิดพลาดขณะดำเนินการตามคำขอ คุณอาจได้รับรหัสตอบกลับ HTTP 4XX หรือ 5XX หรือการเชื่อมต่อ TCP อาจล้มเหลวในระหว่างไคลเอ็นต์และเซิร์ฟเวอร์ของ Google การลองส่งคำขออีกครั้งมักจะเป็นสิ่งที่คุ้มค่า เนื่องจากคำขอติดตามผลอาจประสบความสำเร็จเมื่อคำขอเดิมล้มเหลว อย่างไรก็ตาม ต้องไม่เพียงแค่ส่งคำขอไปยังเซิร์ฟเวอร์ของ 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 จำนวนมากอาจดูเหมือนการโจมตีแบบ Distributiond Denial of Service (DDoS) ในโครงสร้างพื้นฐานของ Google และได้รับการจัดการตามนั้น หากไม่ต้องการให้เป็นเช่นนั้น คุณควรตรวจสอบว่าคำขอ API ไม่ได้ซิงค์ระหว่างไคลเอ็นต์

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

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

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

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

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

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

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

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

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