Hãy tham gia Ngày cộng đồng nhà phát triển Google Maps Platform tiếp theo của chúng tôi tại San Francisco vào tháng 12! Đăng ký ngay để tham dự.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Các phương pháp hay nhất khi sử dụng Street View Static API

Là một tập hợp các giao diện HTTP, API web tĩnh của Google Maps Platform tạo ra hình ảnh để nhúng trực tiếp vào trang web của bạn.

Các dịch vụ web của Google Maps Platform là một tập hợp các giao diện HTTP 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 cho việc thiết lập yêu cầu về hình ảnh và dịch vụ web, cũng như xử lý phản hồi của dịch vụ. Để biết thêm thông tin về Street View Static API, hãy xem hướng dẫn dành cho nhà phát triển.

Street View Static API hoạt động giống như một API web tĩnh, trong khi dịch vụ siêu dữ liệu hoạt động như một dịch vụ web. Để biết thêm thông tin về dịch vụ siêu dữ liệu, hãy xem phần 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 Google Maps Platform cho phép bạn nhúng hình ảnh 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. Các 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.

Một yêu cầu API thông thường về Chế độ xem đường phố tĩnh có dạng như sau:

  https://www.googleapis.com/streetview/z/x/y?parameters

Dịch vụ web là gì?

Dịch vụ web của Google Maps Platform 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 Các quy định hạn chế về giấy phép trong Điều khoản dịch vụ của Google Maps Platform.

Dịch vụ web của API Maps sử dụng các yêu cầu HTTP hoặc HTTPS đến các URL cụ thể, truyền tham số URL 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 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 hoặc xử lý.

Yêu cầu siêu dữ liệu của Chế độ xem đường phố Static API có dạng như sau:

https://maps.googleapis.com/maps/api/streetview/parameters

Quyền truy cập SSL và TLS

Bạn phải sử dụng HTTPS cho tất cả các yêu cầu của Google Maps Platform có 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ể nghĩ rằng một URL "hợp lệ" là điều hiển nhiên, nhưng không hẳn như 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 phương thức 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 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á 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 đều phải tuân thủ cú pháp được chỉ định trong quy cách của Giá trị 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: các ký hiệu chữ và số quen thuộc, cùng 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óm tắt các ký tự hợp lệ trong URL

Đặ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 8 9	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 những ký tự có trong bảng. Việc điều chỉnh URL để sử dụng tập hợp ký tự này thường dẫn đến hai vấn đề, một là bỏ sót và một là thay thế:

Các ký tự mà bạn muốn xử lý nằm ngoài tập hợp nêu 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ự nêu trên. Theo quy ước phổ biến, dấu cách (không được phép trong URL) 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ự đặt trước, nhưng cần được sử dụng theo nghĩa đen. Ví dụ: ? được dùng trong URL để cho biết phần đầu của 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ả các ký tự đượ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 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 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à:

Nhân vậ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 có thể gặp 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 đầu vào của người dùng là ký tự cố định.

Ngoài ra, URL bị giới hạn ở 16.384 ký tự cho 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 đạt đến. 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.

Sử dụng API của Google một cách hợp lý

Các ứng dụng API được thiết kế kém có thể gây tải nặng cho Internet và máy chủ. Phần này trình bày các 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 ứng dụng của bạn không bị chặn do vô tình sử dụng sai 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 sự cố với 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ể không thành công ở đâu đó 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, bạn không nên gửi yêu cầu nhiều lần đế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ử. Độ trễ thường tăng theo hệ số nhân sau mỗi lần thử, một phương pháp được gọi là thuật toán thời gian đợi tăng theo cấp luỹ thừa.

Ví dụ: hãy xem xét một ứng dụng đưa ra yêu cầu này cho Time Zone API:

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

Ví dụ về Python sau đây cho thấy cách thực hiện 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 in the following code 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 the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry 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 on each retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Đảm bảo 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ộ

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

Thay vào đó, bạn có thể thiết kế ứng dụng để có chuông báo thứ hai được đặt thành một 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 mọi API cần thiết và lưu trữ kết quả. Khi ứng dụng cập nhật màn hình vào đầu phút, ứng dụng sẽ sử dụng 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 phân bổ đều theo thời gian. Hơn nữa, các lệnh gọi API không làm chậm quá trình kết xuất khi màn hình cập nhật.

Ngoài thời điểm bắt đầu phút, đừng nhắm đến các thời điểm đồng bộ hoá phổ biến khác, chẳng hạn như thời điểm bắt đầu giờ và thời điểm bắt đầu mỗi ngày vào lúc nửa đêm.

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

Vì không thể đảm bảo định dạng chính xác của từng phản hồi cho một yêu cầu dịch vụ web (một số phần tử có thể bị thiếu hoặc nằm ở nhiều vị trí), nên đừng cho rằng định dạng được trả về cho bất kỳ phản hồi cụ thể nào cũng giống nhau đối với các truy vấn khác nhau. Thay vào đó, hãy xử lý phản hồi và chọn các giá trị thích hợp bằng cách sử dụng 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 phản hồi dễ hiểu nhưng không 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, hãy 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.

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ề 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ý trong chính JavaScript trên máy khách.