API web tĩnh trên Nền tảng Google Maps là một tập hợp các giao diện HTTP với các dịch vụ của Google nhằm tạo ra hình ảnh mà bạn có thể nhúng trực tiếp trên 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 yêu cầu hình ảnh và xử lý phản hồi của dịch vụ. Tham khảo hướng dẫn dành cho nhà phát triển để xem tài liệu đầy đủ về API tĩnh của Maps.
API web tĩnh là gì?
API web tĩnh của Nền tảng Google Maps cho phép bạn nhúng hình ảnh trên Google Maps vào trang web của mình mà không cần JavaScript hoặc bất kỳ hoạt độ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 chuẩn.Yêu cầu API tĩnh của Maps thường có dạng sau:
https://www.googleapis.com/staticmap/z/x/y?parameters
Lưu ý: Tất cả ứng dụng API tĩnh của Maps đều yêu cầu xác thực. Tìm hiểu thêm thông tin về thông tin xác thực.
Truy cập SSL/TLS
HTTPS là bắt buộc đối với tất cả các yêu cầu trên Nền tảng Google Maps sử dụng khoá API hoặc chứa dữ liệu người dùng. Các yêu cầu được thực hiện qua HTTP có 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ể cho rằng URL "hợp lệ" là tự hiển nhiên, nhưng điều này không đúng. Ví dụ: một URL được nhập vào thanh địa chỉ trong 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ự đó sang một chế độ mã hoá khác trước khi truyền.
Cũng giống như mã thông báo, mọi mã tạo hoặc chấp nhận dữ liệu đầu vào UTF-8 đều có thể coi các URL có ký tự UTF-8 là "hợp lệ", nhưng cũng cần phải dịch các ký tự đó trước khi gửi đến máy chủ web.
Quá trình này gọi là
mã hoá URL hoặc mã hoá phần trăm.
Các ký tự đặc biệt
Chúng tôi cần dịch các ký tự đặc biệt vì tất cả URL đều phải tuân thủ cú pháp được chỉ định trong thông số kỹ thuật Mã nhận dạng tài nguyên đồng nhất (URI). Trên thực tế, điều này có nghĩa là URL chỉ phải chứa một tập con các ký tự ASCII đặc biệt: các ký hiệu chữ và số quen thuộc và một số ký tự dành riêng để dùng làm ký tự điều khiển trong URL. Bảng này tóm tắt các ký tự sau:
| Đặt | ký tự | Việ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 | Chuỗi văn bản, cách sử dụng lược đồ (http), cổng (8080), v.v. |
| Không dành riêng | - _ . ~ | Chuỗi văn bản |
| Đã đặt trước | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Ký tự điều khiển 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 Tóm tắt các ký tự URL hợp lệ. Việc cấu thành một URL để sử dụng bộ ký tự này thường sẽ dẫn đến hai vấn đề, một là bỏ sót và một là bị thay thế:
- Các ký tự mà bạn muốn xử lý nằm ngoài nhóm trên. Ví dụ: các ký tự bằng tiế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 cho phép trong URL) thường được biểu thị bằng ký tự dấu cộng'+'. - Các ký tự nằm trong tập hợp trên dưới dạng ký tự dành riêng, nhưng cần được sử dụng theo nghĩa đen.
Ví dụ:
?được dùng trong các URL để cho biết phần đầu của chuỗi truy vấn; nếu muốn sử dụng chuỗi "? và Mysterions", bạn cần mã hoá ký tự'?'.
Tất cả các ký tự được mã hoá URL đều được mã hoá bằng ký tự '%' và một giá trị hex gồm hai ký tự tương ứng với ký tự UTF-8. 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 được mã hoá
Một số ký tự phổ biến phải được mã hoá là:
| 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ừ hoạt động đầu vào của người dùng sẽ rất khó khăn. 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 nó, coi mọi hoạt động đầu vào của người dùng là các ký tự cố định.
Ngoài ra, các URL cũng được giới hạn ở 16384 ký tự đối với tất cả các dịch vụ web và API web tĩnh trên Nền tảng Google Maps. Đố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, xin lưu ý rằng một số dịch vụ có một số tham số có thể dẫn đến URL dài.