เข้าร่วมงาน Google Maps Platform Developer Community Day ครั้งถัดไปกับเราที่ซานฟรานซิสโกในเดือนธันวาคม สมัครเลยเพื่อเข้าร่วม

Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

แนวทางปฏิบัติแนะนำในการใช้ Street View Static API

API แบบคงที่บนเว็บของ Google Maps Platform เป็นคอลเล็กชันอินเทอร์เฟซ HTTP ที่สร้างรูปภาพเพื่อฝังลงในหน้าเว็บโดยตรง

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

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

Street View Static API ทำหน้าที่เหมือน Web API แบบคงที่ ส่วนบริการข้อมูลเมตาทำหน้าที่เป็นเว็บเซอร์วิส ดูข้อมูลเพิ่มเติมเกี่ยวกับบริการข้อมูลเมตาได้ที่ข้อมูลเมตาของภาพ Street View

Web API แบบคงที่คืออะไร

Static Web API ของ Google Maps Platform ช่วยให้คุณฝังรูปภาพ Google Maps ในหน้าเว็บได้โดยไม่ต้องใช้ JavaScript หรือการโหลดหน้าเว็บแบบไดนามิก API ของเว็บแบบคงที่จะสร้างรูปภาพตามพารามิเตอร์ของ URL ที่ส่งโดยใช้คำขอ HTTPS มาตรฐาน

คำขอ Street View Static API ทั่วไปจะมีรูปแบบต่อไปนี้

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

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

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

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

คำขอข้อมูลเมตาของ Street View Static API มีรูปแบบดังนี้

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

การเข้าถึง SSL และ TLS

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

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

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

อักขระพิเศษ

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

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

ตั้งค่า	อักขระ	การใช้ URL
ตัวอักษรและตัวเลขคละกัน	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	สตริงข้อความ การใช้รูปแบบ (`http`) พอร์ต (`8080`) ฯลฯ
ไม่ได้จอง	- _ . ~	สตริงข้อความ
จองแล้ว	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	อักขระควบคุมและ/หรือสตริงข้อความ

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

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

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

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

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

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

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

การใช้ Google APIs อย่างเหมาะสม

ไคลเอ็นต์ API ที่ออกแบบมาไม่ดีอาจทำให้เกิดภาระงานหนักบนอินเทอร์เน็ตและเซิร์ฟเวอร์ ส่วนนี้ประกอบด้วยแนวทางปฏิบัติแนะนำสำหรับไคลเอ็นต์ 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 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}")

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

คำขอที่โหลดแบบซิงโครนัส

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

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

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

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

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

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

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

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

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

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