Google Maps Platform 报告

定期监控 Google Maps Platform 用量、配额和结算数据非常重要。监控这些数据有助于您跟踪项目发出的请求,避免超出预定义的使用限制,并通过计划的预算来控制费用。监控这些数据还有助于您检测您的项目和 Google Maps Platform 服务之间可能发生的任何意外交互。

Cloud Console

您可以使用 Google Cloud Console(也称为 Cloud Console)监控 Google Maps Platform 用量、配额和结算数据。

API 和服务

Cloud Console 中的 API 和服务页面会显示您已为项目启用的所有 API 的用量指标,包括:Google Maps Platform API 和 SDK,以及其他 Google API 与服务。

API 和服务

如需访问“API 和服务”页面,请执行以下操作:

  1. 打开 Cloud Console
  2. 选择项目。
  3. 点击菜单按钮 菜单,然后点击 API 和服务

Google Maps Platform

Cloud Console 中的 Google Maps Platform 页面上显示 Google Maps Platform API 和 SDK(以下统称为 Google Maps Platform API 或简称为 API)的用量和配额指标。

Google 地图信息中心

如需访问“Google Maps Platform”页面,请执行以下操作:

  1. 打开 Cloud Console
  2. 选择项目。
  3. 点击菜单按钮 菜单,向下滚动到“其他 Google 解决方案”,然后点击 Google Maps Platform

结算

Cloud Console 中的结算页面会显示您所选项目的结算及相关费用信息。

结算信息中心

如需访问“结算”页面,请执行以下操作:

  1. 打开 Cloud Console
  2. 选择项目。
  3. 点击菜单按钮 菜单,然后点击结算
  4. 如果您有多个结算帐号,请点击转至关联的结算帐号
    然后,您会转至关联的结算帐号的概览页面。
  5. 在左侧菜单中,点击报告
    然后,您会转至关联的结算帐号的结算报告页面。

用量报告

用量取决于您的项目使用与此项目相关联的凭据向 Google Maps Platform API 发出的请求数量。请求包括成功请求、导致服务器错误的请求以及导致客户端错误的请求。凭据包括 API 密钥和客户端 ID(适用于高级计划项目和迁移后的高级计划项目)。

用量指标以表格(请求、错误和延迟时间)和图表(流量、错误和延迟时间)的形式显示。为方便您进行跟踪:

  • 所有 API 的用量指标都可以按时间段和 API 过滤;您还可以看到按响应代码、API 和凭据分组的流量、错误和延迟时间。
  • 特定 API 的用量指标可以按时间段以及 API 的版本、凭据和方法过滤;您还可以看到按响应代码、API 方法与版本以及凭据分组的流量、错误和延迟时间。

API 和服务“信息中心”页面

API 和服务下的信息中心页面简要列出了您已为项目启用的所有 API(Google Maps Platform API 以及其他 API 和服务)的用量指标。

“信息中心”页面显示了三个图表和一个表格。您可以选择一个时间段(从 1 小时到过去 30 天)来过滤图表和表格中显示的用量。

“流量”图表按 API 显示每秒查询次数 (QPS) 的用量。“错误”图表按 API 显示导致错误的请求所占的百分比。“延迟时间”图表按 API 显示请求的延迟时间中位数。

图表下方有一个表格,其中列出已启用的 API 和服务。请求数是指所选时间段内的请求数量。错误数是指这些请求中导致错误的请求数量。延迟时间(延迟中位数和百分位数)是指这些请求的延迟时间。

如需了解详情,请参阅监控 API 使用量

监控 API

Google 地图“概览”页面

Google 地图下的概览页面包含一个表格,其中列出已启用的 API 以及过去 30 天内的使用请求数。“请求(按 API)”也能以图表形式显示。结算图表显示您的当前帐单和过去 3 个月的总用量。

注意:如果您点击任意已启用 API 的名称,您将会转到该 API 的 Google 地图指标页面。

概览

Google Maps Platform“API”页面

Google 地图下的 API 页面包含两个表格。“已启用的 API”表格列出了过去 30 天内每个已启用 API 的请求数、错误数和平均延迟时间。“其他 API”表格列出了尚未启用的 API(因此,不会报告任何用量)。

注意:如果您点击任意已启用 API 的名称,您将会转到该 API 的 Google 地图指标页面。

apis

Google 地图“指标”页面

Google 地图“指标”页面会显示三个图表:“流量”、“错误”和“延迟时间中位数”。图表中的使用情况数据可以按响应代码、API、API 方法或凭据分组。

在图表下方,“指标”页面包含一个 API 表格,其中显示您已选择的 API 的请求数、错误数和延迟时间。

