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 cho 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 hữu ích để thiết lập yêu cầu dịch vụ web 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 toàn bộ tài liệu về API Chỉ đường.
Dịch vụ web là gì?
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ế để sử dụng cùng với bản đồ, theo Hạn chế về giấy phép trong Điều khoản dịch vụ của Nền tảng Google Maps.
Dịch vụ web của API Maps sử dụng yêu cầu HTTP(S) đến URL cụ thể, chuyển tham số URL và/hoặc dữ liệu POST định dạng JSON làm đối số cho các dịch vụ. Nhìn chung, các dịch vụ này trả về dữ liệu trong yêu cầu HTTP(S) dưới dạng JSON hoặc XML để phân tích cú pháp và/hoặc xử lý bằng ứng dụng của bạn.
Yêu cầu thông thường của API Chỉ đường thường có dạng sau:
https://maps.googleapis.com/maps/api/directions/output?parameters
trong đó output cho biết định dạng phản hồi (thường là json hoặc xml).
Lưu ý: Tất cả các ứng dụng API Chỉ đường đề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
Bạn bắt buộc phải sử dụng HTTPS cho tất cả các yêu cầu Nền tảng Google Maps sử dụng khoá API hoặc chứa dữ liệu người dùng. Yêu cầu được gửi 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ể nghĩ rằng một "hợp lệ" URL rõ ràng, nhưng
không hoàn toàn đúng. Ví dụ: URL được nhập vào thanh địa chỉ trong một 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 mã hoá khác trước khi truyền.
Tương tự như vậy, mọi mã tạo ra hoặc chấp nhận dữ liệu nhập UTF-8 đều có thể coi các URL có ký tự UTF-8 là "valid" 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 gọi là mã hóa URL hay mã hóa 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ả các URL đều phải tuân thủ cú pháp đã 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 đặc biệt gồm các ký tự ASCII: ký hiệu chữ và số quen thuộc và một số ký tự dành riêng để sử 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ự | Tình trạng 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 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 chỗ | ! * ? % # [ ] | Kiểm soát các ký tự và/hoặc Chuỗi văn bản |
Khi tạo 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 Tóm tắt các ký tự URL hợp lệ. Thông thường, việc tạo URL để sử dụng bộ ký tự này thường dẫn đến hai vấn đề: một nội dung bỏ sót và một nội dung thay thế:
- Ký tự mà bạn muốn xử lý tồn tại bên ngoài tập hợp ở 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 phép trong URL) cũng được biểu thị bằng ký tự dấu cộng'+'. - Ký tự tồn tại trong bộ ký tự ở trên được đặt là ký tự dành riêng, nhưng cần được sử dụng theo nghĩa đen.
Ví dụ:
?được sử dụng trong các URL để cho biết phần đầu của chuỗi truy vấn; nếu bạn muốn sử dụng chuỗi "; và Mysterions," bạn cần mã hóa ký tự'?'.
Tất cả ký tự cần mã hoá URL đều được mã hoá bằng ký tự '%' và giá trị hex hai ký tự tương ứng với ký tự UTF-8 của các ký tự đó. Ví dụ: 上海+中國 trong UTF-8 sẽ được mã hoá URL là %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.
Ký tự phổ biến cần mã hóa
Một số ký tự phổ biến phải được mã hóa là:
| Ký tự không an toàn | Giá trị được mã hoá |
|---|---|
| Vũ trụ | %20 |
| ". | %22 |
| Gần | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
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 rất khó khăn. Ví dụ: người dùng có thể nhập một địa chỉ dưới dạng "5th&Main St." Thông thường, bạn nên tạo URL từ các phần của URL, coi mọi thao tác nhập của người dùng là các ký tự chữ.
Ngoài ra, URL được giới hạn ở 8192 ký tự đối với mọi dịch vụ web trên Nền tảng Google Maps và API web tĩnh. Đối với hầu hết các dịch vụ, giới hạn ký tự này hiếm khi được đạt. Tuy nhiên, hãy lưu ý rằng một số dịch vụ có một vài tham số có thể dẫn đến URL dài.
Sử dụng API của Google một cách lịch sự
Các ứng dụng API được thiết kế kém có thể khiến tải nhiều hơn mức cần thiết trên cả máy chủ Internet và máy chủ của Google. Phần này chứa một số phương pháp hay nhất dành cho khách hàng của API. Việc làm theo các phương pháp hay nhất này có thể giúp bạn tránh trường hợp ứng dụng của bạn bị chặn do vô tình sử dụng các API.
Thời gian đợi luỹ thừa
Trong một số ít trường hợp, có thể lỗi trong quá trình 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 kết nối TCP có thể chỉ bị lỗi giữa máy khách và máy chủ của Google. Thông thường, bạn nên thử gửi 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, điều quan trọng là bạn không chỉ đơn giản là lặp lại yêu cầu tới 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 khách 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 lên giữa các lần thử. Thông thường, độ trễ sẽ tăng thêm một hệ số nhân với mỗi lần thử, một phương pháp được gọi là Độ trễ thời gian chờ.
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ụ Python sau đây cho thấy cách thực hiện yêu cầu với 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 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.
Yêu cầu được đồng bộ hóa
Một số lượng lớn yêu cầu được đồng bộ hoá tớ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) trên cơ sở hạ tầng của Google và được xử lý tương ứng. Để tránh điều này, bạn nên đả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ụ: 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 máy khách để đánh thức ứng dụng đó vào đầu phút nhằm cập nhật thời gian hiển thị. Ứng dụng không được gọi 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 là không hợp lệ vì việc này dẫn đến các lệnh gọi API được đồng bộ hoá với thời điểm đầ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 hiệu quả sẽ mang lại mức tăng đột biến về lưu lượng truy cập ở mức 60 lần thông thường vào đầu mỗi phút.
Thay vào đó, bạn nên đặt chuông báo thứ hai thành thời gian đã 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ữ các kết quả. Khi muốn cập nhật màn hình vào đầ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 sẽ đượ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 gian bắt đầu phút, các thời điểm đồng bộ hoá phổ biến khác mà bạn nên cẩn thận là vào đầu giờ bắt đầu và bắt đầu mỗi ngày lúc nửa đêm.
Xử lý phản hồi
Phần này thảo luận cách trích xuất động các giá trị này từ phản hồi của dịch vụ web.
Dịch vụ web của Google Maps cung cấp phản hồi dễ hiểu, nhưng không chính xác để thân thiện với người dùng. Khi thực hiện truy vấn, thay vì hiển thị một tập dữ liệu, bạn có thể muốn trích xuất một vài giá trị cụ thể. Nhìn chung, bạn nên phân tích cú pháp 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 đang trả về kết quả ở định dạng XML hay JSON. Phản hồi JSON (đã ở dạng đối tượng JavaScript) có thể được xử lý ngay trong JavaScript trên máy khách. Hệ thống cần xử lý phản hồi XML bằng cách sử dụng trình xử lý XML và một ngôn ngữ truy vấn XML để giải quyết các phần tử trong định dạng XML. Chúng tôi sử dụng XPath trong các ví dụ sau vì nó thường được hỗ trợ trong các thư viện xử lý XML.
Xử lý XML bằng XPath
XML là một định dạng thông tin có cấu trúc tương đối phù hợp để trao đổi dữ liệu. Mặc dù không nặng như JSON, nhưng XML
cung cấp khả năng hỗ trợ nhiều ngôn ngữ hơn và các công cụ mạnh mẽ hơn. Ví dụ: mã để xử lý XML trong Java sẽ được tích hợp vào các gói javax.xml.
Khi xử lý các phản hồi XML, bạn nên sử dụng ngôn ngữ truy vấn thích hợp để chọn các nút trong tài liệu XML, thay vì giả định các phần tử nằm ở các vị trí tuyệt đối trong mã đánh dấu XML. XPath là một cú pháp ngôn ngữ để mô tả riêng các nút và phần tử trong một tài liệu XML. Biểu thức XPath cho phép bạn xác định nội dung cụ thể trong tài liệu phản hồi XML.
Biểu thức XPath
Một số kiến thức quen thuộc với XPath rất hữu ích trong việc phát triển lược đồ phân tích cú pháp hữu hiệu. Phần này sẽ tập trung vào cách các phần tử trong tài liệu XML được xử lý bằng XPath, cho phép bạn xử lý nhiều phần tử và tạo các truy vấn phức tạp.
XPath sử dụng biểu thức để chọn các phần tử trong tài liệu XML, sử dụng cú pháp tương tự như cú pháp dùng cho các đường dẫn thư mục. Các biểu thức này xác định các phần tử trong cây tài liệu XML, đây là một cây phân cấp tương tự như cây DOM. Nhìn chung, biểu thức XPath trở nên tham số, cho biết rằng chúng sẽ khớp với tất cả các nút khớp với tiêu chí đã cung cấp.
Chúng tôi sẽ sử dụng XML trừu tượng sau để minh hoạ ví dụ:
<WebServiceResponse> <status>OK</status> <result> <type>sample</type> <name>Sample XML</name> <location> <lat>37.4217550</lat> <lng>-122.0846330</lng> </location> </result> <result> <message>The secret message</message> </result> </WebServiceResponse>
Lựa chọn nút trong biểu thức
Các lựa chọn XPath chọn nút. Nút gốc bao gồm toàn bộ tài liệu. Bạn chọn nút này bằng cách sử dụng biểu thức đặc biệt "/" lưu ý rằng nút gốc không phải là nút cấp cao nhất của tài liệu XML; trên thực tế, nút này nằm trên một cấp cao hơn phần tử cấp cao nhất và bao gồm cả nút đó.
Các nút phần tử đại diện cho các phần tử khác nhau trong cây tài liệu XML. Ví dụ: một phần tử <WebServiceResponse> đại diện cho phần tử cấp cao nhất được trả về trong dịch vụ mẫu của chúng tôi ở trên. Bạn chọn các nút riêng lẻ thông qua
đường dẫn tuyệt đối hoặc tương đối, được biểu thị bằng sự hiện diện hoặc
không có ký tự "/" đứng đầu.
- Đường dẫn tuyệt đối: biểu thức "
/WebServiceResponse/result" chọn tất cả các nút<result>là nút con của nút<WebServiceResponse>. (Xin lưu ý rằng cả hai phần tử này đều thuộc phần gốc của nút gốc "/".) - Đường dẫn tương đối từ ngữ cảnh hiện tại: biểu thức
"
result" sẽ khớp với mọi phần tử<result>trong ngữ cảnh hiện tại. Nhìn chung, bạn không cần phải lo lắng về ngữ cảnh, vì bạn thường xử lý kết quả dịch vụ web thông qua một biểu thức duy nhất.
Cả hai biểu thức này đều có thể được tăng cường thông qua việc thêm
đường dẫn ký tự đại diện, được biểu thị bằng dấu gạch chéo đôi ("//".
Ký tự đại diện này cho biết rằng không có hoặc nhiều phần tử có thể khớp trong đường dẫn can thiệp). Biểu thức XPath "//formatted_address,"
ví dụ: sẽ khớp với tất cả các nút của tên đó trong tài liệu hiện tại.
Biểu thức //viewport//lat sẽ khớp với tất cả các phần tử <lat> có thể theo dõi <viewport> dưới dạng mẹ.
Theo mặc định, biểu thức XPath khớp với tất cả các phần tử. Bạn có thể hạn chế biểu thức để khớp với một phần tử nhất định bằng cách cung cấp một đơn vị tổ chức, được đặt trong dấu ngoặc vuông ([]). Biểu thức "giá trị XPath;/GeocodeResponse/result[2] luôn trả về kết quả thứ hai.
| Loại biểu thức | |
|---|---|
| Root node | Biểu thức XPath: "
/"Lựa chọn:
<WebServiceResponse>
<status>OK</status>
<result>
<type>sample</type>
<name>Sample XML</name>
<location>
<lat>37.4217550</lat>
<lng>-122.0846330</lng>
</location>
</result>
<result>
<message>The secret message</message>
</result>
</WebServiceResponse>
|
| Đường dẫn tuyệt đối | Biểu thức XPath: "
/WebServiceResponse/result"Lựa chọn:
<result>
<type>sample</type>
<name>Sample XML</name>
<location>
<lat>37.4217550</lat>
<lng>-122.0846330</lng>
</location>
</result>
<result>
<message>The secret message</message>
</result>
|
| Đường dẫn có ký tự đại diện | Biểu thức XPath: "
/WebServiceResponse//location"Lựa chọn:
<location>
<lat>37.4217550</lat>
<lng>-122.0846330</lng>
</location>
|
| Đường dẫn có thuộc tính | Biểu thức XPath: "
/WebServiceResponse/result[2]/message"Lựa chọn:
<message>The secret message</message>
|
Tất cả phần tử con trực tiếp của result đầu tiên |
Biểu thức XPath: "
/WebServiceResponse/result[1]/*"Lựa chọn:
<type>sample</type>
<name>Sample XML</name>
<location>
<lat>37.4217550</lat>
<lng>-122.0846330</lng>
</location>
|
name của result có văn bản type là "sample." |
Biểu thức XPath: "
/WebServiceResponse/result[type/text()='sample']/name"Lựa chọn:
Sample XML
|
Điều quan trọng cần lưu ý là khi chọn các phần tử, bạn cần chọn các nút, chứ không chỉ văn bản trong các đối tượng đó. Nhìn chung, bạn nên lặp lại tất cả các nút trùng khớp và trích xuất văn bản. Bạn cũng có thể so khớp trực tiếp các nút văn bản; xem phần Nút văn bản bên dưới.
Hãy lưu ý rằng XPath cũng hỗ trợ các nút thuộc tính; tuy nhiên, tất cả dịch vụ web của Google Maps đều phân phát các phần tử không có thuộc tính nên không cần thiết phải so khớp các thuộc tính.
Lựa chọn văn bản trong biểu thức
Văn bản trong tài liệu XML được chỉ định trong biểu thức XPath
thông qua toán tử nút văn bản. Toán tử "text()"
cho biết việc trích xuất văn bản từ nút đã chỉ định. Chẳng hạn, biểu thức XPath "//formatted_address/text()" sẽ trả về tất cả văn bản trong các phần tử <formatted_address>.
| Loại biểu thức | |
|---|---|
| Tất cả các nút văn bản (bao gồm cả khoảng trắng) | Biểu thức XPath: "
//text()"Lựa chọn:
sample
Sample XML
37.4217550
-122.0846330
The secret message
|
| Lựa chọn văn bản | Biểu thức XPath: "
/WebServiceRequest/result[2]/message/text()"Lựa chọn:
The secret message
|
| Lựa chọn nhạy cảm theo ngữ cảnh | Biểu thức XPath: "
/WebServiceRequest/result[type/text() = 'sample']/name/text()"Lựa chọn:
Sample XML
|
Ngoài ra, bạn có thể đánh giá một biểu thức và trả về một tập hợp các nút, sau đó lặp lại tập hợp "nút +" trích xuất văn bản từ mỗi nút. Chúng tôi sử dụng phương pháp này trong ví dụ bên dưới.
Để biết thêm thông tin về XPath, hãy tham khảo Đặc tả W3C XPath.
Đánh giá XPath trong Java
Java có hỗ trợ rộng rãi để phân tích cú pháp XML và sử dụng biểu thức XPath trong gói javax.xml.xpath.*.
Chính vì vậy, mã mẫu trong phần này sử dụng Java để minh hoạ cách xử lý XML và phân tích cú pháp dữ liệu từ các phản hồi dịch vụ XML.
Để sử dụng XPath trong mã Java của mình, trước tiên, bạn cần tạo bản sao của một XPathFactory và gọi newXPath() trên nhà máy đó để tạo một đối tượng XPath
. Sau đó, đối tượng này có thể xử lý các biểu thức XML và XPath đã chuyển bằng cách sử dụng phương thức evaluate().
Khi đánh giá các biểu thức XPath, hãy đảm bảo rằng bạn lặp lại
bất kỳ &bộ công cụ nào có thể được trả về. Vì các kết quả này được trả về dưới dạng nút DOM trong mã Java, nên bạn nên thu thập nhiều giá trị như vậy trong một đối tượng NodeList và lặp lại trên đối tượng đó để trích xuất bất kỳ văn bản hoặc giá trị nào từ các nút đó.
Mã sau đây minh hoạ cách tạo một đối tượng XPath, gán đối tượng XML và biểu thức XPath, đồng thời đánh giá biểu thức để in nội dung liên quan.
import org.xml.sax.InputSource;
import org.w3c.dom.*;
import javax.xml.xpath.*;
import java.io.*;
public class SimpleParser {
public static void main(String[] args) throws IOException {
XPathFactory factory = XPathFactory.newInstance();
XPath xpath = factory.newXPath();
try {
System.out.print("Web Service Parser 1.0\n");
// In practice, you'd retrieve your XML via an HTTP request.
// Here we simply access an existing file.
File xmlFile = new File("XML_FILE");
// The xpath evaluator requires the XML be in the format of an InputSource
InputSource inputXml = new InputSource(new FileInputStream(xmlFile));
// Because the evaluator may return multiple entries, we specify that the expression
// return a NODESET and place the result in a NodeList.
NodeList nodes = (NodeList) xpath.evaluate("XPATH_EXPRESSION", inputXml, XPathConstants.NODESET);
// We can then iterate over the NodeList and extract the content via getTextContent().
// NOTE: this will only return text for element nodes at the returned context.
for (int i = 0, n = nodes.getLength(); i < n; i++) {
String nodeString = nodes.item(i).getTextContent();
System.out.print(nodeString);
System.out.print("\n");
}
} catch (XPathExpressionException ex) {
System.out.print("XPath Error");
} catch (FileNotFoundException ex) {
System.out.print("File Error");
}
}
}