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

แนวทางปฏิบัติแนะนำสำหรับการใช้บริการเว็บ API คุณภาพอากาศ

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

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

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

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

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

ขอข้อมูลคุณภาพอากาศรายชั่วโมงปัจจุบันโดยใช้ currentConditions โดยส่งคำขอ HTTP POST ไปยัง:

https://airquality.googleapis.com/v1/currentConditions:lookup?key=API_KEY

ส่งเนื้อหา JSON ในคำขอกำหนดสถานที่

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

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

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

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

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

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

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