借助顶部的 API 下拉列表和右侧窗格中的过滤选项,您可以选择特定或多个 API、凭据和/或响应代码来过滤显示的用量指标。此外,您也可以选择时间段(从 1 小时到过去 30 天)和粒度(每秒或每天)来过滤显示的用量指标。

指标

响应代码图表

“流量(按响应代码)”和“错误(按响应代码)”图表按响应代码类别划分用量。下表显示了 Google Maps Platform API 响应状态和响应代码类别之间的对应关系:

响应状态 响应代码类别
(2xx、3xx、4xx、5xx)
备注
OK 2xx 成功响应。

这是可计费请求,并会消耗配额。
OK 3xx 成功响应。

这是可计费请求,并会消耗配额。

例如,如果地点照片请求成功,则返回指向所引用图片的 302 重定向。
DATA_NOT_AVAILABLE 2xx 成功响应,表示没有可用于输入位置的数据。

这是可计费请求,并会消耗配额。
ZERO_RESULTS 2xx 成功响应没有返回任何结果。

这是可计费请求,并会消耗配额。
NOT_FOUND 2xx 对于 Directions API,这个响应状态表示请求的出发地、目的地或航点中指定的位置中至少有一个无法接受地理编码。

对于 Places API,这个响应状态表示在 Places 数据库中找不到引用的位置 (place_id)。

这是可计费请求,并会消耗配额。
INVALID_REQUEST(参数值无效)、
MAX_WAYPOINTS_EXCEEDED、
MAX_ROUTE_LENGTH_EXCEEDED 等
2xx 由参数值无效、提供的值过多等引起的错误。如需了解详情,请查看 API 响应。

这是可计费请求,并会消耗配额。
REQUEST_DENIED 4xx 由身份验证错误、访问错误等引起的客户端错误。如需了解详情,请查看 API 响应。
OVER_DAILY_LIMIT、
OVER_QUERY_LIMIT、
RESOURCE_EXHAUSTED、
rateLimitExceeded、
dailyLimitExceeded、
userRateLimitExceeded
4xx 由每个允许的时间段内请求过多而引起的客户端错误。稍后重试请求。如需了解详情,请查看 API 响应。
INVALID_REQUEST(参数无效,缺少参数,请求解析错误) 4xx 由请求无效引起的客户端错误。如需了解详情,请查看 API 响应。
NOT_FOUND (404) 4xx 对于 Geolocation API,这个响应状态表示输入的内容不足以生成位置信息估算值。

对于 Roads API,这个响应状态表示输入的内容无法与道路合理对应。

这是可计费请求,并会消耗配额。
UNKNOWN_ERROR 5xx 表示请求无法继续的服务器错误,具体原因如下:内部错误、服务过载、不可用、超时等。

如需详细了解状态代码和错误消息,请参阅您感兴趣的 API 的响应文档(例如,地理编码响应路线响应)。

Google Maps Platform 解决方案参数

Google Maps Platform 提供了许多类型的示例代码,可帮助您快速上手。例如,您可以使用 Cloud Console 中的快速构建器、按照行业解决方案实施指南进行操作,以及通过 Codelab 学习。

为了了解代码使用情况和改善解决方案的方法,Google 在 API 调用中添加了 solution_channel 查询参数,用于收集与示例代码使用情况相关的信息:

  • 默认情况下,solution_channel 查询参数包含在解决方案示例代码中。
  • 此查询参数会将经过匿名化处理的解决方案采用情况分析数据返回到 Google,以便在未来的版本中提高解决方案质量。
  • 从示例代码中删除 solution_channel 查询参数及其值即可将其停用。
  • 无需保留此查询参数,将其移除不会影响性能。
  • 此查询参数仅用于示例代码使用情况报告。
  • 此查询参数独立于任何 API 特定的分析和报告。也就是说,从解决方案示例代码中移除此参数将不会停用内部 Maps JavaScript API 报告。

配额报告

您可以根据配额针对您的项目向 Google Maps Platform API 发出的请求数设置限制。您可以通过以下三种方式限制请求数:每天请求数、每秒请求数和每位用户每秒的请求数。只有成功请求和导致服务器错误的请求才会计入配额。未通过身份验证的请求不计入配额。

配额用量以图表形式显示在 Cloud Console 的配额页面中,可以按每分钟的请求分组。所选 API 的当前配额限制以表格形式显示在配额用量图表下方。

使用此计算器可获取任意 GMP API 产品的每分钟配额值。

Google 地图“配额”页面

Google 地图下的配额页面会显示所选特定 API 的配额限制和配额用量。

