Google Cloud Monitoring API 如何查询 Distance Matrix elements？

2026-10-24支付小周

结论

serviceruntime.googleapis.com/api/request_count 统计的是请求次数，不能据此换算 Distance Matrix 的 elements 数量。

Cloud Monitoring 并不存在一个适用于所有项目、能够直接表示“Distance Matrix element count”的固定 metric.type。应查询 Service Runtime 的配额用量指标：

serviceruntime.googleapis.com/quota/rate/net_usage

再使用 resource.labels.service 和 metric.labels.quota_metric 筛选 Distance Matrix 的 element 配额。quota_metric 的实际值需要从项目返回的时序数据或配额配置中确认，不要根据名称直接硬编码。

如果要核对最终账单，应以 Cloud Billing 导出到 BigQuery 的数据为准。Monitoring 的配额用量更适合监控和预估当月用量。

为什么请求数不等于 elements

一次 Distance Matrix 请求处理的 elements 数量为：

elements = origins 数量 × destinations 数量

例如，一个请求包含 4 个 origins 和 6 个 destinations，则会处理：

4 × 6 = 24 elements

因此，下面的指标统计的是请求数：

metric.type="serviceruntime.googleapis.com/api/request_count"

如果把结果命名为 total_elements，不仅容易引起误解，也无法准确估算费用。

第一步：找出项目中的 element 配额标签

先查询 Distance Matrix 服务产生的 quota time series，并打印相关标签：

from google.cloud import monitoring_v3
from google.oauth2 import service_account
import datetime

credentials = service_account.Credentials.from_service_account_file(
    GCP_MONITOR_KEY
)
client = monitoring_v3.MetricServiceClient(credentials=credentials)

project_name = f"projects/{GCP_PROJECT_ID}"

now = datetime.datetime.now(datetime.timezone.utc)
start_time = now - datetime.timedelta(days=7)

interval = monitoring_v3.TimeInterval(
    start_time=start_time,
    end_time=now,
)

results = client.list_time_series(
    request={
        "name": project_name,
        "filter": (
            'metric.type="serviceruntime.googleapis.com/quota/rate/net_usage" '
            'AND resource.type="consumed_api"'
        ),
        "interval": interval,
        "view": monitoring_v3.ListTimeSeriesRequest.TimeSeriesView.HEADERS,
    }
)

for series in results:
    service = series.resource.labels.get("service")
    quota_metric = series.metric.labels.get("quota_metric")
    quota_name = series.metric.labels.get("quota_name")

    if (
        "distance" in str(service).lower()
        or "matrix" in str(quota_metric).lower()
        or "element" in str(quota_metric).lower()
    ):
        print({
            "service": service,
            "quota_metric": quota_metric,
            "quota_name": quota_name,
            "metric_labels": dict(series.metric.labels),
            "resource_labels": dict(series.resource.labels),
        })

找到与 Distance Matrix elements 对应的值后，记录这两个标签：

resource.labels.service
metric.labels.quota_metric

这些标签可能因 API 后端、项目配置或 Google Maps Platform 的产品迁移而异，应以项目实际返回的数据为准。

第二步：统计当月 element 配额用量

把上一步找到的标签填入下面的代码：

from google.cloud import monitoring_v3
from google.oauth2 import service_account
import datetime

credentials = service_account.Credentials.from_service_account_file(
    GCP_MONITOR_KEY
)
client = monitoring_v3.MetricServiceClient(credentials=credentials)

project_name = f"projects/{GCP_PROJECT_ID}"

# 使用项目中实际发现的标签值
DISTANCE_MATRIX_SERVICE = "YOUR_SERVICE_LABEL"
DISTANCE_MATRIX_ELEMENT_QUOTA = "YOUR_ELEMENT_QUOTA_METRIC_LABEL"

now = datetime.datetime.now(datetime.timezone.utc)
start_of_month = now.replace(
    day=1,
    hour=0,
    minute=0,
    second=0,
    microsecond=0,
)

interval = monitoring_v3.TimeInterval(
    start_time=start_of_month,
    end_time=now,
)

filter_string = (
    'metric.type="serviceruntime.googleapis.com/quota/rate/net_usage" '
    'AND resource.type="consumed_api" '
    f'AND resource.labels.service="{DISTANCE_MATRIX_SERVICE}" '
    f'AND metric.labels.quota_metric="{DISTANCE_MATRIX_ELEMENT_QUOTA}"'
)

results = client.list_time_series(
    request={
        "name": project_name,
        "filter": filter_string,
        "interval": interval,
        "view": monitoring_v3.ListTimeSeriesRequest.TimeSeriesView.FULL,
    }
)

total_elements = 0

for series in results:
    for point in series.points:
        value = point.value

        # 当前指标通常返回 int64；保留 double 兼容处理
        if value.int64_value:
            total_elements += value.int64_value
        elif value.double_value:
            total_elements += value.double_value

print(f"Distance Matrix elements this month: {total_elements:,.0f}")

如果 quota/rate/net_usage 是 DELTA 类型的配额消费指标，可以对查询区间内的点求和。实际使用前，建议通过 Metric Descriptor 检查它的 metric_kind 和 value_type，避免直接累加 GAUGE 或 CUMULATIVE 指标。

时区需要单独处理

示例以 UTC 月初作为起点：

now = datetime.datetime.now(datetime.timezone.utc)

如果费用报表按照特定账单时区划分月份，需要先在该时区计算月初，再转换为 UTC。例如，使用 Asia/Shanghai 时区：

from zoneinfo import ZoneInfo
import datetime

billing_tz = ZoneInfo("Asia/Shanghai")
now_local = datetime.datetime.now(billing_tz)
start_local = now_local.replace(
    day=1,
    hour=0,
    minute=0,
    second=0,
    microsecond=0,
)

now = now_local.astimezone(datetime.timezone.utc)
start_of_month = start_local.astimezone(datetime.timezone.utc)

否则，月初附近的数据可能会被计入相邻月份。

费用估算的注意事项

不要直接套用统一的“免费 10,000 elements，超出后每 1,000 elements 固定收费”公式，除非它确实适用于当前账号、SKU 和合同价格。实际费用还可能受这些因素影响：

请求属于基础还是高级计费 SKU；
不同 SKU 的单价和阶梯价格；
月度抵扣、促销额度或企业合同折扣；
无效请求、失败请求和配额消费的计费处理差异；
Distance Matrix API 与 Routes API 的产品及 SKU 差异；
价格或免费额度调整。

因此，Monitoring 可以用于统计“处理了多少配额单位”，但这个数字不一定与最终的 billable units 完全一致。

如需准确核算月费，应启用 Cloud Billing 导出到 BigQuery，并按 Maps Platform 的 SKU 汇总：

SELECT
  sku.description,
  SUM(usage.amount) AS usage_amount,
  usage.unit,
  SUM(cost) AS gross_cost,
  SUM(
    cost + IFNULL(
      (SELECT SUM(c.amount) FROM UNNEST(credits) AS c),
      0
    )
  ) AS net_cost
FROM `PROJECT_ID.DATASET_ID.gcp_billing_export_v1_BILLING_ACCOUNT_ID`
WHERE service.description = "Google Maps Platform"
  AND usage_start_time >= TIMESTAMP("2026-08-01")
  AND usage_start_time < TIMESTAMP("2026-09-01")
GROUP BY sku.description, usage.unit
ORDER BY net_cost DESC;

建议使用 quota/rate/net_usage 监控当月 elements，再通过 Billing Export 核对实际 SKU、抵扣和应付金额。