使用 Street View Static API 的最佳做法

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Google Maps Platform 静态 Web API 是 Google 服务的 HTTP 接口集合,可生成可直接嵌入到网页上的图片。

Google Maps Platform 网络服务是 Google 服务的 HTTP 接口集合,为您的地图应用提供地理数据。

本指南介绍了一些有助于设置映像和网络服务请求以及处理服务响应的常见做法。如需查看 Street View Static API 的完整文档,请参阅开发者指南

Street View Static API 的行为类似于静态 Web API,而元数据服务则可以被视为网络服务。如需详细了解元数据服务,请参阅街景图片元数据

什么是静态 Web API?

借助 Google Maps Platform 静态网络 API,您无需使用 JavaScript 或加载任何动态页面,即可在网页上嵌入 Google 地图图片。API 会根据通过标准 HTTP 请求发送的网址参数创建图片,并允许您在网页上显示结果。

典型的 Street View Static API 请求通常采用以下格式:

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

什么是网络服务?

Google Maps Platform 网络服务接口可用于从外部服务请求 Maps API 数据,并在地图应用中使用这些数据。根据 Google Maps Platform 服务条款中的许可限制,这些服务应与地图一起使用。

Maps API 网络服务使用 HTTP(S) 请求的特定网址,并将网址参数和/或 JSON 格式的 POST 数据作为参数传递给服务。通常,这些服务会在 HTTP(S) 请求中返回 JSON 格式的数据,以便您的应用进行解析和/或处理。

Street View Static API 元数据请求的格式如下:

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

注意:所有 Street View Static API 应用都需要进行身份验证。 详细了解身份验证凭据

SSL/TLS 访问

使用 API 密钥或包含用户数据的所有 Google Maps Platform 请求都需要使用 HTTPS。通过 HTTP 发出的包含敏感数据的请求可能会被拒绝。

构建有效网址

您可能认为“有效”网址不言自明,但实际并非如此。例如,在浏览器地址栏中输入的网址可能包含特殊字符(例如 "上海+中國");浏览器需要先在内部将这些字符转换为其他编码,然后再进行传输。同样,任何生成或接受 UTF-8 输入的代码都可能会将包含 UTF-8 字符的网址视为“有效”,但同样需要先转换这些字符,然后再将其发送给网络服务器。该过程称为网址编码百分号编码

特殊字符

我们之所以需要转换特殊字符,是因为所有网址都需要符合统一资源标识符 (URI) 规范所规定的语法。实际上,这意味着网址必须只包含一个特殊的 ASCII 字符子集:熟悉的字母数字符号以及一些在网址内用作控制字符的预留字符。下表汇总了这些字符:

有效网址字符摘要
字符集字符在网址中的用法
字母数字 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 文本字符串、架构用法 (http)、端口 (8080) 等
未预留 - _。~ 文本字符串
预留 ! * ' ( ) ; : @ & = + $ , / ? % [ ] 控制字符和/或文本字符串

构建有效网址时,您必须确保网址只包含“有效网址字符摘要”表格中显示的那些字符。让网址按照上述字符集使用字符通常会带来两个问题,一个是遗漏问题,一个是替换问题:

  • 您要处理的字符未包含在上述字符集内。例如,外语字符(例如 上海+中國)需要使用上述字符进行编码。按照常见惯例,空格(网址内不允许使用空格)通常也使用加号字符 '+' 表示。
  • 字符以预留字符的形式存在于上述字符集内,但需要按原义使用。例如,? 在网址内用于表示查询字符串的开头;如果您想要使用字符串“? and the Mysterions”,则需要对 '?' 字符进行编码。

所有要进行网址编码的字符都会使用一个 '%' 字符和一个与其 UTF-8 字符对应的两个字符的十六进制值进行编码。例如,UTF-8 中的 上海+中國 在进行网址编码后将变为 %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B。字符串 ? and the Mysterians 在进行网址编码后将变为 %3F+and+the+Mysterians%3F%20and%20the%20Mysterians

需要编码的常见字符

以下是一些必须进行编码的常见字符:

不安全的字符 编码值
空格键 %20
" %22
< %3C
> %3E
# %23
% %25
| %7C

转换您通过用户输入获取的网址有时颇为棘手。例如,用户可能会输入“5th&Main St.”这样的地址。一般而言,您应该根据网址的组成部分进行构建,将所有用户输入都视为原义字符。

此外,对于所有的 Google Maps Platform 网络服务 API 或静态网络 API,网址最多可包含 8192 个字符。对于大多数服务,很少出现接近这一字符数限制的情况。但请注意,某些服务具有的若干参数可能会导致网址较长。

合理使用 Google API

设计不当的 API 客户端可能会在互联网和 Google 服务器上产生不必要的负载。本部分包含 API 客户端的一些最佳做法。遵循这些最佳做法有助于避免您的应用因意外滥用 API 而遭到屏蔽。

指数后退

在极少数情况下,您的请求可能会出错;您可能会收到 4XX 或 5XX HTTP 响应代码,或者 TCP 连接可能会在客户端与 Google 服务器之间的某处失败。通常,值得重试该请求,因为原始请求失败时后续请求可能会成功。但是,不要简单地重复向 Google 的服务器发出请求。这种循环行为可能会导致您的客户端和 Google 之间的网络过载,从而导致多方出现问题。

更好的方法是在两次尝试之间的间隔时间增加时重试。通常,每次尝试的延迟时间都会乘以乘数因子,这种方法称为指数退避算法

例如,假设有一个应用希望向 Time Zone API 发出此请求:

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

下面的 Python 示例显示了如何通过指数后退发起请求:

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}")

您还应注意,应用调用链中不存在导致快速连续重复请求的重试代码。

同步请求

对 Google API 的大量同步请求可能看起来像是对 Google 基础架构的分布式拒绝服务 (DDoS) 攻击,并对此进行了相应处理。为避免这种情况,您应该确保 API 请求未在客户端之间同步。

例如,假设某个应用显示当前时区的时间。该应用可能会在客户端操作系统中设置警报,并在分钟开始时唤醒该操作系统,以便更新显示的时间。在与警报相关联的处理过程中,应用不应进行任何 API 调用。

发出 API 调用来响应固定的闹钟是坏的做法,因为这会导致 API 调用与分钟开始时间同步(即使在不同设备之间),而不是在一段时间内均匀分布。一个设计不佳的应用执行此操作会导致每分钟开始时流量出现正常水平 60 倍。

正确的做法是,将第二个闹钟设置为随机选择的时间。当第二个闹钟触发时,应用会调用所需的任何 API 并存储结果。如果应用想要在分钟开始时更新其显示,它会使用之前存储的结果,而不是再次调用 API。使用这种方法,API 调用会在一段时间内均匀分布。此外,更新显示屏时,API 调用不会延迟渲染。

除了分钟开始之外,您应该注意不要定位的其他常见同步时间是在小时开始时以及每天午夜时分。

处理响应

此部分介绍如何以动态方式从 Web 服务响应中提取这些值。

Google 地图网络服务提供的响应易于理解,但并非完全易用。执行查询时,您可能希望提取一些特定值,而不是显示一组数据。通常,您需要解析网络服务的响应并仅提取您感兴趣的值。

具体使用何种解析方案取决于您是否以 JSON 格式返回输出结果。JSON 响应(已经采用 JavaScript 对象的形式)可以在客户端的 JavaScript 中进行处理。