Các phương pháp hay nhất khi sử dụng dịch vụ web API xác thực địa chỉ

Dịch vụ web của Nền tảng Google Maps là tập hợp các giao diện HTTP tới các dịch vụ của Google cung cấp dữ liệu địa lý cho ứ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 cho việc thiết lập yêu cầu dịch vụ web và xử lý phản hồi dịch vụ. Hãy tham khảo hướng dẫn dành cho nhà phát triển để xem tài liệu đầy đủ về API xác thực địa chỉ.

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. Những dịch vụ này được thiết kế để sử dụng cùng với bản đồ, theo Các quy định 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 các 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 sẽ trả về dữ liệu trong nội dung phản hồi dưới dạng JSON để phân tích cú pháp và/hoặc xử lý của ứng dụng.

Xác thực địa chỉ bằng cách gửi yêu cầu HTTP POST đến phương thức validateAddress:

https://addressvalidation.googleapis.com/v1:validateAddress

Truyền nội dung JSON đến yêu cầu xác định địa chỉ để xác thực

Lưu ý: Tất cả các ứng dụng API Xác thực địa chỉ đề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 một URL "hợp lệ" là điều hiển nhiên, nhưng thực tế thì không phải vậy. Ví dụ: một 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 phải dịch nội bộ các ký tự đó sang một chế độ mã hoá khác trước khi truyền. Cũng như vậy, 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 chứa 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.

Thận trọng: Các trình duyệt và/hoặc dịch vụ có thể tự động mã hoá URL URL yêu cầu trước khi gửi. Trên các API sử dụng tính năng ký yêu cầu bằng mã hoá, điều này có thể sẽ vô hiệu hoá chữ ký nếu quá trình mã hoá URL thay đổi yêu cầu sau khi ký. Để tránh vấn đề này, hãy luôn mã hoá URL chuỗi truy vấn của bạn trước khi ký yêu cầu.

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 theo 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 con đặc biệt gồm các ký tự ASCII: ký hiệu chữ-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 9 6 7	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 xây dựng 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ự của URL hợp lệ. Việc định dạng một URL để sử dụng bộ ký tự này thường 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ý tồn tại bên ngoài tập hợp 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 cho 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 sử dụng chuỗi "? và Mysterions", 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 cách sử dụ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. 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á

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ã hóa
Khoảng trống	%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 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 URL đó, coi mọi dữ liệu do người dùng nhập là ký tự cố định.

Ngoài ra, URL được giới hạn ở 16384 ký tự đối với tất cả các dịch vụ web của 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 áp dụng. Tuy nhiên, xin lưu ý rằng một số dịch vụ có nhiều tham số có thể dẫn đến URL dài.

Sử dụng API Google theo cách lịch sự

Các ứng dụng API được thiết kế kém có thể gây ra mức tải nhiều hơn mức cần thiết trên cả Internet và máy chủ của Google. Phần này trình bày một số phương pháp hay nhất dành cho ứng dụng 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 việc ứng dụng bị chặn do vô tình lạm dụng các API.

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 lỗi trong khi thực hiện 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ể đơn giản là gặp lỗi ở nơi nào đó giữa ứng dụng của bạn 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, điều quan trọng là không chỉ lặp lại việc gửi 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 và Google, gây ra sự cố cho nhiều bên.

Một cách hiệu quả hơn là thử lại và tăng độ trễ giữa các lần thử. Thông thường, độ trễ sẽ được tăng theo 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 tới Time Zone API (API Múi giờ):

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

Ví dụ Python sau đây cho thấy cách đưa ra 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 cẩn thận để không thử lại mã cao hơn trong chuỗi lệnh gọi của ứng dụng, điều này dẫn đến các yêu cầu lặp lại liên tiếp.

Yêu cầu được đồng bộ hoá

Số lượng lớn các yêu cầu được đồng bộ hoá đối với các API của Google có thể giống như một cuộc tấn công Từ chối dịch vụ phân tán (DDoS) vào cơ sở hạ tầng của Google và sẽ được xử lý tương ứng. Để tránh điều này, bạn cầ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ụ: 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 của ứng dụng đánh thức chuông báo vào đầu phút để thời gian hiển thị có thể được cập nhật. Ứ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 quan đến 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 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 đầ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ế không tốt khi thực hiện việc này sẽ tạo ra lưu lượng truy cập tăng đột biến ở mức 60 lần mức bình thường vào đầu mỗi phút.

Thay vào đó, bạn nên đặt chuông báo thứ hai vào thời điểm đượ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 cần thiết và lưu trữ kết quả. Khi muốn cập nhật màn hình ngay từ đầu, ứ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 cách tiếp cận này, các lệnh gọi API sẽ trải đều theo thời gian. Ngoài ra, các lệnh gọi API không trì hoãn việc 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 điểm đồng bộ hóa phổ biến khác mà bạn nên cẩn thận không nhắm mục tiêu là thời điểm bắt đầu giờ và bắt đầu mỗi ngày vào lúc nửa đêm.

Đang xử lý câu trả lời

Lưu ý: Vì định dạng chính xác của từng phản hồi với một yêu cầu dịch vụ web không được đảm bảo (một số phần tử có thể bị thiếu hoặc ở nhiều vị trí), nên bạn không nên giả định rằng định dạng được trả về cho mọi phản hồi nhất định sẽ giống nhau đối với các truy vấn khác nhau. Thay vào đó, bạn nên xử lý phản hồi và chọn các giá trị thích hợp thông qua biểu thức.

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 rất dễ hiểu, nhưng không hoàn toàn 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ể. Nhìn chung, bạn nên phân tích cú pháp các phản hồi qua dịch vụ web và chỉ trích xuất các giá trị mà bạn quan tâm.

Lượ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ề đầu ra trong JSON hay không. Phản hồi JSON đã ở dạng đối tượng JavaScript có thể được xử lý ngay trong chính JavaScript trên ứng dụng.