แนวทางปฏิบัติที่ดีที่สุดในการใช้ Maps Static API

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

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

API เว็บแบบคงที่คืออะไร

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

โดยทั่วไปแล้ว คำขอ API แบบคงที่ของ Maps จะอยู่ในรูปแบบต่อไปนี้

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

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

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

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

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

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

ข้อควรระวัง: เบราว์เซอร์และ/หรือบริการอาจเข้ารหัส URL ให้กับ URI คำขอก่อนส่ง ใน API ที่ใช้การรับรองคำขอการเข้ารหัส การดำเนินการนี้อาจทำให้ลายเซ็นใช้งานไม่ได้ หากการเข้ารหัส URL เปลี่ยนแปลงคำขอหลังจากลงนาม เพื่อหลีกเลี่ยงปัญหานี้ ให้เข้ารหัส URL ในสตริงการค้นหาทุกครั้งก่อนที่จะลงนามในคำขอ

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

เราต้องแปลสัญลักษณ์พิเศษเนื่องจาก URL ทั้งหมดต้องสอดคล้องกับไวยากรณ์ที่ระบุโดยข้อกำหนด Uniform Resource Identifier (URI) ซึ่งหมายความว่า URL ต้องมีเฉพาะชุดย่อยพิเศษของอักขระ ASCII ได้แก่ สัญลักษณ์ที่เป็นตัวอักษรและตัวเลขคละกันที่คุ้นเคย และอักขระที่สงวนไว้บางตัวเพื่อใช้เป็นอักขระควบคุมภายใน 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 X Y Z 0 1 2 3 4	สตริงข้อความ การใช้รูปแบบ (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 ยังมีอักขระได้ไม่เกิน 16, 384 ตัวสำหรับบริการเว็บ Google Maps Platform และ API เว็บแบบคงที่ทั้งหมด สำหรับบริการส่วนใหญ่ จำนวนอักขระสูงสุดนี้จะไม่ค่อยถึงขีดจำกัดนี้ อย่างไรก็ตาม โปรดทราบว่าบริการบางอย่างมีพารามิเตอร์หลายรายการที่อาจส่งผลให้ URL มีความยาวได้