แนวทางปฏิบัติที่ดีที่สุดในการใช้บริการเว็บ Places Insights API

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

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

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

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

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

ตัวอย่างต่อไปนี้จะแสดง URL ของ คำขอ REST GET:

AN ACTUAL API CALL INCLUDING THE API_KEY&key=API_KEY

หมายเหตุ: แอปพลิเคชัน Places Insights 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
ตัวอักษรและตัวเลขคละกัน 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 เพื่อระบุว่า จุดเริ่มต้นของสตริงการค้นหา หากต้องการใช้ สตริง "? และเรื่องลึกลับ" คุณจะต้องเข้ารหัส '?' อักขระ

อักขระทั้งหมดที่จะเข้ารหัส URL จะเข้ารหัส โดยใช้อักขระ '%' และเลขฐานสิบหก 2 ตัว ที่สอดคล้องกับอักขระ UTF-8 ตัวอย่างเช่น 上海+中國 ใน UTF-8 จะเป็น%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B เมื่อเข้ารหัสเป็น URL สตริง ? 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 ของเว็บเซอร์วิสและ Web API แบบคงที่ทั้งหมดของ Google Maps Platform จะถูกจำกัดไว้ที่ 16384 อักขระ สำหรับบริการส่วนใหญ่ จำนวนอักขระสูงสุดนี้แทบจะไม่ได้ใช้เลย อย่างไรก็ตาม โปรดทราบว่าบริการบางอย่างมีพารามิเตอร์หลายรายการที่อาจส่งผลให้มี URL แบบยาว

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

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

Exponential Backoff

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

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

ตัวอย่างเช่น ลองพิจารณาแอปพลิเคชันที่ต้องการให้ส่งคําขอนี้ไปยัง 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 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 เอง ไคลเอ็นต์