Google Cloud Console 中的配额用量图表显示了 API 密钥和客户端 ID 的总流量。客户端 ID 流量还会显示在 Cloud Console 的“指标”图表中。如需了解详情,请参阅问题 158809616

该页面仅显示会消耗配额的请求:成功请求(OK、ZERO_RESULTS、DATA_NOT_AVAILABLE)和导致服务器错误的请求(NOT_FOUND、INVALID_VALUE、UNKNOWN_ERROR)。

导致客户端错误(身份验证/授权/无效参数错误,响应状态为 REQUEST_DENIED、OVER_QUERY_LIMIT、INVALID_REQUEST)的请求不会消耗配额,因此不会显示在该页面上。

对于大多数 Google Maps Platform API(Static Maps API、Street View Static API、Geocoding API、Directions API、Places API、Timezone API、Geolocation API 和 Elevation API)而言,配额单元是一个请求。但也有一些例外情况:

  • 对于 Distance Matrix API,配额单元是一个元素,即“出发地-目的地”对。
  • 对于 Maps JavaScript API,配额单元是一次地图加载。
  • 对于 Maps SDK for Android 和 Maps SDK for iOS,配额单元是一次街景请求/全景图片加载(地图加载免费且不会消耗配额)。
配额

配额单元

下表显示了 Google Maps Platform API 对应的配额单元。

Google Maps Platform API 配额单元
地图
Maps SDK for Android 1 张全景图片
Maps SDK for iOS 1 张全景图片
Maps Static API 1 个请求
Maps JavaScript API 1 次地图加载
Street View Static API 1 个请求
Maps Embed API 1 次地图加载
路线
Directions API 1 个请求
Distance Matrix API 1 个元素(“出发地-目的地”对)
Roads API 1 个请求
地点
Places API 1 个请求
Geocoding API 1 个请求
Geolocation API 1 个请求
Time Zone API 1 个请求

结算报告

查看您的结算报告

您可以在 Google Cloud Console 中查看您使用的 Google Maps Platform 产品的结算报告(请参阅结算)。

如何解读结算报告图表

结算报告采用堆叠折线图表示一段时间内的费用。默认视图显示所有产品当月每天与用量相关的费用,按项目分组,已用的任何与用量相关的赠金包含在内,还显示当月的预测总费用。图表中的每条线(以及摘要表格中的每一行)均与项目对应,按费用从高到低排序。详细了解如何解读结算报告图表

结算报告
图 1:采用默认预设视图显示图表和表格的结算报告。

提示:按 SKU 分析用量和费用

为了更准确地了解随用随付定价模式的详细信息以及这种模式对您的实现的影响,请按 SKU 查看您的用量和费用

按 SKU 分组的结算报告
图 2:按 SKU 显示用量和费用专列项的结算表格。
结算报告过滤条件
图 3:结算报告过滤条件。
如需将报告视图更改为按 SKU 显示专列项,请执行以下操作:
  1. 在图表右侧的面板中,展开分组依据过滤条件。
  2. 选择 SKU

其他可用的结算报告过滤条件包括时间范围项目产品SKU位置,可让您根据 API 请求来源进行过滤。

除了产品之外,若要对使用来源进行分类,您可以按照列出的其中一个值将结算报告分组。与 Google Maps Platform API 相关的三个密钥如下:goog-maps-api-key-suffix(API 密钥的最后四个字符)、goog-maps-platform-type(平台:Android、iOS、JavaScript 或 webservice),以及 goog-maps-channel(API 查询中的一组数字渠道值)。详细了解过滤和分组

您可以取消选中右侧面板中的将赠金纳入费用复选框,将图表视图更改为不包含与用量相关的赠金。

监控和限制用量

为了帮助您规划预算并控制费用,您可以执行以下操作:

  • 设置预算提醒,以跟踪支出是如何达到特定金额的。设置预算不会限制 API 的使用,它只会在支出金额接近指定金额时提醒您。
  • 限制每日 API 用量,以管理可计费 API 的使用费。通过设置每日请求数上限,您可以限制支出。使用简单的等式即可确定每日请求数上限,上限取决于您希望支出的金额。例如:(每月支出/每个 SKU 的价格)/30 = 每日请求数上限(针对一个 API)。请注意,您的实现可能会使用多个可计费的 API,因此请根据需要调整等式。请记住,每月会获得 200 美元的 Google Maps Platform 赠金,因此计算时务必考虑到这一点。

按渠道跟踪用量

