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

Google Maps Platform Static Web API ซึ่งเป็นชุดอินเทอร์เฟซ HTTP จะสร้างรูปภาพสําหรับฝังในหน้าเว็บโดยตรง

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

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

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

Static 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

ต้องใช้ 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 เพื่อระบุ จุดเริ่มต้นของสตริงคำค้นหา หากต้องการใช้สตริง "? 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

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

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

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

นอกจากนี้ URL ยังมีความยาวไม่เกิน 16384 ตัวสำหรับเว็บเซอร์วิสทั้งหมดของ Google Maps Platform และเว็บ API แบบคงที่ สำหรับบริการส่วนใหญ่ คุณแทบจะไม่ต้องกังวลเรื่องจำนวนอักขระสูงสุดนี้ อย่างไรก็ตาม โปรดทราบว่าบริการบางอย่างมีพารามิเตอร์หลายรายการที่อาจทำให้ 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 ต่อไปนี้แสดงวิธีส่งคำขอด้วย การถอยแบบทวีคูณ

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 เองในไคลเอ็นต์ได้