API web tĩnh của Nền tảng Google Maps là một tập hợp các giao diện HTTP đến các dịch vụ của Google. Các dịch vụ này tạo ra hình ảnh mà bạn có thể nhúng trực tiếp vào trang web của mình.
Hướng dẫn này mô tả một số phương pháp phổ biến hữu ích để thiết lập các yêu cầu hình ảnh và xử lý phản hồi của dịch vụ. Hãy tham khảo hướng dẫn dành cho nhà phát triển để biết tài liệu đầy đủ về API tĩnh của Maps.
API web tĩnh là gì?
API web tĩnh của Google Maps Platform cho phép bạn nhúng hình ảnh Google Maps vào trang web mà không cần JavaScript hoặc bất kỳ tính năng tải trang động nào. API web tĩnh tạo hình ảnh dựa trên các tham số URL được gửi bằng yêu cầu HTTPS tiêu chuẩn.Yêu cầu API Tĩnh của Maps thường có dạng như sau:
https://www.googleapis.com/staticmap/z/x/y?parameters
Lưu ý: Tất cả ứng dụng API Bản đồ tĩnh đều yêu cầu xác thực. Xem thêm thông tin về thông tin xác thực.
Quyền truy cập SSL/TLS
Tất cả các yêu cầu gửi tới Nền tảng Google Maps sử dụng khoá API hoặc chứa dữ liệu người dùng đều phải sử dụng giao thức HTTPS. Các yêu cầu được thực hiện qua HTTP và chứa dữ liệu nhạy cảm có thể bị từ chối.
Tạo URL hợp lệ
Bạn có thể nghĩ rằng một URL "hợp lệ" là điều hiển nhiên, nhưng thực tế không phải vậy. Ví dụ: URL được nhập trong thanh địa chỉ của trình duyệt có thể chứa các ký tự đặc biệt (ví dụ: "上海+中國"); trình duyệt cần dịch nội bộ các ký tự đó thành một cách mã hoá khác trước khi truyền.
Tương tự, mọi mã tạo hoặc chấp nhận dữ liệu đầu vào UTF-8 đều có thể coi URL có ký tự UTF-8 là "hợp lệ", nhưng cũng cần dịch các ký tự đó trước khi gửi đến máy chủ web.
Quá trình này được gọi là
mã hoá URL hoặc mã hoá theo tỷ lệ phần trăm.
Các ký tự đặc biệt
Chúng ta cần dịch các ký tự đặc biệt vì tất cả URL cần tuân thủ cú pháp do quy cách Uniform Resource Identifier (URI) (Giá trị nhận dạng tài nguyên đồng nhất) chỉ định. Về cơ bản, điều này có nghĩa là URL chỉ được chứa một tập hợp con đặc biệt của ký tự ASCII: các ký hiệu chữ và số quen thuộc và một số ký tự được đặt trước để dùng làm ký tự điều khiển trong URL. Bảng này tóm tắt các ký tự này:
| Chuẩn bị | ký tự | Mức sử dụng URL |
|---|---|---|
| Chữ và số | 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 | Chuỗi văn bản, cách sử dụng giao thức (http), cổng (8080), v.v. |
| Không dành riêng | – _ . ~ | Chuỗi văn bản |
| Đã đặt trước | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Điều khiển ký tự và/hoặc Chuỗi văn bản |
Khi tạo một URL hợp lệ, bạn phải đảm bảo rằng URL đó chỉ chứa các ký tự xuất hiện trong bảng. Việc tuân thủ một URL để sử dụng bộ ký tự này thường dẫn đến hai vấn đề, một vấn đề về việc bỏ qua và một vấn đề về việc thay thế:
- Các ký tự mà bạn muốn xử lý nằm ngoài tập hợp trên. Ví dụ: các ký tự bằng ngôn ngữ nước ngoài như
上海+中國cần được mã hoá bằng các ký tự ở trên. Theo quy ước phổ biến, dấu cách (không được phép trong URL) cũng thường được biểu thị bằng ký tự dấu cộng'+'. - Các ký tự tồn tại trong tập hợp trên dưới dạng ký tự được đặt trước, nhưng cần được sử dụng theo nghĩa đen.
Ví dụ:
?được dùng trong URL để chỉ báo đầu chuỗi truy vấn; nếu muốn sử dụng chuỗi "? and the Mysterions", bạn cần mã hoá ký tự'?'.
Tất cả ký tự cần được mã hoá URL đều được mã hoá bằng ký tự '%' và giá trị thập lục phân gồm hai ký tự tương ứng với ký tự UTF-8 của chúng. Ví dụ: 上海+中國 trong UTF-8 sẽ được mã hoá URL thành %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. Chuỗi ? and the Mysterians sẽ được mã hoá URL dưới dạng %3F+and+the+Mysterians hoặc %3F%20and%20the%20Mysterians.
Các ký tự phổ biến cần mã hoá
Sau đây là một số ký tự phổ biến phải được mã hoá:
| Ký tự không an toàn | Giá trị được mã hoá |
|---|---|
| Không gian | %20 |
| " | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
Đôi khi, việc chuyển đổi URL mà bạn nhận được từ dữ liệu đầu vào của người dùng khá rắc rối. Ví dụ: người dùng có thể nhập địa chỉ là "5th&Main St." Nhìn chung, bạn nên tạo URL từ các phần của URL, coi mọi dữ liệu đầu vào của người dùng là ký tự cố định.
Ngoài ra, URL bị giới hạn ở 16384 ký tự đối với tất cả dịch vụ web và API web tĩnh của Google Maps Platform. Đối với hầu hết các dịch vụ, giới hạn ký tự này hiếm khi được áp dụng. Tuy nhiên, hãy lưu ý rằng một số dịch vụ có một số tham số có thể dẫn đến URL dài.