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 để tạo ra những hình ảnh mà bạn có thể nhúng trực tiếp vào trang web của mình.
Các dịch vụ web của 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 cung cấp dữ liệu địa lý cho các ứng dụng bản đồ của bạn.
Hướng dẫn này mô tả một số phương pháp phổ biến giúp bạn thiết lập yêu cầu dịch vụ web và hình ảnh, cũng như 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 cho Chế độ xem đường phố.
API Tĩnh của Chế độ xem đường phố hoạt động như một API web tĩnh, trong khi dịch vụ siêu dữ liệu có thể được coi là một dịch vụ web. Để biết thêm thông tin về dịch vụ siêu dữ liệu, hãy đọc bài viết Siêu dữ liệu hình ảnh trong Chế độ xem đường phố.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 Google Maps vào trang web của mình mà không yêu cầu 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 tham số URL được gửi bằng yêu cầu HTTPS chuẩn.Thông thường, một yêu cầu API tĩnh cho Chế độ xem đường phố thường có dạng như sau:
https://www.googleapis.com/streetview/z/x/y?parameters
Dịch vụ web là gì?
Các dịch vụ web của Nền tảng Google Maps là một giao diện để yêu cầu dữ liệu API Maps từ các dịch vụ bên ngoài và sử dụng dữ liệu trong các ứng dụng Maps của bạn. Các dịch vụ này được thiết kế để dùng cùng với bản đồ, theo Giới hạn cấp phép trong Điều khoản dịch vụ của Nền tảng Google Maps.
Các dịch vụ web của API Maps sử dụng yêu cầu HTTP(S) cho những URL cụ thể, truyền tham số URL và/hoặc dữ liệu POST ở định dạng JSON làm đối số cho dịch vụ. Nhìn chung, các dịch vụ này trả về dữ liệu trong nội dung phản hồi dưới dạng JSON để ứng dụng của bạn phân tích cú pháp và/hoặc xử lý.
Yêu cầu Siêu dữ liệu API tĩnh cho Chế độ xem đường phố có dạng như sau:https://maps.googleapis.com/maps/api/streetview/parameters
Lưu ý: Tất cả ứng dụng API tĩnh dành cho Chế độ xem đường phố đều yêu cầu xác thực. Xem thêm thông tin về thông tin xác thực.
Truy cập SSL/TLS
HTTPS là yêu cầu 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. Những yêu cầu được thực hiện qua HTTP chứa dữ liệu nhạy cảm có thể bị từ chối.
Tạo URL hợp lệ
Có thể bạn cho rằng một URL "hợp lệ" là điều hiển nhiên, nhưng điều đó không đúng. Ví dụ: URL được nhập trong 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 kiểu mã hoá khác trước khi truyền.
Tương tự như vậy, mọi mã tạo hoặc chấp nhận dữ liệu đầu vào UTF-8 có thể coi 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ỉ được chứa một tập hợp con ký tự ASCII đặc biệt: 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ự | 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 | 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 | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | 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ự hiển thị trong bảng. Việc tạo một URL để sử dụng tập hợp ký tự này thường dẫn đến 2 vấn đề, một là bị bỏ sót và một là bị thay thế:
- Các ký tự bạn muốn xử lý tồn tại ngoài
nhóm ở trên. Ví dụ: bạn cần mã hoá các ký tự bằng tiếng nước ngoài như
上海+中國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 nêu 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 điểm bắt đầu của chuỗi truy vấn; nếu muốn dùng chuỗi "? và Chuỗi ẩn số", bạn cần mã hoá ký tự'?'.
Tất cả các ký tự cần 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 dưới dạng %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. Chuỗi ? and the Mysterians sẽ được mã hoá URL thành %3F+and+the+Mysterians hoặc %3F%20and%20the%20Mysterians.
Các ký tự phổ biến cần 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 một URL mà bạn nhận được từ hoạt động đầu vào của người dùng đôi khi khá phức tạp. 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 hoạt động đầu vào của người dùng là các ký tự cố định.
Ngoài ra, URL chỉ được có tối đa 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ụ, hiếm khi đạt đến giới hạn ký tự này. Tuy nhiên, hãy lưu ý rằng một số dịch vụ nhất định có một số tham số có thể dẫn đến URL dài.
Sử dụng lịch sự các API của Google
Các ứng dụng API được thiết kế kém có thể khiến cả Internet và máy chủ của Google phải tải nhiều hơn mức cần thiết. Phần này trình bày một số phương pháp hay nhất dành cho các ứng dụng khách sử dụng API. Khi làm theo các phương pháp hay nhất này, bạn có thể tránh việc ứng dụng của mình bị chặn do vô tình sử dụng API sai cách.
Thuật toán thời gian đợi luỹ thừa
Trong một số ít trường hợp, có thể xảy ra sự cố khi phân phát yêu cầu của bạn; bạn có thể nhận được mã phản hồi HTTP 4XX hoặc 5XX hoặc đơn giản là kết nối TCP không thành công ở đâu đó giữa ứng dụng khách và máy chủ của Google. Thông thường, bạn nên thử lại yêu cầu vì yêu cầu tiếp theo có thể thành công khi yêu cầu ban đầu không thành công. Tuy nhiên, bạn không nên chỉ lặp đi lặp lại các yêu cầu đến máy chủ của Google. Hành vi lặp lại này có thể làm quá tải mạng giữa ứng dụng của bạn và Google, gây ra sự cố cho nhiều bên.
Cách tốt hơn là thử lại với độ trễ tăng dần giữa các lần thử. Thông thường, độ trễ được tăng lên bằng một hệ số nhân với mỗi lần thử, một phương pháp được gọi là Thời gian đợi luỹ thừa.
Ví dụ: hãy xem xét một ứng dụng muốn gửi yêu cầu này đến API Múi giờ:
https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510×tamp=1331161200&key=YOUR_API_KEY
Ví dụ sau đây trong Python cho thấy cách tạo yêu cầu bằng thuật toán thời gian đợi luỹ thừa:
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}")
Bạn cũng nên lưu ý rằng không có mã thử lại nào cao hơn trong chuỗi lệnh gọi ứng dụng dẫn đến các yêu cầu lặp lại liên tiếp nhanh chóng.
Yêu cầu đã đồng bộ hoá
Số lượng lớn các yêu cầu được đồng bộ hoá với các API của Google có thể trông giống như một cuộc tấn công Từ chối dịch vụ phân tán (DDoS) nhằm vào cơ sở hạ tầng của Google và được xử lý tương ứng. Để tránh tình trạng này, bạn phải đảm bảo rằng các yêu cầu API không được đồng bộ hoá giữa các ứng dụng.
Ví dụ: hãy xem xét một ứng dụng hiển thị thời gian theo múi giờ hiện tại. Ứng dụng này có thể sẽ đặt chuông báo trong hệ điều hành ứng dụng khi đánh thức chuông báo vào đầu phút để có thể cập nhật thời gian hiển thị. Ứng dụng không được thực hiện bất kỳ lệnh gọi API nào trong quá trình xử lý liên kết với chuông báo đó.
Việc thực hiện lệnh gọi API để phản hồi một chuông báo cố định sẽ không tốt vì việc này dẫn đến việc các lệnh gọi API được đồng bộ hoá vào thời điểm bắt đầu phút, ngay cả giữa các thiết bị khác nhau, thay vì được phân phối đồng đều theo thời gian. Một ứng dụng được thiết kế kém làm việc này sẽ tạo ra mức tăng đột biến về lưu lượng truy cập ở mức bình thường 60 lần khi bắt đầu mỗi phút.
Thay vào đó, bạn nên đặt chuông báo thứ hai theo thời gian được chọn ngẫu nhiên. Khi chuông báo thứ hai này kích hoạt, ứng dụng sẽ gọi bất kỳ API nào mà ứng dụng cần và lưu trữ kết quả. Khi muốn cập nhật màn hình ngay từ đầu phút, ứng dụng sẽ sử dụng các kết quả đã lưu trữ trước đó thay vì gọi lại API. Với phương pháp này, các lệnh gọi API được trải đều theo thời gian. Ngoài ra, các lệnh gọi API không trì hoãn quá trình kết xuất khi màn hình đang được cập nhật.
Ngoài thời điểm bắt đầu phút, các thời gian đồng bộ hoá phổ biến khác mà bạn không nên cẩn thận nhắm mục tiêu là vào đầu một giờ và bắt đầu mỗi ngày vào lúc nửa đêm.
Đang xử lý câu trả lời
Phần này thảo luận cách trích xuất các giá trị này một cách linh động từ phản hồi của dịch vụ web.
Các dịch vụ web của Google Maps cung cấp câu trả lời dễ hiểu, nhưng không thân thiện với người dùng. Khi thực hiện một truy vấn, thay vì hiển thị một tập dữ liệu, bạn nên trích xuất một vài giá trị cụ thể. Thông thường, bạn sẽ muốn phân tích cú pháp các phản hồi từ dịch vụ web và chỉ trích xuất những giá trị mà bạn quan tâm.
Giao thức phân tích cú pháp mà bạn sử dụng phụ thuộc vào việc bạn có trả về kết quả ở định dạng JSON hay không. Phản hồi JSON vốn đã ở dạng đối tượng JavaScript, có thể được xử lý ngay trong JavaScript trên ứng dụng.