若要通过数字渠道跟踪用量,您必须在 API 请求中添加 'channel' 参数。对于渠道值,只接受 0-999 之间的数字。以下是几个例子:

  • Geocoding Web Service API

    https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY&channel=1
  • Maps JavaScript API

    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&channel=2&callback=initMap"
    async defer></script>

您可以在结算报告中直接监控渠道的用量。渠道在标签下反映为“键”:goog-maps-channel

按标签过滤
图 4:按 SKU 和渠道过滤
如需按 SKU 和渠道过滤结算报告,请执行以下操作:
  1. 分组依据中选择 SKU 作为过滤条件。
  2. 点击标签插入符号。
  3. 点击下拉菜单,然后选择 goog-maps-channel
  4. 点击下拉菜单,然后选择要作为过滤条件的数字渠道。

若要查看每个渠道产生的费用,可以在“分组依据”下的“标签键”中选择:goog-maps-channel

在请求中添加渠道的用量数据后,可能需要等待一段时间(最多 24 小时)才会反映在您的结算报告中。

使用 BigQuery 导出结算数据

您还可以将结算数据导出到 BigQuery

借助 BigQuery Export,您可以将详细的 Cloud Billing 每日数据(例如用量和费用估算数据)自动导出到您指定的 BigQuery 数据集内。然后,您可以通过 BigQuery 访问自己的结算数据,以进行详细分析。这可让您更详细地了解 Google Maps Platform 用量的来源。

如果您想开始使用 BigQuery Export 并查询数据,可以试用下面的示例查询。在运行此查询之前,您必须执行以下操作:

  • 为您的帐号启用结算和 BigQuery 结算导出功能。
  • 表格格式为 PROJECT_ID.DATASET_NAME.gcp_billing_export_v1_BILLING_ACCOUNT_ID,其中:
    • PROJECT_ID 是您的实际项目 ID(例如“my-project-123456”)。
    • DATASET_NAME 是您创建的数据集的名称(例如“SampleDataSet”)。
    • BILLING_ACCOUNT_ID 引用了您的结算帐号 ID,带有“gcp_billing_export_v1_”前缀,并将短划线 (-) 更改为下划线 (_)。例如,结算帐号 ID 123456-7890AB-CDEF01 将变为 gcp_billing_export_v1_123456_789AB_CDEF01

注意:创建新数据集时,它会立即显示在界面中,但用于查询的表不会显示。该表将在几小时后自动生成。然后,您需要等待大约 24 小时才能看到自己的数据。您的 BigQuery 数据集仅反映自您设置结算导出之日起所产生的用量和费用数据。换句话说,结算数据不会追溯添加,因此您不会看到启用 BigQuery Export 之前的结算数据。

  #standardSQL
  SELECT   Date(usage_start_time, "America/Los_Angeles") AS billing_day,
           invoice.month                                 AS invoice_month,
           service.description                           AS service,
           sku.description                               AS sku,
           (
                  SELECT l.value
                  FROM   Unnest(labels) AS l
                  WHERE  l.KEY = 'goog-maps-channel' ) AS goog_maps_channel,
           Round(Sum(usage.amount), 2)                 AS usage_amount,
           usage.unit                                  AS usage_unit,
           Round(Sum(cost), 2)                         AS cost,
           cost_type,
           currency
  FROM     `PROJECT_ID.DATASET_NAME.gcp_billing_export_v1_BILLING_ACCOUNT_ID`
  WHERE    invoice.month = '202002' -- Change the invoice month with the same format as the example.
  GROUP BY billing_day,
           invoice_month,
           service,
           sku,
           goog_maps_channel,
           usage_unit,
           cost_type,
           currency
  ORDER BY billing_day,
           service,
           sku
  

Cloud Billing:

Google Maps Platform:

响应状态和报告

下表列出了响应状态和响应代码类别,并表明相应请求是否会显示在用量、配额和/或结算报告中。

响应状态 响应代码类别
(2xx、3xx、4xx、5xx)
用量报告 配额报告 结算报告
OK 2xx、
3xx
ZERO_RESULTS、
DATA_NOT_AVAILABLE、
NOT_FOUND
2xx
INVALID_REQUEST(参数值无效)、
MAX_WAYPOINTS_EXCEEDED、
MAX_ROUTE_LENGTH_EXCEEDED
2xx
REQUEST_DENIED 4xx
OVER_DAILY_LIMIT、
OVER_QUERY_LIMIT、
RESOURCE_EXHAUSTED、
dailyLimitExceeded、
rateLimitExceeded、
userRateLimitExceeded
4xx
INVALID_REQUEST(参数无效、请求解析错误) 4xx
NOT_FOUND(Geolocation API 和 Roads API) 4xx
UNKNOWN_ERROR 5xx